Version Compatibility

Normalize selected MongoDB wire-protocol and metadata behavior between approved client and server versions.

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Request + response
Category	Transform
Canonical minimum tier	Free
Legacy dashboard tier label	Pro
Legacy rendered name	Version Compatibility
Legacy rendered summary	Bridge wire protocol gaps between old MongoDB clients and new servers.
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

Release accuracy

• 0.2.0 Private Preview: Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

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.15ms
P95	0.35ms
P99	0.60ms

Legacy note: Only triggers on handshake commands (hello/isMaster). For regular queries the step is a no-op pass-through (<0.01ms).

Overview

The Version Compatibility step solves one of the most painful MongoDB upgrade scenarios: your server is on 7.0/8.0 but some applications still use legacy drivers (3.6, 4.0, 4.2) that cannot be immediately upgraded.

The step intercepts hello, isMaster, and buildInfo responses from the server and patches the advertised wire protocol version to match what the connecting client expects. This allows legacy clients to successfully handshake with newer servers.

How it handles different language drivers:

The step operates at the MongoDB wire protocol level — not at the driver/language level. Every MongoDB driver (Python, Java, Node.js, Go, C#, etc.) communicates with the server using the same binary protocol (OP_MSG). What matters is which wire protocol version the driver produces:

Driver	Wire Protocol Version
PyMongo 3.x	MongoDB 3.6–4.4
PyMongo 4.x	MongoDB 5.0–7.0
Java Driver 4.x	MongoDB 4.0–5.0
Java Driver 5.x	MongoDB 6.0–7.0
Node.js Driver 5.x	MongoDB 5.0–6.0
Node.js Driver 6.x	MongoDB 7.0+
Go Driver 1.x	MongoDB 4.0–6.0
Go Driver 2.x	MongoDB 7.0+
C# Driver 2.x	MongoDB 4.4–6.0
C# Driver 3.x	MongoDB 7.0+

So if you have PyMongo 3.12 (speaks 4.4 protocol) and Java Driver 4.11 (speaks 5.0 protocol) both connecting to a MongoDB 7.0 server, configure client versions as ["4.4", "5.0"] and server version as ["7.0"]. Nexo handles both transparently regardless of language.

Key translations performed:

• OP_QUERY (legacy, pre-5.0) → OP_MSG (modern)
• Deprecated command fields (e.g., $orderby → sort)
• isMaster → hello handshake translation
• Wire compression negotiation differences
• buildInfo version string patching

This is a singleton step — only one instance per pipeline. Configure all your client/server versions in one place.

When to use

• Upgrading MongoDB servers while legacy applications still use old drivers
• Running mixed-version client environments (some apps on 4.0, others on 6.0)
• Zero-downtime migration strategy: upgrade server first, then drivers incrementally
• Testing new server versions with production traffic from old clients

How it works

1. Request phase: Detects isMaster, hello, and buildInfo commands and marks them for response patching.
2. Response phase: For marked commands, patches maxWireVersion and minWireVersion in the response BSON to match the lowest configured client version.
3. If patch_build_info is enabled, also overrides the version string in buildInfo responses.
4. If strict_mode is enabled, rejects connections from clients whose driver version isn't in the configured list.
5. Wire version mapping is precomputed at step construction time for zero-overhead at runtime.

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
client_versions	multiselect	—	Yes	MongoDB client/driver versions connecting through this proxy
server_versions	multiselect	—	Yes	MongoDB server versions behind this proxy
patch_build_info	bool	false	No	Override version string in buildInfo responses
strict_mode	bool	false	No	Reject connections from unlisted client versions

Settings reference

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

Examples

Bridge 3.6/4.0 clients to 7.0 server

steps:
  - name: builtin:version-compat
    config:
      client_versions: ["3.6", "4.0"]
      server_versions: ["7.0"]
      patch_build_info: true
      strict_mode: false

Mixed environment with strict enforcement

steps:
  - name: builtin:version-compat
    config:
      client_versions: ["4.4", "5.0", "6.0"]
      server_versions: ["7.0", "8.0"]
      patch_build_info: false
      strict_mode: true

Multi-language stack (PyMongo 3.x + Java 4.x + Node 6.x → MongoDB 7.0)

# PyMongo 3.12 speaks 4.4 protocol
# Java Driver 4.11 speaks 5.0 protocol
# Node.js Driver 6.x speaks 7.0 protocol (no translation needed)
steps:
  - name: builtin:version-compat
    config:
      client_versions: ["4.4", "5.0", "7.0"]
      server_versions: ["7.0"]
      patch_build_info: true
      strict_mode: true

Best practices

• Only include client versions that actually exist in your environment
• Enable strict_mode in production to prevent unknown drivers from connecting
• Enable patch_build_info if clients check server version strings (some ORMs do)
• Plan to remove this step once all clients are upgraded — it's a migration bridge, not permanent

Limitations

• Cannot translate actual protocol behavior differences (e.g., new aggregation stages)
• Only patches handshake responses — doesn't modify query/response payloads
• Wire version patching may not work for clients that validate cryptographic signatures in hello
• Singleton: only one instance per pipeline

Security and operational guidance

• Cannot create capabilities absent from MongoDB
• Test authentication, sessions, transactions, topology, and failover
• The pinned Proxy controller does not watch NexoVersionCompat directly

Related steps

• query-rewrite

Release availability

• 0.2.0 Private Preview: Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

See the component catalog for the complete comparison matrix.