M↓ View as Markdown ↗

Warehouse connectivity

Availability

• Deployment: Self-managed deployments only. On Actian SaaS, Actian manages these settings.

Members connect warehouses in Studio, under Connections → Add a connection → Warehouses. As the operator of a self-managed deployment of Actian AI Analyst, you decide:

• Which private networks the server may connect to.
• Whether the Actian-family connectors are available, by running the JDBC bridge.
• Which connectors members are offered.
• Which egress IP addresses Studio shows members for their firewall rules.

How AI Analyst connects to a warehouse

• Most connectors (PostgreSQL, Snowflake, BigQuery and others) connect directly from the AI Analyst server.
• Actian, Ingres, Informix and ZenDB connect through the JDBC bridge, a separate service that holds their JDBC drivers. The server sends each query to the bridge, which connects to the warehouse.

For every connector, the server first resolves the warehouse host name and checks the address against its egress rules. See Reach warehouses on private networks.

A connector appears under Add a connection → Warehouses only when all of these allow it:

Gate	Set by	Effect
The JDBC bridge	JDBC_BRIDGE_URL	Actian, Ingres, Informix and ZenDB are offered only when JDBC_BRIDGE_URL is set.
The connector allowlist	CONNECTORS_ENABLED	When set, only the listed connectors are offered.
Your Licence	The Licence Actian issues	A connector is offered unless your Licence explicitly excludes it.

Reach warehouses on private networks

The server's egress rules

Before it connects to a warehouse, the server resolves the host name and checks every address it gets back:

• Private address space is denied unless you allow it. This covers 0.0.0.0/8, 10.0.0.0/8, 127.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::/128, ::1/128 and fc00::/7. To allow a range, list it in WAREHOUSE_EGRESS_ALLOW_PRIVATE_CIDRS as comma-separated CIDRs, for example 10.20.0.0/16,192.168.50.0/24.
• Some destinations are always denied, even if you list them: link-local addresses (169.254.0.0/16 and fe80::/10, which include cloud metadata services) and the host names metadata.google.internal, metadata.goog, kubernetes.default, kubernetes.default.svc and kubernetes.default.svc.cluster.local.
• Public addresses are allowed.

The same rules apply to the LLM and Embedding endpoints that organizations add under Settings → Inference. They don't apply to the deployment default endpoints in Configure inference.

When WAREHOUSE_EGRESS_ALLOW_PRIVATE_CIDRS isn't set at all, the default depends on where the server runs:

Where the server runs	Default when the variable is unset
Kubernetes (Helm chart)	All private ranges are denied. The Helm chart always sets the variable, so this applies when your list is empty.
Docker Compose	10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 and ::1 are allowed.

Once you set the variable, only the ranges you list are allowed.

Compose bundle

Every container except the reverse proxy sits on a Docker network with no route off the host. Out of the box, the server and the JDBC bridge can reach only the containers in the stack.

To reach warehouses on your network:

1. Attach the stack to your network with the override file:

   docker compose -f docker-compose.yml -f compose.customer-network.yml up -d --wait
   

   The override attaches the server, keycloak and jdbc-bridge services to one more, routed Docker network. You can name it with CUSTOMER_NETWORK_NAME (default ai-analyst-customer).

2. Restrict egress with the host firewall. From now on, the host firewall is what keeps the installation Air-gapped. Allow traffic out of that network only to your own address ranges, such as warehouses, LLM and Embedding endpoints and your SMTP relay. On Linux, the DOCKER-USER iptables chain is the usual place for these rules.

3. Optional: restrict which private ranges the server may reach. On Compose, private ranges are already allowed by default. If you want to limit the server to specific ranges, list them in .env:

   WAREHOUSE_EGRESS_ALLOW_PRIVATE_CIDRS=10.20.0.0/16
   

   Then run the same docker compose ... up -d --wait command again.

Tip

Use the same -f options every time you run docker compose for this stack, or the override is dropped.

Helm chart

List the private ranges in a chart value:

jdbcBridge:
  networkPolicy:
    allowPrivateEgressCidrs:
      - 10.20.0.0/16

Then run helm upgrade. The chart uses this one list in two places:

• It sets WAREHOUSE_EGRESS_ALLOW_PRIVATE_CIDRS on the server pods. This value overrides the same key in your Secret, so don't set it there.
• When the JDBC bridge is enabled, it adds an egress rule for each range to the bridge's NetworkPolicy.

The chart doesn't ship a NetworkPolicy for the server pods. Your cluster's own egress policy must allow the server to reach your warehouses.

Enable Actian-family warehouses (JDBC bridge)

The JDBC bridge serves the Actian, Ingres, Informix and ZenDB connectors. It's off by default. While JDBC_BRIDGE_URL is unset, these connectors aren't offered.

