Manage the Network Configuration of an Ocient System

Connectivity pools configure the external networking interfaces that clients use to connect to an System. They define the addresses and ports that SQL Nodes listen on and control how clients such as JDBC, pyocient, and the HTTP Query API (OpenAPI) interact with the system. Connectivity pools do not affect the internal network configuration that Ocient Nodes use to communicate with each other.

Connectivity Pool Behavior

A connectivity pool groups one or more SQL Nodes together and provides clients with the network information needed to connect. A connectivity pool serves three purposes:

Defines listen endpoints — Each participant node in the pool specifies the address and port where it accepts connections for both the SQL wire protocol and the HTTP Query API.
Advertises connection information — Each participant can advertise a different address and port than it listens on, which is essential when clients connect through Network Address Translation (NAT) or load balancers.
Enables automatic client redirection — The system can automatically redirect JDBC and pyocient clients connecting to any node in a pool to the least busy node within the same pool. This redirection provides client-side load balancing without external infrastructure.

The HTTP Query API (OpenAPI) does not support automatic redirection because cross-origin request restrictions make it impractical. Use DNS round-robin or an external load balancer for OpenAPI load distribution.

All SQL Nodes in the system must belong to at least one connectivity pool. Each node can belong to multiple pools. For the DDL statements for managing connectivity pools, see CONNECTIVITY POOL.

Connectivity pools do not support dynamic IP addresses. If the IP address of your SQL Node changes, you must manually update it by using an ALTER CONNECTIVITY_POOL ALTER PARTICIPANT SQL statement.

Default Behavior

The Ocient System creates a single shared connectivity pool named system during bootstrap. All SQL Nodes automatically join this pool as participants. When you add a new SQL Node to the cluster, the system automatically adds it to the system pool. This default behavior enables automatic client redirection between all SQL Nodes, which is the chosen behavior for most deployments. You do not need any additional configuration.

Pool Selection Behavior

When a client connects to a SQL Node, the system determines which connectivity pool to use through the following process:

The system identifies all pools that have a participant listening on the connected address and port.
The system filters pools by SOURCE_ADDRESS, matching the source IP address of the client against the CIDR range of each pool.
If a pool specifies the SOURCE_PORT value, the connection port must also match.
Among all matching pools, the system selects the pool with the highest PRIORITY value.
The system associates the client with that pool. For JDBC and pyocient connections, redirection uses the ADVERTISED_ADDRESS and ADVERTISED_PORT values of nodes within the selected pool.

This selection process allows you to direct clients from different networks to different pools. For example, internal clients can match a higher-priority pool that advertises internal hostnames, while external clients match a lower-priority pool that advertises external hostnames.

Initial Configuration

For most deployments, the default system pool provides the correct behavior without additional configuration. To customize your initial connectivity pool configuration, use the CREATE CONNECTIVITY_POOL statement or specify the configuration in the bootstrap.conf file. For details about the bootstrap.conf file, see Node Bootstrapping Reference.

Expand the Network of an Ocient System

The system adds new SQL Nodes to the system pool. No manual steps are required. If you use custom connectivity pools instead of the default system pool, you can add new SQL Nodes to an existing pool using the ALTER CONNECTIVITY_POOL ADD PARTICIPANTS statement.

Change the Network Configuration of an Ocient System

You can configure IP addresses that the Ocient System uses to connect to the external client or to other nodes in the system. Configure IP addresses for external client connections using the ALTER CONNECTIVITY_POOL SQL statement. Configure IP addresses for connections with other nodes in the system using the ALTER NODE SET ADDRESS SQL statement. The system automatically adds new SQL Nodes to the system pool. If you use custom connectivity pools, you might need to configure the pools using the CONNECTIVITY_POOL SQL statements after adding a new SQL Node or adding a SQL role using the ALTER NODE ADD ROLE SQL statement.

Common Deployment Scenarios

These scenarios illustrate common connectivity pool configurations for different network topologies and workload requirements. Each scenario includes the SQL statements needed to create and configure the pools.

Single Pool With All Nodes

This deployment is the simplest and most common. All SQL Nodes share one connectivity pool, and you can redirect clients connecting to any node to the least busy node. This behavior is the default with the system pool. You do not need any additional configuration. You can verify the configuration by querying the system catalog.

SQL

SELECT name, source_address, priority
FROM sys.connectivity_pools;

SQL

SELECT pool_name, node_name,
    listen_address, listen_port,
    advertised_address, advertised_port
