Native Neo4j dump imports

Wiki / Clients and drivers

Galactus reads offline Neo4j 4.x and 5.x .dump files directly in Rust. No Java, Neo4j installation, Docker container or conversion service is needed. The database image includes the native reader.

Use a dump created after a clean Neo4j shutdown. This reader imports the stored graph; it does not replay transaction logs or recover a crashed store. For a store needing recovery, recover it in the original Neo4j version and create a fresh offline dump first.

Use 2026.09.23-neo4j-streaming or a newer release for both the database and Explorer. Both Docker Hub images support Linux AMD64 and ARM64. Pull and recreate both services to enable streaming uploads. The original 2026.09.23-neo4j-import images predate streaming and retain the 63 MiB Explorer upload limit.

Import

Choose an empty target database in Explorer, click Import, and select .dump. Explorer shows the target and import behavior before uploading. Its file picker accepts explicit .gdb and .dump extensions. Script separately accepts Cypher text in .cypher, .cql and .txt files. .gdb snapshots retain their existing replace-and-restore behavior and licensing requirements.

From Cypher, supply a path on the database server's filesystem:

CALL gdb.neo4j.import('/data/northwind-50.dump')
YIELD format, nodes, relationships, properties, schemaImported, done
RETURN format, nodes, relationships, properties, schemaImported, done;

Or pass the file contents as a Bolt byte-array parameter:

CALL gdb.neo4j.import($dump)

Imports require write privileges and an empty graph. Existing data is never deleted. The whole graph is decoded and validated before writes begin, and all writes form one atomic statement: an invalid value, target constraint failure, or subsequent query error rolls back the import. Explicit transactions may also roll back a successful import. Normal durable commit semantics apply.

Nodes, labels, properties, directed relationships, parallel edges and self-loops are preserved. Internal Neo4j node IDs are remapped; property values named id are ordinary data and remain unchanged. Neo4j schema, constraints, indexes, users, authentication settings, transaction history and GDS projections are not imported (schemaImported is always false). Recreate the required Galactus indexes and constraints separately.

Compatibility and limits

Neo4j 3.x, block stores, high-limit stores, unknown store versions, named-zone datetime encodings, and temporal/point arrays are rejected with an error before data is written. Use a logical export for these encodings. A .dump extension alone does not imply that its store format is supported.

Explorer streams .dump uploads up to 512 MiB, including 400 MiB files, through an authenticated connection using acknowledged 1 MiB chunks. The database spools the compressed file to its writable data volume; neither the Explorer process nor an individual Bolt message buffers the complete upload. The upload progress display changes to validation/import after the browser has sent the file. The final success response means the atomic import completed.

The server permits at most four concurrent uploads/imports. Reserve up to 512 MiB of temporary disk space per active upload, plus normal database/WAL capacity. Incomplete uploads make no graph changes. Failure, abort, connection close and a 60-second receive idle timeout remove the temporary file. Uploading does not hold the target write lock. Once the upload completes, the normal executor rechecks that the target is empty and applies the import under its write lock. A failed import rolls back the statement.

Transfers are connection-owned and not resumable. If the connection is lost after the full file was submitted, the atomic import may still complete; check the target before retrying. A hard process termination can leave reserved .neo4j-upload-*.dump files in GDB_DATA; remove those only while the database server is stopped. The server-side path procedure remains available.

This streams the transfer and decompression, not the entire graph build. The decoder still bounds expanded archives to 1 GiB, Zstandard windows to 64 MiB, dynamic values to 16 MiB, token tables to 100,000 entries / 16 MiB of names per table, label names to 1 MiB per node, the graph to two million entities, and decoded logical data to a 1 GiB accounting budget. The latter is not a cap on process RSS: store buffers, decoded graph, database and transaction undo/WAL buffers also occupy memory. Large imports hold the target's write lock until completion.

Archive paths are never extracted to disk. Compression checksums, tar headers, record references, property chains, token references and relationship endpoints are checked. This is not a substitute for Neo4j's full store consistency checker.

Reverse proxies

For Explorer behind nginx, configure its import route to allow the body size, avoid request buffering, and wait for the final import result. Keep the existing upstream address and authentication settings:

client_max_body_size 512m;
proxy_request_buffering off;
proxy_http_version 1.1;
proxy_read_timeout 3600s;
proxy_send_timeout 300s;

These directives belong in the existing Explorer location block. See nginx's request buffering and body-size limit documentation. A proxy's own lower limit can still reject an upload.