Clustering & multi-database

This section documents the current Neo4j 2026.x calendar-versioned line — Neo4j moved from semantic to calendar versioning (YYYY.MM) in 2025, and the same line applies to the Graph Data Science library — as published at the Neo4j documentation, which is the reference these pages are written and verified against. No specific monthly patch is pinned. Some areas (Aura’s internal infrastructure, the Raft consensus implementation details, and the GDS Pregel API’s low-level internals) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, as Neo4j iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

A Neo4j cluster replicates a database with the Raft consensus protocol among a small set of writable servers and fans out read traffic to a larger, independently scalable tier behind them. On top of that cluster, one DBMS can host many logical databases, optionally federated under a single composite database.

Raft-based clustering: server roles and leader election

Terminology change: the server roles are now called primary and secondary — these replace the legacy CORE and READ_REPLICA naming used by older Neo4j versions. A primary holds a full copy of a database and takes part in Raft voting for it; a secondary holds a copy kept in step by asynchronous catch-up but does not vote.

A Raft consensus group of three primaries — one leader and two followers — replicating to a secondary tier of two read replicas

For each database, the primaries hosting it form one Raft group:

  • One primary is elected leader for that database and is the only server that accepts writes to it; the rest are followers.

  • Every write is appended to the leader’s Raft log and must be acknowledged by a majority of the primaries in the group before it is committed — this is what keeps the database available and consistent through the loss of a minority of primaries.

  • If the leader stops heartbeating, the remaining primaries hold a Raft election and a new leader is chosen by majority vote. A client driver using neo4j:// routing discovers the new leader automatically on its next write.

  • Secondaries replicate committed transactions from the primaries asynchronously. They scale read throughput and geographic read locality without adding Raft voting overhead, and a load balancer (or driver-side routing) can steer read traffic to them while writes go to the leader.

flowchart TD L["primary (leader)"] -->|Raft log replication| F1["primary (follower)"] L -->|Raft log replication| F2["primary (follower)"] F1 -.->|majority ack required to commit| L F2 -.->|majority ack required to commit| L L -->|async catch-up| S1["secondary A"] L -->|async catch-up| S2["secondary B"] F1 -. leader unreachable: election .-> F2 F2 -. new leader elected .-> F1

See Clustering for the full server-role and topology reference, and Clustering: Lifecycle for how a server joins, leaves, and is replaced within a running cluster.

Multi-database and composite databases

A single DBMS instance (or cluster) can host several independent databases, each with its own data, schema, and — in a cluster — its own Raft group of primaries. Databases are managed with Cypher administration commands rather than a separate tool:

// Create a new database (async by default -- add WAIT to block until it comes online)
CREATE DATABASE `orders` IF NOT EXISTS WAIT;

// List every database and its per-server role/status
SHOW DATABASES YIELD name, address, role, currentStatus;

// Inspect one database in detail
SHOW DATABASE `orders` YIELD name, currentStatus, requestedStatus;

// Take a database offline, then drop it
STOP DATABASE `orders`;
DROP DATABASE `orders` IF EXISTS;

Terminology change: the current term for federating multiple databases under one virtual, queryable namespace is a composite database — this is the same capability formerly marketed as Fabric. A composite database has no data of its own; it exposes a set of constituent databases (which can live on the same DBMS or be reached over the network) as named graphs that a single Cypher query can address together.

// Create a composite database, then attach constituents to it
CREATE COMPOSITE DATABASE `analytics`;
CREATE ALIAS `analytics`.`orders` FOR DATABASE `orders`;
CREATE ALIAS `analytics`.`inventory` FOR DATABASE `inventory`;

// Query across constituents from the composite database
USE `analytics`.`orders`
MATCH (o:Order) RETURN count(o);

Aura’s managed take. Neo4j Aura provisions and operates the primary/ secondary Raft topology above for you — a Professional or Business Critical instance is backed by a managed cluster with automatic leader failover, and Aura additionally handles patching, backup scheduling, and scaling the secondary tier without exposing the underlying server administration commands. Multi-database and composite databases are available on the tiers that support them, managed through the Aura console and the same Cypher administration commands shown above rather than through any cluster-lifecycle command, since Aura owns that layer — see the Aura documentation for which capabilities each tier includes.

Related pages