FROM sys.connectivity_pool_participants;

NAT: Internal and External Networks

When clients access SQL Nodes through a NAT gateway, the internal and external addresses differ. Create two connectivity pools: one for internal clients and one for external clients.

SQL

CREATE CONNECTIVITY_POOL internal_pool
    SOURCE_ADDRESS '10.0.0.0/8'
    PRIORITY 2
    PARTICIPANTS (
        (NODE sql0
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql0.internal.example.com'
         ADVERTISED_PORT 4050),
        (NODE sql1
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql1.internal.example.com'
         ADVERTISED_PORT 4050));

CREATE CONNECTIVITY_POOL external_pool
    SOURCE_ADDRESS '0.0.0.0/0'
    PRIORITY 1
    PARTICIPANTS (
        (NODE sql0
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4051
         ADVERTISED_ADDRESS 'sql0.external.example.com'
         ADVERTISED_PORT 4051),
        (NODE sql1
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4051
         ADVERTISED_ADDRESS 'sql1.external.example.com'
         ADVERTISED_PORT 4051));

In this example:

Internal clients (source IP in 10.0.0.0/8) match internal_pool (priority 2) and connect on port 4050. Redirection uses the internal hostnames.
External clients (any other source IP) match external_pool (priority 1) and connect on port 4051. Redirection uses the external hostnames.
Both pools listen on 0.0.0.0, so connections arrive on any interface. The pool selection depends on the source address of the client and the priority of the pool.

Workload Isolation

Dedicate different SQL Nodes to different workloads or tenants by placing them in separate pools. The system redirects clients connecting to a node in one pool to other nodes in the same pool.

SQL

CREATE CONNECTIVITY_POOL analytics_pool
    SOURCE_ADDRESS '0.0.0.0/0'
    PRIORITY 1
    PARTICIPANTS (
        (NODE sql0
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql0.example.com'
         ADVERTISED_PORT 4050),
        (NODE sql1
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql1.example.com'
         ADVERTISED_PORT 4050));

CREATE CONNECTIVITY_POOL ingest_pool
    SOURCE_ADDRESS '0.0.0.0/0'
    PRIORITY 1
    PARTICIPANTS (
        (NODE sql2
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql2.example.com'
         ADVERTISED_PORT 4050),
        (NODE sql3
         LISTEN_ADDRESS '0.0.0.0'
         LISTEN_PORT 4050
         ADVERTISED_ADDRESS 'sql3.example.com'
         ADVERTISED_PORT 4050));

In this example, analytics clients connect to sql0 or sql1 and the system redirects only within the analytics_pool pool. Ingest clients connect to sql2 or sql3 and the system redirects only within the ingest_pool pool. The two workloads do not interfere with each other.

Connectivity Pool Troubleshooting

If a connectivity pool misconfiguration prevents client connections, you can enable a fallback listener by adding this configuration to the rolehostd.conf file. This configuration causes all SQL Nodes to listen on 0.0.0.0:4050 regardless of the connectivity pool settings, allowing you to connect and correct the pool configuration.

Text

sql:
   defaultListen: true

You must restart the rolehostd process after you add this configuration.

Shell

sudo systemctl restart rolehostd

Alternatively, you can change the IP address of the SQL Nodes in the connectivity pool using an ALTER CONNECTIVITY_POOL ALTER PARTICIPANT SQL statement.

For existing clusters, the Ocient System configures all SQL Nodes to listen on the IP address 0.0.0.0, allowing clients to manually create initial connectivity pools.

Install an Ocient System Ocient System Bootstrapping Node Bootstrapping Reference CONNECTIVITY POOL ALTER NODE ADD ROLE ALTER NODE REMOVE ROLE ALTER NODE SET ADDRESS

​Connectivity Pool Behavior

​Default Behavior

​Pool Selection Behavior

​Initial Configuration

​Expand the Network of an Ocient System

​Change the Network Configuration of an Ocient System

​Common Deployment Scenarios

​Single Pool With All Nodes

​NAT: Internal and External Networks

​Workload Isolation

​Connectivity Pool Troubleshooting

​Related Links

Connectivity Pool Behavior

Default Behavior

Pool Selection Behavior

Initial Configuration

Expand the Network of an Ocient System

Change the Network Configuration of an Ocient System

Common Deployment Scenarios

Single Pool With All Nodes

NAT: Internal and External Networks

Workload Isolation

Connectivity Pool Troubleshooting

Related Links