onehouse-python-sdk

Python SDK for connecting to Onehouse data-plane and control-plane services.

The base package has zero required dependencies. Drivers ship as optional extras so you only install what you need.

pip install onehouse-python-sdk[lakebase]    # PostgreSQL/LakeBase SQL client
pip install onehouse-python-sdk[resources]   # Control-plane REST client

LakeBase

LakeBase is Onehouse's PostgreSQL-compatible managed lakehouse engine. This SDK provides a psycopg2-backed client that handles the browser-based and federated authentication flows LakeBase clusters require, on top of standard username/password auth.

Installation

pip install onehouse-python-sdk[lakebase]

Requires Python 3.9+.

Quickstart

from onehouse_python_sdk import LakebaseClient

# Username / password
with LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    user="admin",
    password="secret",
) as client:
    rows = client.fetchall("SELECT * FROM mytable WHERE id = %s", (42,))

Authentication flows

# OIDC Device Flow
client = LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    browser_auth="true",
    oidc_client_id="0oaXXXXX",
    oidc_issuer_url="https://myorg.okta.com",
    oidc_iam_role="arn:aws:iam::123456789012:role/LakeBaseRole",
)

# Azure AD OAuth2
client = LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    browser_auth="true",
    azure_oauth_tenant_id="your-tenant-id",
    azure_oauth_client_id="your-client-id",
    azure_oauth_client_secret="your-client-secret",
)

DSN string form is also supported:

client = LakebaseClient().connect(
    "postgresql://<cluster-host>:5432/mydb"
    "?browser_auth=true"
    "&oidc_client_id=0oaXXXX"
    "&oidc_issuer_url=https://myorg.okta.com"
    "&oidc_iam_role=arn:aws:iam::123456789012:role/LakeBaseRole"
)

Client API

All clients implement the SqlClient interface:

Notes

• Credential caching — auth tokens are cached for 4 minutes per connection parameters to avoid repeated browser prompts within the same process.
• Callback port — the local auth callback server defaults to port 8888 at path /lakebase. Override with auth_callback_port and auth_callback_path.

Onehouse Resources (Control-Plane API)

OnehouseResources wraps the Onehouse REST API for managing platform resources — clusters, lakes, flows, jobs, table services, and more. It posts SQL statements to https://api.onehouse.ai/v1/resource/ and polls /v1/status/{requestId} for the result.

Installation

pip install onehouse-python-sdk[resources]

Quickstart

from onehouse_python_sdk import OnehouseResources

client = OnehouseResources(
    account_uid="...", project_uid="...",
    api_key="...", api_secret="...",
    link_uid="...", region="us-west-2", user_uid="...",
)

# Typed helper — blocks until the operation reaches a terminal status.
result = client.create_cluster(
    "prod",
    type="Managed",
    max_ocu=10,
    min_ocu=1,
    options={"worker.type": "oh-general-4"},
)
print(result.api_status)        # ApiStatus.SUCCESS
print(result.api_response)      # raw API payload

Credentials

Credentials resolve from three sources, in order (highest wins):

