Read/Write Splitter

Status: Unavailable: NexoReadWriteSplit is schema-only and the pinned Proxy does not execute the router phase.

:::caution No supported deployment contract

This capability is documented for catalog completeness, but the selected release does not publish a supported end-to-end deployment contract.

:::

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Router
Category	Routing
Canonical minimum tier	Pro
Legacy dashboard tier label	Pro
Legacy rendered name	Read/Write Splitter
Legacy rendered summary	Automatically route reads to secondaries without any driver-level changes.
Canonical entitlement	Yes
Supported deployment contract	No
Release status	Unavailable: NexoReadWriteSplit is schema-only and the pinned Proxy does not execute the router phase.

Release accuracy

• 0.2.0 Private Preview: Unavailable: NexoReadWriteSplit is schema-only and the pinned Proxy does not execute the router phase.

The detailed material below preserves every section rendered by the legacy dashboard. Where it conflicts with the release status above, the release status is authoritative. Legacy field names and examples are not a substitute for the selected bundle's CRD and runtime contract. Unsafe legacy wording is retained in metadata for traceability but is corrected in the rendered guidance.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Legacy, unverified performance claims

These numbers are preserved for documentation parity with the legacy dashboard. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Legacy claim
P50	<0.1ms
P95	<0.2ms
P99	<0.3ms

Legacy note: Command classification is a simple map lookup

Overview

The Read/Write Splitter inspects each incoming MongoDB command and routes it to the appropriate target: writes always go to the primary, while reads are distributed across secondaries using your chosen strategy.

This is transparent to the application — no readPreference configuration needed in drivers. The splitter monitors replication lag and automatically routes reads back to primary if a secondary falls too far behind.

When to use

• Offloading read traffic from primary without changing application code
• Scaling read-heavy workloads across replica set members
• Reducing latency for read operations by using geographically closer secondaries
• Gradually rolling out secondary reads with staleness guarantees

How it works

1. Incoming command is classified as read or write based on command name
2. Writes always route to primary_target
3. Reads are distributed to secondary_targets using the chosen strategy
4. Replication lag is monitored — if a secondary exceeds max_staleness, it's removed from rotation
5. Commands matching force_primary_patterns always go to primary regardless

Configuration

The table preserves the legacy dashboard field reference. “Not specified” means the legacy source did not declare required semantics.

Field	Legacy UI type	Legacy default	Required	Description
primary_target	string	—	Yes	Primary MongoDB address
secondary_targets	json	—	Not specified	List of secondary addresses
strategy	select	round_robin	Not specified	Load balancing strategy for reads
max_staleness	duration	10s	Not specified	Max acceptable replication lag
read_commands	json	[find, aggregate, count, distinct]	Not specified	Commands routed to secondaries
force_primary_patterns	json	—	Not specified	Collections that always use primary

Settings reference

The legacy page did not render an additional anchored settings reference.

Examples

Basic read scaling

steps:
  - id: builtin:read-write-split
    config:
      primary_target: mongo-primary:27017
      secondary_targets:
        - mongo-secondary-1:27017
        - mongo-secondary-2:27017
      strategy: round_robin
      max_staleness: 5s

Latency-based with exclusions

steps:
  - id: builtin:read-write-split
    config:
      primary_target: mongo-primary:27017
      secondary_targets:
        - mongo-secondary-us:27017
        - mongo-secondary-eu:27017
      strategy: latency
      max_staleness: 30s
      force_primary_patterns:
        - "^billing_"
        - "^transactions"

Best practices

• Start with a conservative max_staleness (5-10s) and increase based on your consistency requirements
• Use force_primary_patterns for collections that require read-after-write consistency
• Monitor secondary lag with the metrics step to tune staleness thresholds
• latency strategy works best with geographically distributed secondaries

Limitations

• Aggregation pipelines with $out or $merge always route to primary
• Cannot split reads within a multi-document transaction
• Staleness detection requires periodic isMaster checks (every 5s by default)

Security and operational guidance

• Validate replication lag and causal consistency
• Keep transactions and primary-required operations on the primary
• Do not infer runtime support from schema presence

Related steps

• connection-pooler
• traffic-split
• intelligent-failover

Release availability

• 0.2.0 Private Preview: Unavailable: NexoReadWriteSplit is schema-only and the pinned Proxy does not execute the router phase.

See the component catalog for the complete comparison matrix.