The bridge refuses to start without JDBC_BRIDGE_TOKEN, a shared secret that the server sends with each request. There's no default token. Generate one:

openssl rand -hex 32

Compose bundleHelm chart

1. In .env, set:

   JDBC_BRIDGE_URL=http://jdbc-bridge:8080
   JDBC_BRIDGE_TOKEN=<TOKEN>
   

   The server and the bridge both read the same JDBC_BRIDGE_TOKEN.

2. Start the stack with the jdbc profile. Add the compose.customer-network.yml override if your warehouses are on your network:

   docker compose --profile jdbc -f docker-compose.yml -f compose.customer-network.yml up -d --wait
   

Tip

To avoid typing --profile jdbc every time, set COMPOSE_PROFILES=jdbc in .env. This is a standard Docker Compose setting.

1. Push the jdbc-bridge image from the Release bundle to your registry, as you did for the other images.

2. Set these values:

   jdbcBridge:
     enabled: true
     image:
       repository: registry.example.internal/ai-analyst/jdbc-bridge
       tag: "<VERSION>"
   

   jdbcBridge.image.repository is empty by default, so you must set it.

3. Add JDBC_BRIDGE_URL and JDBC_BRIDGE_TOKEN to the server Secret (server.existingSecret). The bridge pod reads its token from the same Secret.

   kubectl -n ai-analyst patch secret ai-analyst-secrets --type merge \
     -p '{"stringData":{"JDBC_BRIDGE_URL":"http://ai-analyst-jdbc-bridge:8080","JDBC_BRIDGE_TOKEN":"<TOKEN>"}}'
   

   The bridge's Service is named <fullname>-jdbc-bridge and listens on port 8080. <fullname> is:

   • the release name, when it contains ai-analyst (release ai-analyst gives http://ai-analyst-jdbc-bridge:8080);
   • otherwise <release>-ai-analyst (release prod gives http://prod-ai-analyst-jdbc-bridge:8080);
   • or fullnameOverride, when you set it.

4. Run helm upgrade, then restart the server pods so they read the updated Secret. See How you supply configuration.

After the server restarts, the four connectors appear under Add a connection → Warehouses, unless CONNECTORS_ENABLED or your Licence excludes them. For each connector's connection form, see Actian Data Platform, Actian Ingres and Actian Zen.

How the bridge is protected

• It stores no warehouse credentials. The server decrypts the credentials and sends them with each request. The bridge doesn't keep them or pool connections.
• It needs the token. Only requests that carry JDBC_BRIDGE_TOKEN can run queries.
• On Helm, it's reachable only from the server. The bridge has a ClusterIP Service and no ingress route. Its NetworkPolicy accepts connections on port 8080 only from the chart's server pods. Its egress allows DNS and public addresses, but not 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 169.254.0.0/16, except for the ranges you list in allowPrivateEgressCidrs.
• On Compose, the token is the main control. There's no NetworkPolicy. Any container on the stack's network can reach the bridge.

NetworkPolicy needs a CNI that enforces it

If your cluster's network plugin doesn't enforce NetworkPolicy, the bridge's ingress and egress rules have no effect, and nothing reports it. Check your network plugin before you rely on these rules.

On Helm, the bridge pod loads the whole server Secret, but it reads only JDBC_BRIDGE_TOKEN from it.

Check which drivers the bridge can load

The bridge answers GET /health without a token. The response lists each driver and whether the bridge can load it:

{"ok": true, "drivers": {"ACTIAN": true, "INGRES": true, "INFORMIX": true, "ZENDB": false}}

This example shows a bridge that can't load the ZenDB driver. The endpoint is reachable only from inside the deployment, and the bridge image has no curl:

Compose bundleHelm chart

Ask from the server container:

docker compose exec server node -e "fetch('http://jdbc-bridge:8080/health').then(r => r.text()).then(console.log)"

Forward the bridge's port, then ask from your machine:

kubectl -n ai-analyst port-forward svc/<fullname>-jdbc-bridge 8080:8080
curl -s http://127.0.0.1:8080/health

Replace <fullname>-jdbc-bridge with your bridge Service name (see above).

AI Analyst doesn't read this endpoint itself. Studio offers all four connectors whenever JDBC_BRIDGE_URL is set, even if the bridge can't load a driver.

ZenDB

If the health response shows "ZENDB": false, ZenDB connections fail even though Studio offers the connector: tests and queries are refused because the driver isn't available. Contact Actian about the ZenDB driver. Until then, you can hide ZenDB with CONNECTORS_ENABLED on the Helm chart.

Limit which connectors are offered

CONNECTORS_ENABLED is a comma-separated list of connector IDs. When you set it, members are offered only the listed connectors. When it's unset or empty, every connector is offered.

CONNECTORS_ENABLED=POSTGRESQL,SNOWFLAKE,ACTIAN

IDs are upper case and must match exactly:

ID	Connector	ID	Connector
POSTGRESQL	PostgreSQL	BIGQUERY	BigQuery
MYSQL	MySQL	SNOWFLAKE	Snowflake
MARIADB	MariaDB	DATABRICKS	Databricks
REDSHIFT	Amazon Redshift	MOTHERDUCK	MotherDuck
MSSQL	Microsoft SQL Server	ACTIAN	Actian
SYNAPSE	Azure Synapse	INGRES	Ingres
FABRIC	Microsoft Fabric	INFORMIX	Informix
CLICKHOUSE	ClickHouse	ZENDB	ZenDB

• It can't turn on a bridge connector. ACTIAN, INGRES, INFORMIX and ZENDB still need JDBC_BRIDGE_URL.
• CSV file uploads aren't affected. Files aren't a connector.
• Existing connections keep working. For a connector that isn't offered, members can't create a connection, test an unsaved connection, list schemas for an unsaved connection, or change an existing connection's credentials. The API refuses these actions with a CONNECTOR_UNAVAILABLE error (HTTP 409) and the message not offered by this deployment. Members can still browse, query, rename and re-test existing connections.
• Set it on the Helm chart only. Add CONNECTORS_ENABLED to the server Secret. The shipped Compose file doesn't pass this key to the server, so setting it in .env has no effect.

When your Licence excludes a connector, the same actions are refused with CONNECTOR_UNAVAILABLE and the message not included in your plan.

Removing the bridge breaks existing Actian-family connections

If you remove JDBC_BRIDGE_URL or JDBC_BRIDGE_TOKEN later, the server can no longer reach the bridge. Every query on an existing Actian, Ingres, Informix or ZenDB connection fails, and connection tests show This warehouse type isn't available right now.

Show your egress IP addresses to members

Members often need to allow AI Analyst's IP addresses through their warehouse firewall. Studio's Setup help panel for a warehouse connection can list those addresses under Which IPs to allow.

By default, a self-managed deployment lists no addresses, and the panel shows general guidance instead. To list your deployment's outbound (NAT or egress) addresses, set WAREHOUSE_EGRESS_IPS to a comma-separated list:

WAREHOUSE_EGRESS_IPS=203.0.113.10,203.0.113.11

On the Helm chart, add it to the server Secret. The shipped Compose file doesn't pass this key to the server. On Compose, give members the addresses yourself.

Credential encryption key

AI Analyst encrypts stored warehouse credentials with WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY. Keep this key safe and never change it. If you lose it, AI Analyst can't read any stored credential. See Credential encryption key.

Slack and Microsoft Teams

The Slack and Microsoft Teams integrations need vendor-hosted services. On an Air-gapped deployment, which includes every Compose installation, the server refuses to start if any Slack or Teams key is set, so these integrations aren't available. See Connected and Air-gapped deployments.

Troubleshooting

Symptom	Likely cause	Fix
Actian, Ingres, Informix or ZenDB is missing under Add a connection → Warehouses.	JDBC_BRIDGE_URL is unset, CONNECTORS_ENABLED leaves the connector out, or your Licence excludes it.	Set up the JDBC bridge and check CONNECTORS_ENABLED.
Another connector is missing.	CONNECTORS_ENABLED leaves it out, or your Licence excludes it.	Add its ID to CONNECTORS_ENABLED, or contact Actian about your Licence.
The JDBC bridge doesn't start.	JDBC_BRIDGE_TOKEN is empty.	Set a non-blank token for both the server and the bridge.
A connection test shows This warehouse type isn't available right now.	The server has no JDBC_BRIDGE_URL or JDBC_BRIDGE_TOKEN.	Set both and restart the server.
A connection to a warehouse on a private network fails.	The server's egress rules deny the address, or the network doesn't route to it. A connection test shows Could not connect with the detail "Warehouse host is not allowed". Other requests, such as listing schemas, answer HTTP 400 with the code WAREHOUSE_HOST_DENIED.	List the warehouse's range in WAREHOUSE_EGRESS_ALLOW_PRIVATE_CIDRS (Compose) or allowPrivateEgressCidrs (Helm). On Compose, private ranges are allowed by default, so a denial usually means a link-local address or a list you set that leaves the range out. On Compose, use the customer network override and check the host firewall. On Helm, check your cluster's egress policy.
ZenDB tests fail although the bridge runs.	The bridge can't load the ZenDB driver.	Check the bridge's drivers.
A connection test shows Stored credentials could not be read.	WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY changed since the credentials were saved.	Restore the original key.
CONNECTORS_ENABLED has no effect on Compose.	The Compose file doesn't pass this key to the server.	This setting is available on the Helm chart.