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
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.
| 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 |