Client Routes (Private Networking)¶

When connecting to ScyllaDB Cloud clusters over private networking (e.g. AWS PrivateLink or GCP Private Service Connect), nodes are not reachable at the addresses they broadcast to each other. Each node is instead reachable through a proxy whose address is stored in the system.client_routes table. The driver has to be told to route through that table — that is what the Client Routes feature does.

How it works¶

Each proxy is identified by a connection id — a string the cloud infrastructure assigns to a particular PrivateLink / Private Service Connect connection.
On session startup, and on every metadata refresh, the driver reads system.client_routes to find which address and port to use for each node, filtered by the configured connection ids.
The driver subscribes to CLIENT_ROUTES_CHANGE events, so it can pick up changes to the table without waiting for a full metadata refresh.

Usage¶

Provide a clientRoutes option alongside contactPoints:

const { Client } = require('@scylladb/driver');

(async () => {
  const client = new Client({
    contactPoints: ['my-privatelink-endpoint.amazonaws.com:9042'],
    localDataCenter: '<your-dc>',
    clientRoutes: {
      proxies: [
        { connectionId: 'my-connection-id' },
      ],
    },
  });

  await client.connect();
})();

Replace <your-dc> with the datacenter name reported by your cluster. This setting controls coordinator selection; it does not filter discovered hosts or client routes.

contactPoints is still required — use the address your cloud setup gives you for the initial connection. Contact points are never translated, which is what makes the first connection possible before any route is known.

Proxies¶

clientRoutes.proxies is a non-empty array; each entry identifies one ScyllaDB Cloud connection to read routes for:

Option	Description
`connectionId`	The ScyllaDB Cloud connection id. Used to filter the rows of `system.client_routes` that apply to this proxy. This is required.
`hostnameOverride`	Overrides the hostname that would otherwise be read from `system.client_routes` for this connection id. Useful for e.g. local testing.

More than one proxy can be specified when connecting, for example one per availability zone - pass all of them in clientRoutes.proxies.

clientRoutes: {
  proxies: [
    { connectionId: 'conn-id-az-1' },
    { connectionId: 'conn-id-az-2' },
  ],
},

Restrictions¶

clientRoutes is mutually exclusive with:

policies.addressResolution — client routes performs its own Host ID based address translation, so a custom address translator would conflict with it.
sslOptions — TLS is not yet supported for client routes connections.

Combining either with clientRoutes throws when the client is created.

Limitations¶

Mixed clusters are not supported. Every node must be reachable through client routes, and so must have a corresponding entry in system.client_routes. A cluster where some nodes are behind private networking and others are reachable directly will not work.
Advanced shard awareness (the driver picking a source port to target a specific shard) is disabled, because the proxy infrastructure does not preserve it. Basic shard awareness still works, so requests are still routed to the correct shard.

Was this page helpful?