Python & JDBC

For service code, ETL jobs, and ML pipelines: change one parameter in your connector setup. The official Snowflake and Databricks Python connectors work unchanged, and you can read the X-Airbrx-* response headers right from the cursor session — handy for asserting cache behavior in tests.

snowflake-connector-python

Replace the account parameter with your gateway address. Everything else — credentials, warehouse, database, schema — stays the same.

import snowflake.connector

conn = snowflake.connector.connect(
    user="analytics_runner",
    password=os.environ["SF_PWD"],
    account="your-account",
    warehouse="REPORTING_WH",
    database="ANALYTICS",
)

import snowflake.connector

conn = snowflake.connector.connect(
    user="analytics_runner",
    password=os.environ["SF_PWD"],
    account="your-slug.gateway.airbrx.ai",
    warehouse="REPORTING_WH",
    database="ANALYTICS",
)

databricks-sql-connector

from databricks import sql

conn = sql.connect(
    server_hostname="dbc-1234567890.cloud.databricks.com",
    http_path="/sql/1.0/warehouses/abc123",
    access_token=os.environ["DBX_TOKEN"],
)

from databricks import sql

conn = sql.connect(
    server_hostname="your-slug.gateway.airbrx.ai",
    http_path="/sql/1.0/warehouses/abc123",
    access_token=os.environ["DBX_TOKEN"],
)

SQLAlchemy

Update the host portion of the connection URL. Both the Snowflake dialect (snowflake://) and the Databricks dialect (databricks://) accept the gateway address transparently.

engine = create_engine(
  "snowflake://user:pwd@your-account/"
  "ANALYTICS?warehouse=REPORTING_WH"
)

engine = create_engine(
  "snowflake://user:pwd@your-slug"
  ".gateway.airbrx.ai/ANALYTICS"
  "?warehouse=REPORTING_WH"
)

Generic JDBC (Java callers)

Replace the host in the JDBC URL — same shape as the DBeaver recipe. The Snowflake and Databricks JDBC drivers are wire-compatible with the Gateway.

Authentication

For interactive jobs and service flows, you have two options:

• Warehouse credentials — pass through to the warehouse unchanged. Same user, same password / token / key pair as direct connections. Most existing code keeps working.
• Airbrx Personal Access Token — for service code that should be tightly scoped (e.g. a CI job that only reads one tenant's analytics). The four-axis scope (method × path × tenant × account) locks the token down. See scoping a token for the model.

Verify cache from your driver session

Both connectors expose the response metadata of the most recent statement, including X-Airbrx-* response headers. Useful in tests and observability hooks:

cursor.execute("SELECT region, sum(amount) FROM orders GROUP BY region")

# Snowflake connector
metadata = cursor._connection.rest.token  # internal — see SDK docs

# Cleaner: use a session-level handler that captures the headers
print(cursor.sfqid)            # query id
print(cursor.headers.get("X-Airbrx-Cache-Status"))  # HIT or MISS
print(cursor.headers.get("X-Airbrx-Rule-Id"))

For service code, log a one-line trace per query if you want a steady signal of cache effectiveness:

Notes worth knowing

• Connection pooling. Most Python service code pools connections (SQLAlchemy QueuePool, app-level pools). The Gateway pools warehouse sessions independently — the two layers stack fine. If you're tuning, the Gateway-side pool typically reduces warehouse session pressure more than the app-side pool does.
• Async drivers. The async Snowflake driver (snowflake-connector-python async APIs) and databricks-sql-connector with async clients work unchanged.
• SDK request retries. Driver retry logic on transient errors works through the Gateway just like through the warehouse — the Gateway is wire-compatible end to end.
• Tests. Asserting X-Airbrx-Cache-Status: HIT in your test suite is a clean way to lock in expected cache behavior for hot paths.

Where to go next

• Security posture — credentials forwarded, four-axis token scopes, RLS preserved.
• Response headers reference — full list of X-Airbrx-* headers you can read from the cursor.
• API reference — for service code that needs to manage rules or fetch analytics.