Server Discovery, Routing, Leader Changes, Read Scaling, and Causal Consistency Expectations

AtlasMart’s API is now pointed at a cluster. The team asks whether clients should pin the writer hostname, load-balance Bolt connections themselves, or send all reads to the nearest secondary. All three shortcuts can fail. A routing-aware official driver starts from one or more reachable addresses, obtains the database’s current routing table, sends writes to the writer, sends eligible reads to reader endpoints, and refreshes topology as leadership or membership changes.

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. Discovery answers “who is in the cluster?”

A server joining a cluster needs contact points so it can discover topology. Current Neo4j supports resolver strategies including explicit lists, DNS and Kubernetes services. The discovery service continuously exchanges topology information after bootstrap. Discovery endpoints are cluster-internal membership plumbing; an application should not use that list as an improvised read/write load balancer.

# Current LIST discovery shape on each licensed server.
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

# DNS and Kubernetes resolver types are alternatives when appropriate.
# Discovery finds cluster members; it is not the same thing as driver routing.

2. Routing answers “where should this transaction go?”

The routing table is database-specific and contains endpoint capabilities: writers, readers and routers. There is usually one writer. Readers can include secondaries and, depending on routing configuration and topology, non-writer primaries. Routers are endpoints that can answer routing discovery. The table has a TTL, so the driver caches it for a bounded period and also refreshes when failures/topology changes invalidate its view.

:use system
CALL dbms.routing.getRoutingTable({}, 'atlasmart')
YIELD ttl, servers
RETURN ttl, servers;

3. neo4j:// and access mode express routing intent

For a cluster, use a routing-aware neo4j:// URI with the official driver. bolt:// is a direct connection to one address and is useful for deliberate direct-server operations, but it does not provide the same client-side routing behavior. In the Python driver, execute_query() defaults toward writers; read-only calls should explicitly request read routing when appropriate.

from neo4j import GraphDatabase, RoutingControl

URI = "neo4j://server01.example.test:7687"   # routing-aware scheme
AUTH = ("atlasmart_app", "<synthetic-test-secret>")

with GraphDatabase.driver(URI, auth=AUTH) as driver:
    driver.verify_connectivity()

    # Writes are routed to the current writer.
    records, summary, keys = driver.execute_query(
        """
        MERGE (m:HaMarker {markerId: $id})
        SET m.updatedAt = datetime()
        RETURN m.markerId AS id
        """,
        id="HA-TRACE-17",
        database_="atlasmart",
    )

    # Explicitly request read routing for read-only work.
    records, summary, keys = driver.execute_query(
        "MATCH (m:HaMarker {markerId:$id}) RETURN m.markerId AS id",
        id="HA-TRACE-17",
        database_="atlasmart",
        routing_=RoutingControl.READ,
    )

4. Leadership changes are normal, not exceptional architecture

If the writer stops or becomes unsuitable, another primary can be elected as long as quorum exists. The database writer can therefore move between servers. A robust driver refreshes routing and managed transactions may retry classified transient failures. Your code must not cache “server02 is the writer” in configuration or DNS.

5. Read scaling introduces a freshness decision

Secondaries replicate asynchronously, so they can lag. That is often acceptable for product browse analytics, but not necessarily for “place order, immediately fetch the order from another session.” A bookmark represents a committed causal state. Passing or managing the bookmark causes later work to wait until that state is available on the chosen server. This is causal coordination, not a promise that all concurrent global operations are serialized.

from neo4j import GraphDatabase, RoutingControl

URI = "neo4j://server01.example.test:7687"
AUTH = ("atlasmart_app", "<synthetic-test-secret>")

with GraphDatabase.driver(URI, auth=AUTH) as driver:
    # execute_query uses the driver's bookmark manager by default.
    driver.execute_query(
        "MERGE (:HaMarker {markerId:$id})",
        id="HA-CAUSAL-17",
        database_="atlasmart",
    )

    # Causally chained: this read waits as needed for the represented state.
    rows, summary, keys = driver.execute_query(
        "MATCH (m:HaMarker {markerId:$id}) RETURN m.markerId AS id",
        id="HA-CAUSAL-17",
        database_="atlasmart",
        routing_=RoutingControl.READ,
    )

6. Deterministic routing trace

Without an Enterprise cluster, practice the state machine instead of inventing output. Start with the following trace and answer where each request should go.

7. Optional licensed evidence capture

:use system
SHOW DATABASE atlasmart YIELD address, role, writer, currentStatus, replicationLag RETURN * ORDER BY address;
CALL dbms.routing.getRoutingTable({}, 'atlasmart') YIELD ttl, servers RETURN ttl, servers;

8. Verification checklist

• Discovery settings are not used as application routing logic.
• The application uses a routing-aware URI and one maintained driver.
• Reads explicitly request read routing when stale-tolerant/read-only.
• Bookmarks are applied only where causality requires them and their latency cost is measured.
• Leader change evidence correlates database state, routing table, driver retry and business invariant.

Production judgment

Summary and next step

Routing makes topology changes survivable to clients, but only if failure domains and quorum are sound. Lesson 3 moves from individual server loss to zones, regions and network partitions.

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.