Unify database / graph / vector-store node naming and classType

[dsapandora]

We've been talking about cleaning up node naming, so I went digging through the nodes to figure out what a "consistent pattern" would actually look like. It really comes down to one family that never got the treatment the others did. Writing it up here so we can agree on the shape before anyone starts renaming things.

Where we already have a pattern

Two families are already consistent: a shared base class under packages/ai/src/ai/common/<family>/, a matching classType, and a <family>_ prefix.

• db_* → relational, DatabaseGlobalBase / DatabaseInstanceBase, natural language → SQL.
• graph_* → GraphGlobalBase / GraphInstanceBase (extracted in feat(nodes, ai): add graph base class; make FalkorDB a real graph node #1584, applied to Neo4j in feat(nodes): migrate neo4j onto the graph base class (graph_neo4j) #1611), NL → Cypher.

The vector databases never got this. They have no prefix, classType: ["store"], and no shared base — each one reimplements lifecycle/config/IO straight on top of the generic IGlobalTransform. That's the real inconsistency, and it's why the tree is hard to navigate.

store and database are different capabilities

The names are close enough that it's worth being explicit: they do different jobs. store is a vector database (embeddings + semantic search), database is relational/SQL. Postgres is the clearest example, since it shows up as two separate nodes, one for each:

	db_postgres	vectordb_postgres
classType	["database"]	["store"]
What it says it does	"takes structured table data and inserts it into a PostgreSQL … relational"	"enhances PostgreSQL with vector similarity search"
Giveaway config	Table name, Database name, "Allow direct query execution"	Similarity Metric, pgvector, "Vector Store"
Operations	insert tables + NL→SQL (get_data / execute)	"Add document to store" + "Search with question" (embed + similarity)
Base	DatabaseBase	IGlobalTransform

Same engine, two nodes, because they do two different things. Qdrant, Weaviate, Milvus, Pinecone, Chroma, Astra and Atlas are all store as well — their own descriptions say "A vector database component."

(Heads up while we're here: Supabase today is a variant of db_postgres, the relational one, via db_postgres/services.supabase.json.)

classType is a list of capabilities, not a single prefix

An engine can do more than one thing, so classType should carry every capability, and the name prefix should follow the primary one:

• Postgres → relational + pgvector → ["database", "store"]
• ArangoDB → graph-first, also SQL → ["graph", "database"]
• HydraDB → graph-first → ["graph", "database"]
• Qdrant / Weaviate / Milvus / Chroma / Astra / Atlas → pure vector → ["store"]

It's also why I'd push back on renaming atlas → db_atlas: Atlas is a vector db (store), not a relational database. If prefix follows family it should be vectordb_atlas, not db_. Otherwise we just trade one inconsistency for another.

What I'm proposing

Prefix = primary capability, classType = the full list.

Current node	Current classType	→ Proposed name	Proposed classType	Base class	Action
db_postgres	[database]	db_postgres	[database, store]	DatabaseBase + VectorStoreBase*	Add store; absorb vectordb_postgres
vectordb_postgres	[store]	(merge into db_postgres)	—	—	Remove / merge
db_postgres (supabase)	[database]	db_supabase	[database]	DatabaseBase	Rename only — the Supabase node is relational ingestion, not meant as a vector store
db_arango	[database]	graph_arango	[graph, database]	GraphBase + DatabaseBase	Rename + add graph base (keep SQL)
db_hydradb	[database]	graph_hydradb	[graph, database]	GraphBase + DatabaseBase	Rename + add graph base
db_mysql	[database]	db_mysql	[database]	DatabaseBase	✅ no change
db_clickhouse	[database]	db_clickhouse	[database]	DatabaseBase	✅ no change
graph_falkordb	[graph]	graph_falkordb	[graph]	GraphBase	✅ no change
graph_neo4j	[graph]	graph_neo4j	[graph]	GraphBase	✅ no change
qdrant	[store]	vectordb_qdrant	[store]	VectorStoreBase*	Rename + base
weaviate	[store]	vectordb_weaviate	[store]	VectorStoreBase*	Rename + base
milvus	[store]	vectordb_milvus	[store]	VectorStoreBase*	Rename + base
pinecone	[store]	vectordb_pinecone	[store]	VectorStoreBase*	Rename + base
chroma	[store]	vectordb_chroma	[store]	VectorStoreBase*	Rename + base
astra_db	[store]	vectordb_astra	[store]	VectorStoreBase*	Rename + base
atlas	[store]	vectordb_atlas	[store]	VectorStoreBase*	Rename + base (not db_atlas)
index_search	[store]	vectordb_elasticsearch	[store]	VectorStoreBase*	Rename + base

* VectorStoreBase doesn't exist yet. We'd extract it first, the same way GraphBase came out in #1584, before touching any of the vector nodes.

Rollout

• Every rename breaks saved pipes, so each one needs a services-version bump + upgradeComponent — same migration we did for the graph renames in feat(nodes): migrate neo4j onto the graph base class (graph_neo4j) #1611.
• Order I'd suggest: (1) extract VectorStoreBase behind the existing nodes, (2) migrate the pure vector nodes onto it with rename + upgrade, (3) unify the multi-capability engines (Postgres, Arango, HydraDB) last.
• The two multi-model ones (Arango, HydraDB) need a call on how two base classes compose on a single node before we start — that's its own little design question.

What I want to agree on

1. Prefix follows the primary capability, classType carries the full list — good?
2. Prefix for the pure vector nodes: vectordb_ (matches the existing vectordb_postgres) or store_?
3. Postgres as one node with [database, store], or keep the relational and vector nodes split? (Supabase stays relational-only — that node isn't intended as a vector db.)

If we're roughly aligned I'll start with extracting VectorStoreBase so the rest can hang off it.

[github-actions[bot]]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[dsapandora]

One caution on the migration that's easy to miss: a rename here is really two changes, and only one of them is dangerous.

The folder/class name is cosmetic. The thing saved pipes actually key off is the provider (the protocol in services.json) — that's the ID stored in every .pipe. So:

• Renaming just the node (folder/class), leaving the provider as-is → nothing breaks. Existing pipes keep resolving because their stored provider ID is unchanged. Totally safe, zero migration needed.
• Renaming the provider too (which is what makes it actually consistent — graph_falkordb:// etc.) → this breaks every saved pipe that references the old provider, and needs a services-version bump + upgradeComponent to remap them, exactly like feat(nodes): migrate neo4j onto the graph base class (graph_neo4j) #1611 did for the graph renames.

So there's a real fork in the road per node:

• Cheap + safe but unbalanced: rename the name only, keep the old provider. No pipes break, but you end up with e.g. a vectordb_qdrant node still carrying a qdrant:// provider — the inconsistency just moves down a layer instead of going away.
• Full + balanced: rename name and provider, ship the version bump + upgrade path. More work and it touches saved pipes, but it's the only way the cleanup is actually complete.

My vote is the full version for anything we rename, precisely so we don't leave a half-renamed layer behind — but if we want to stage it, the name-only step is a safe first move that breaks nothing, and we can follow with the provider + upgrade later. Just worth being explicit that the provider change is the one that carries migration risk, not the rename itself.

[dsapandora]

To keep this reviewable, I'd split it into staged PRs where the risky part (the migration) lands last and on its own. Rough shape:

PR 1 — renames only, no provider change. Just the git mv of folders + class renames to the target names in the table (qdrant → vectordb_qdrant, atlas → vectordb_atlas, db_arango → graph_arango, etc.). Providers/protocol untouched, so no saved pipe breaks and there's nothing to migrate. It touches a lot of files, but almost all of it reads as moves in the diff, so it's quick to review. Gets the names consistent immediately. (One thing to confirm here: that the node registry keys off the provider, not the folder name — which is the whole reason this is safe.)

PR 2 — extract VectorStoreBase + migrate one node. If we agree vector db is its own family, this is where it gets its own base (ai/common/vectordb/, mirroring graph/) and we migrate a single driver onto it — vectordb_qdrant is the obvious first one. Small and focused: the base + one worked example, so the pattern is easy to see and agree on. Same move as #1584 (graph base + FalkorDB).

PR 3 — migrate the rest. Weaviate, Milvus, Pinecone, Chroma, Astra, Atlas, Elasticsearch onto the base from PR 2. Bigger PR but mechanical and repetitive — every node looks like the qdrant one, so it reviews fast even though it's wide.

PR 4 — provider renames + migration. Only now touch protocol/provider in services.json so the naming is actually balanced (vectordb_qdrant:// and friends), with a services-version bump + upgradeComponent to remap saved pipes. This is the one PR that carries migration risk, and it's isolated at the end where it's easy to review carefully and easy to roll back — same upgrade path as #1611.

So the whole thing is safe and non-breaking right up until PR 4, and PR 4 is the only one a reviewer has to look at with migration in mind.

Two side notes:

• The graph-first engines (graph_arango, graph_hydradb) only get the name in PR 1. Actually adding the graph base + [graph, database] is a separate follow-up, since composing two base classes on one node is its own design question.
• Postgres unification ([database, store], absorbing vectordb_postgres) also lands after this sequence as its own PR — it depends on VectorStoreBase existing first.

Does this order work for everyone? If so I'll open PR 1 (renames only) to get the easy part out of the way.