Cluster Roles, Primaries/Secondaries or Current Topology Concepts, Consensus, Quorum, and Write Availability

AtlasMart is preparing a flash-sale launch. A single Neo4j process can preserve ACID correctness, but one host failure would make the graph unavailable. The platform team asks for “three replicas plus a read replica.” That phrase sounds simple but hides the central design question: which copies are allowed to participate in committing writes, how many acknowledgements are required, and what happens when one copy disappears? Current Neo4j answers those questions per database, not per server.

Learning outcomes

Lab baseline and scope

AtlasMart remains the same customer/order/product graph used throughout earlier chapters. This chapter changes deployment topology, not business identity. The optional licensed topology uses a separate database name atlasmart on disposable test infrastructure so cluster administration cannot damage the single-server continuity database.

1. The topology belongs to the database

In modern Neo4j, a cluster is a pool of servers that can host allocations for many databases. The labels primary and secondary describe a copy of one database. Server 01 might host the writer primary for atlasmart, a follower primary for another database, and no copy of a third. This is why old mental models that call machines “Core servers” or “read replicas” permanently are misleading for current releases.

2. One writer, multiple voting primaries

Neo4j uses Raft for the write-consensus group of each database. One primary is elected leader/writer. It orders transactions and synchronously replicates the corresponding log entries to enough primaries for the fault-tolerance contract. A client does not choose an arbitrary primary and create an independent write history. Routing directs writes to the current writer, and if leadership changes the routing view must converge on the new writer.

3. Quorum mathematics determines write availability

For N primaries, a simple majority is floor(N/2)+1. A three-primary database therefore needs two live primaries to continue fault-tolerant writes; a five-primary database needs three. A single-primary database needs its only primary: there is no automatic write-failover tolerance if that allocation fails.

from math import floor

SCENARIOS = [
    (1, 0), (1, 1),
    (3, 0), (3, 1), (3, 2),
    (5, 1), (5, 2), (5, 3),
]

for primaries, failed in SCENARIOS:
    majority = floor(primaries / 2) + 1
    alive = primaries - failed
    print({
        "primaries": primaries,
        "failed": failed,
        "alive": alive,
        "majority": majority,
        "write_available": alive >= majority,
    })

4. Primaries and secondaries solve different problems

A secondary receives database changes asynchronously. That is useful for read scaling and can reduce read load on primaries, but it does not vote in write consensus. Therefore 1 primary + 2 secondaries gives three copies yet still loses write availability when the single primary is unavailable. This is the chapter’s first deliberately misleading architecture.

5. Optional licensed cluster setup and evidence

The following is intentionally separated from the mandatory Community path. It assumes a licensed, isolated Enterprise 2026.07.1 test cluster. Do not copy the addresses to a public network; production cluster links need deliberate TLS/intra-cluster security, DNS and firewall design.

# OPTIONAL LICENSED LAB — illustrative per-server neo4j.conf fragments.
# Use distinct resolvable addresses in an isolated Enterprise 2026.07.1 test environment.
# On server01, server02, server03 (system primaries):
server.default_listen_address=0.0.0.0
server.default_advertised_address=server01.example.test   # change per server

dbms.cluster.discovery.resolver_type=LIST
dbms.cluster.endpoints=server01.example.test:6000,server02.example.test:6000,server03.example.test:6000,server04.example.test:6000
server.cluster.system_database_mode=PRIMARY
initial.dbms.default_primaries_count=3
initial.dbms.default_secondaries_count=0

# On server04 use its own advertised address. It may join with NONE modeConstraint
# and later host a secondary allocation for atlasmart.

:use system
CREATE DATABASE atlasmart TOPOLOGY 3 PRIMARIES 1 SECONDARY;
SHOW DATABASE atlasmart YIELD
  address, role, writer, currentStatus,
  currentPrimariesCount, currentSecondariesCount,
  requestedPrimariesCount, requestedSecondariesCount,
  replicationLag
RETURN * ORDER BY role, address;

6. Controlled failure reasoning before touching a server

Before stopping anything, predict the outcome. In a 3P+1S topology: losing the secondary should not change write quorum; losing one primary should retain a 2-of-3 majority; losing a second primary should remove the majority and therefore write availability. Reads may still be possible from surviving allocations, but “readable” is not the same as “healthy for writes.”

7. Replication is not backup

All cluster copies can faithfully replicate a bad write, an accidental delete, compromised credentials, or application corruption. They can also share a common infrastructure disaster. Chapter 16’s off-host/immutable backup and isolated restore evidence therefore remains mandatory even after HA is introduced.

8. AtlasMart verification checklist

• Can you name the writer by database rather than by permanent server?
• Can you calculate the majority from requested/current primary counts?
• Can you explain why secondaries do not increase write quorum?
• Can you prove topology with SHOW DATABASE ... YIELD * rather than process count?
• Can you identify the backup evidence that remains independent of all cluster copies?

Production judgment

Summary and next step

You can now explain current Neo4j HA from database topology and quorum rather than server labels. Lesson 2 follows a real client request through discovery, the routing table, leadership changes, read scaling and bookmarks.

Authoritative references

• Current Neo4j versions — Current Neo4j 2026.07.1, 5.26.30 LTS, Cypher Shell and GDS release snapshot.
• Clustering architecture — Current server/database decoupling, primaries, secondaries, majority writes, and causal consistency.
• Deploy a basic cluster — Current discovery/bootstrap configuration and TOPOLOGY examples.
• Cluster server discovery — LIST/DNS/Kubernetes discovery and the current discovery-service model.
• Leadership, routing, and load balancing — Per-database Raft leadership, routing tables, readers/writers/routers, and routing policy.
• Managing databases in a cluster — Primary/secondary allocation and topology changes.
• Managing servers in a cluster — Server enablement, constraints, deallocation, removal, and operational lifecycle.
• Server management command syntax — SHOW/ENABLE/ALTER/DEALLOCATE/REALLOCATE/DROP server commands.
• Show databases — Role, writer, allocation counts, replication lag, and database-state evidence.
• Monitor databases in a cluster — SHOW DATABASES-based per-allocation monitoring and status interpretation.
• Resilient multi-data-center cluster — Failure-domain placement, latency/fault-tolerance tradeoffs, and recommended/anti-pattern layouts.
• Cluster disaster recovery — Recovery when allocations or whole failure domains are lost.
• Built-in procedures — Current routing, cordon, deallocation and related procedure names/deprecations.
• Python driver transactions/routing — Read/write routing and explicit database selection in the official driver.
• Python driver bookmarks — Bookmark propagation and causal-consistency coordination across sessions.