> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage the Network Configuration of an Ocient System
> Manage network configuration for an Ocient System, including hostnames, IP addresses, ports, NIC bonding, and inter-node communication for production.
export const Ocient = "Ocient®";
Connectivity pools configure the external networking interfaces that clients use to connect to an {Ocient} 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](/cluster-and-node-management#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](/cluster-and-node-management#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:
1. The system identifies all pools that have a participant listening on the connected address and port.
2. The system filters pools by `SOURCE_ADDRESS`, matching the source IP address of the client against the CIDR range of each pool.
3. If a pool specifies the `SOURCE_PORT` value, the connection port must also match.
4. Among all matching pools, the system selects the pool with the highest `PRIORITY` value.
5. 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](/cluster-and-node-management#create-connectivity_pool) statement or specify the configuration in the `bootstrap.conf` file. For details about the `bootstrap.conf` file, see [Node Bootstrapping Reference](/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](/cluster-and-node-management#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](/cluster-and-node-management#alter-connectivity_pool) SQL statement. Configure IP addresses for connections with other nodes in the system using the [ALTER NODE SET ADDRESS](/cluster-and-node-management#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](/cluster-and-node-management#connectivity-pool) SQL statements after adding a new SQL Node or adding a SQL role using the [ALTER NODE ADD ROLE](/cluster-and-node-management#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 SQL theme={null}
SELECT name, source_address, priority
FROM sys.connectivity_pools;
```
```sql SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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.
```none Text theme={null}
sql:
defaultListen: true
```
You must restart the `rolehostd` process after you add this configuration.
```shell Shell theme={null}
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](/cluster-and-node-management#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.
## Related Links
[Install an Ocient System](/install-an-ocient-system)
[Ocient System Bootstrapping](/ocient-system-bootstrapping)
[Node Bootstrapping Reference](/node-bootstrapping-reference)
[CONNECTIVITY POOL](/cluster-and-node-management)
[ALTER NODE ADD ROLE](/cluster-and-node-management)
[ALTER NODE REMOVE ROLE](/cluster-and-node-management#alter-node-remove-role)
[ALTER NODE SET ADDRESS](/cluster-and-node-management)