Version Compatibility

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

Always confirm availability in the release bundle selected for deployment.

At a glance

Property	Value
Pipeline phase	Request + response
Category	Transform
Canonical minimum tier	Free
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Catalog component. The dashboard currently displays an incorrect Pro badge; canonical entitlement is Free.

Release accuracy

• Current documentation: Catalog component. The dashboard currently displays an incorrect Pro badge; canonical entitlement is Free.

Where any detail below conflicts with the release status above, the release status is authoritative. Field names and examples describe the current dashboard and CRD surface; always confirm behavior against the selected release bundle before relying on it operationally.

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 Unverified performance figures

These figures are illustrative only. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Reported figure
P50	0.15ms
P95	0.35ms
P99	0.60ms

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

“Not specified” means required semantics were not declared for that field.

Field	Type	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

No additional settings reference is documented for this component.

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

• Current documentation: Catalog component. The dashboard currently displays an incorrect Pro badge; canonical entitlement is Free.

See the component catalog for the complete comparison matrix.