1. Explicit constructor arguments (shown above).
2. Environment variables — ONEHOUSE_ACCOUNT_UID, ONEHOUSE_PROJECT_UID, ONEHOUSE_API_KEY, ONEHOUSE_API_SECRET, ONEHOUSE_LINK_UID, ONEHOUSE_REGION, ONEHOUSE_USER_UID. Optional: ONEHOUSE_BASE_URL, ONEHOUSE_PROFILE, ONEHOUSE_CREDENTIALS_FILE. ONEHOUSE_BASE_URL is the API host (default https://api.onehouse.ai); a trailing /v1 is dropped, since every request adds it.
3. INI credentials file at ~/.onehouse/credentials (override with ONEHOUSE_CREDENTIALS_FILE).

# ~/.onehouse/credentials
[default]
account_uid = 92e5f1ab-...
project_uid = 3afe72cd-...
api_key     = j+m8wRhgpKYFTLxCHNDzQA==
api_secret  = tXpzrqfUBNK9yhS5+FmLM37xwfhVeZygJntCzHG4Dpq=
link_uid    = da56fe8b-...
region      = us-west-2
user_uid    = ...

[staging]
account_uid = ...

# Read from environment / default profile.
client = OnehouseResources()

# Pick a named profile.
client = OnehouseResources(profile="staging")

Missing fields produce an AuthError listing which fields are unset and how to supply them. A world-readable credentials file triggers a warning — chmod 600 ~/.onehouse/credentials.

OAuth sign-in instead of an API key

A person can sign in through the browser instead of holding an API key. external-api runs an OAuth 2.1 authorization server (authorization code + PKCE). Its access token is a Firebase ID token for the signed-in user and lasts an hour. Its refresh token rotates on every use and lasts 30 days. The org must have enable_external_api_bearer_auth on.

from pathlib import Path
from onehouse_python_sdk._session import FileSessionStore
from onehouse_python_sdk.resources import oauth

store = FileSessionStore(Path.home() / ".onehouse" / "session.json")
oauth.login("https://api.onehouse.ai", store)  # opens the browser, catches the code on 127.0.0.1

client = OnehouseResources(
    account_uid="...", project_uid="...", link_uid="...", region="us-west-2",
    token_source=oauth.FirebaseRefreshTokenSource("https://api.onehouse.ai", store),
)

• With a token_source, api_key, api_secret and user_uid are not required. Calls send Authorization: Bearer and never the key pair or user id: external-api takes the user from the token. link_uid and region are still required, because statements that reach a data plane need them.
• The token source refreshes 60 s before expiry and once after a 401. Refresh runs under the store's cross-process lock and re-reads the store first. Concurrent processes therefore share one rotation; presenting a rotated refresh token twice revokes the whole session.
• oauth.logout(base_url, store) revokes the refresh token and deletes the session. An access token already issued stays valid until it expires, at most an hour.
• FileSessionStore writes one 0600 file. The oh CLI keeps the refresh token in the OS keychain instead and falls back to this file.
• The client is the static public client oh-cli, registered for http://127.0.0.1/oauth/callback on any port.

AI Gateway tokens

onehouse_python_sdk.ai_gateway gets tokens for a data plane's AI Gateway. It uses the standard library only, and resources never imports it. Every call needs the VPN or the customer network.

from onehouse_python_sdk import ai_gateway

gateway = "https://ai-gateway-<id>.dp.onehouse.ai"

# A service principal: client_credentials with its API key pair. 300 s tokens, re-minted.
source = ai_gateway.ServicePrincipalTokenSource(gateway, api_key, api_secret)

# A person: sign in once on Keycloak's `onehouse-cli` client, then refresh.
ai_gateway.login(gateway, store)
source = ai_gateway.KeycloakSessionTokenSource(gateway, store)

token = source.get()            # send as X-Onehouse-Authorization (or Authorization on /mcp)
token = source.get(force=True)  # after the gateway answers 401

• ai_gateway.discover(gateway) follows the gateway's own discovery chain: RFC 9728 protected-resource metadata, then RFC 8414 or OIDC metadata for the issuer it names. It checks that the issuer matches and that the audience is on the gateway's host. Nothing is derived from the hostname or the link id. A gateway with auth off raises AuthDisabledError.
• The human session stores only the refresh token. The access token (7 days on that client) stays in memory and is never written to disk.
• ai_gateway.logout(gateway, store) ends the Keycloak session best effort and always deletes the stored token.

Three ways to run a command

# (1) Blocking — submit, poll, return the terminal status. Most common.
result = client.execute("SHOW CLUSTERS")

# (2) Non-blocking — submit now, poll later. Good for long-running ops or
# parallel orchestration where you don't want to hold a thread.
submitted = client.submit("CREATE CLUSTER `prod` TYPE = 'Managed' MAX_OCU = 10 MIN_OCU = 1")
# ... do other work, persist submitted.request_id ...
status = client.get_status(submitted.request_id)
while status.api_status == ApiStatus.PENDING:
    time.sleep(5)
    status = client.get_status(submitted.request_id)

# (3) Typed helpers — same blocking semantics as execute(), but build the SQL for you.
client.create_cluster("prod", type="Managed", max_ocu=10, min_ocu=1)
client.show_clusters()
client.delete_cluster("prod")

Typed helpers

OnehouseResources exposes one method per Phase 1 SQL command (~50 methods across 11 resource families): Clusters, Lakes, Databases, Tables, Catalogs, Sources, Flows, Transformations, Validations, Table Services, Jobs, Service Principals, API Tokens. Every typed helper accepts the same trailing kwargs: unsafe_raw, timeout, poll_interval.

client.create_lake(
    "analytics",
    lake_type="MANAGED",
    bucket_path="s3://my-bucket/lake",
    default_services_cluster="services",
)

from onehouse_python_sdk.resources.sql.commands import PartitionKeyField

client.create_flow(
    "events_pipeline",
    source="my_kafka_source",
    lake="analytics",
    database="events",
    table_name="page_views",
    write_mode="MUTABLE",
    cluster="ingest_cluster",
    catalogs=["my_glue_catalog"],
    record_key_fields=["id"],
    partition_key_fields=[
        PartitionKeyField("date", partition_type="DATE_STRING",
                          input_format="yyyy-mm-dd", output_format="yyyy-mm-dd"),
    ],
    min_sync_frequency_mins=5,
    options={"kafka.topic.name": "page_views"},
)

CREATE FLOW — WITH options reference

Source-specific options and advanced configs are passed via the options dict. All keys and values are strings.

Kafka source

S3 source

GCS source — same as S3 with gcs. prefix (e.g. gcs.folder.uri, gcs.file.format, etc.).

Onehouse table source

Postgres source

MySQL source

Oracle source

Schema registry (Kafka sources)

Cross-source advanced configs

</code></pre>
<p>ACL / privilege / role / group commands aren't exposed as typed helpers yet — use <code>client.execute("GRANT ...")</code> until they land in a future release.</p>
<h4 id="user-content-unsafe_raw-escape-hatch"><code>unsafe_raw</code> escape hatch<a href="#user-content-unsafe_raw-escape-hatch" aria-label="Link to heading 'unsafe_raw escape hatch'" data-heading-content="unsafe_raw escape hatch" class="anchor"></a></h4>
<p>The builder validates resource names against <code>^[A-Za-z][A-Za-z0-9_-]*$</code> and rejects unknown enum values to catch obvious typos. If a name doesn't match (e.g. legacy resources with dots in the name) or you're using a SQL feature the SDK hasn't been updated for, pass <code>unsafe_raw=True</code> on the call to skip validation:</p>
<pre><code class="language-python">client.create_cluster("legacy.name", type="CustomType", unsafe_raw=True)

The argument is deliberately named so its uses are easy to find in grep.

Error handling

OnehouseSdkError
└── ResourcesError                     # raised by the resources/ subpackage
    ├── AuthError                      # missing/invalid credentials
    ├── SqlParseError                  # HTTP 400 + grpc-message — server rejected the SQL
    ├── OperationFailedError           # terminal status FAILED or INVALID
    └── OperationTimeoutError          # polling exceeded the configured timeout

OperationTimeoutError carries the request_id of the in-flight operation — you can resume polling with get_status(request_id) rather than re-submitting (which would create a duplicate resource).

Client API

Notes

• Lazy import — from onehouse_python_sdk import OnehouseResources works even when the [resources] extra isn't installed; the first network call raises a clear "install [resources] extra" error.
• Rate limit — projects are capped at 10 QPS. The transport retries 429 responses with bounded exponential backoff.
• Not a SqlClient — OnehouseResources is a control-plane HTTP client and intentionally does not implement the SqlClient interface (no cursor, fetchall, etc.).