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>Groups, grants, roles and access-control policies have typed helpers too, for example <code>client.create_group("data_eng")</code>, <code>client.grant_privilege("SELECT", on="TABLE", name="lake.db.table", principal_type="GROUP", principal="data_eng")</code>, <code>client.grant_member(on="GROUP", name="data_eng", principal_type="USER", principal="a@acme.com")</code> and <code>client.show_policies("my_catalog")</code>. Anything without a helper still works through <code>client.execute(...)</code>.</p>
<h4 id="user-content-data-plane-onboarding">Data plane onboarding<a href="#user-content-data-plane-onboarding" aria-label="Link to heading 'Data plane onboarding'" data-heading-content="Data plane onboarding" class="anchor"></a></h4>
<p>These helpers onboard a GENERIC_K8S data plane (on-prem Kubernetes with S3-compatible storage). The org must have <code>enable_external_api_dp_onboarding</code> on. No statement names an org: every call acts on the <code>project_uid</code> the client sends. Pass <code>project_uid=</code> to the constructor to target an org other than the one in your profile or environment.</p>
<pre><code class="language-python">client = OnehouseResources(profile="default", project_uid="<org id>")

# Storage credentials and the Helm template go to their own REST endpoints, not /v1/resource,
# so the secret is never stored as statement text.
storage = client.upsert_dataplane_storage_credentials(
    "https://s3.example.com", access_key_id, secret_access_key, "us-east-1",
)                                                    # -> storage summary dict, no secret
client.validate_dataplane_storage()
client.alter_dataplane(zookeeper_servers=["zk-0.zk:2181", "zk-1.zk:2181"], storage_class="standard")
template = client.generate_dataplane_template()      # values_yaml, chart_ref, chart_version,
                                                     # release_name, namespace
client.create_dataplane()                            # starts the provisioning workflow
client.describe_dataplane()                          # org, storage, settings, workflow status
client.show_dataplane_node_types()
client.drop_dataplane()

• alter_dataplane updates only the settings you pass; the others keep their current values. The keyword arguments merge into options (giving a key both ways raises ValueError), so a setting without a keyword argument yet can go in options: client.alter_dataplane({"storage_class": "fast"}). A list value is sent comma-separated.
• The server validates the keys and values: zookeeper_servers must be host:port entries, and storage_class="" means the cluster's default storage class. An unknown key fails with the list of supported keys.
• describe_dataplane() returns the current values under settings (zookeeperServers, storageClassName); alter_dataplane() returns the effective settings plus updatedKeys. Like other StatusResponse payloads these keep the server's camelCase keys.
• The two REST methods send the same headers as /v1/resource, including Authorization: Bearer for an oh login session. They raise the same exceptions (AuthError on 401/403, SqlParseError on a 400 with a grpc-message, ResourcesError otherwise).
• Their error messages never quote the response body, and a secret the server echoes back is masked. values_yaml holds credentials: the returned dict's repr masks it, so write template["values_yaml"] to a 0600 file rather than printing it.

unsafe_raw escape hatch

The builder validates resource names against ^[A-Za-z][A-Za-z0-9_-]*$ 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 unsafe_raw=True on the call to skip validation:

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.).