Migrate from RushDB 2.x

RushDB 2.x was an application platform on top of Neo4j. RushDB 3 is a database engine of its own; RushDB Cloud runs it, and it is the part of RushDB you can self-host. What you do depends on how you run RushDB today.

You run	What to do
RushDB Cloud	Nothing for your data: RushDB moves Cloud projects to the RushDB 3 engine. Upgrade your SDK and MCP server to 3.x (below).
A self-hosted RushDB 2.x platform (Docker Compose, Helm, or a template, with Neo4j)	The platform is not self-hostable in RushDB 3. Either move to RushDB Cloud, or run the RushDB 3 engine and move your data: see Upgrading from RushDB 2.x in the engine manual.
A Cloud project on your own Neo4j instance	Projects no longer connect to an external Neo4j database; every project's data lives in the RushDB engine.

---

Upgrade the SDKs

npm install @rushdb/javascript-sdk@3
pip install "rushdb>=3,<4"

Code written against the 2.x SDK keeps working on RushDB Cloud: the record, relationship, label, property, search and transaction APIs are unchanged. Review these changes:

Both SDKs

Change	What to do
Untyped detach removes every type, both ways. Without typeOrTypes, records.detach removes relationships of every type; without direction, in both directions.	Pass typeOrTypes (and direction) when you mean one kind of relationship.
Some writes are refused inside a transaction: deleting by query, detach, relationships.createMany / deleteMany, upserts and merge imports, inline vectors, property deletes. Cloud answers 400 and rolls the transaction back.	Run them outside the transaction. See Transactions.
Reads inside a transaction see committed data, not the transaction's staged writes.	Use the record a staged write returns.
query.raw runs openCypher in the engine and returns rows keyed by column, in data.records, instead of a Neo4j driver result.	Return named columns (RETURN p.name AS name); check the openCypher profile.
hops without max means up to 10 hops; "unbounded" traversal no longer exists.	Set max for deeper chains.
Project settings no longer report customDB / managedDB.	Remove code that reads them.

TypeScript

Change	What to do
Under Node, import RushDB from '@rushdb/javascript-sdk' now gets an ES module whose default export is the RushDB class (before, an ESM import received the CommonJS module object).	Drop any .default workaround.
records.findById([...ids]) searches by id (it used to post to the create endpoint).	—

Python

Change	What to do
records.find raises RushDBError when a request fails, instead of returning an empty result.	Catch RushDBError where you relied on the empty result.
ImportsAPI is removed (async import runs; no RushDB 3 server implements them).	Use records.import_json / import_csv, in batches.
Python 3.10 or newer; no runtime dependencies (requests is no longer installed).	Upgrade Python 3.8/3.9 environments.

New in 3.x

• Keyword search (records.textSearch, db.textIndexes) and hybrid search (vectorSearch({ text }), RRF or DBSF fusion).
• Named embedding indexes, and mode, ef and scoreThreshold on vector search, with a report of how it ran.
• Direct mode: the same SDK against a self-hosted engine (direct: true, engineUrl, scope), with CloudOnlyError and DirectModeError instead of silent fallbacks.

---

Upgrade the MCP server

npx -y @rushdb/mcp-server runs 3.x. With RUSHDB_API_KEY it works with RushDB Cloud as before. New in 3.x:

• Direct mode (RUSHDB_MODE=direct, RUSHDB_ENGINE_URL, RUSHDB_ENGINE_TOKEN) for a self-hosted engine, over stdio.
• New tools: listTextIndexes, createTextIndex, deleteTextIndex, textSearch, smartSearch; vectorSearch takes index, text, fusion and the other hybrid options.
• detachRelation no longer takes transactionId: a detach can't run inside a transaction.

See MCP and All MCP Tools.

---

Removed with the Neo4j platform

2.x feature	In RushDB 3
Self-hosting the platform (Docker Compose, Helm, deploy templates, rushdb/platform image)	Self-host the engine; the dashboard and AI features are RushDB Cloud
Bring-your-own Neo4j for a Cloud project	The engine stores every project
Async import runs (/imports, Python ImportsAPI)	importJson / importCsv in batches, or the engine's nested import
RUSHDB_* platform environment variables, NEO4J_* settings	The engine's configuration for a self-hosted engine