onehouse-python-sdk 0.1.0

Onehouse Python SDK — modular data-plane clients for LakeBase and beyond

onehouse-python-sdk

Python SDK for connecting to Onehouse data-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]

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

Flow	Parameters
Username / password	user, password
OIDC Device Flow (Okta / Auth0)	browser_auth=true, oidc_client_id, oidc_issuer_url, oidc_iam_role
Azure AD OAuth2	browser_auth=true, azure_oauth_tenant_id, azure_oauth_client_id, azure_oauth_client_secret
Azure Entra ID SAML	browser_auth=true, azure_tenant_id, azure_entity_id
Built-in login form	browser_auth=true (default when no IdP params are set)
External redirect	browser_auth=true, auth_redirect_url

# 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:

Method	Description
connect(dsn=None, **kwargs) → self	Establish connection, returns self for chaining
execute(sql, params)	Run a statement, return rowcount
fetchall(sql, params)	Run a query, return list[tuple]
fetchone(sql, params)	Run a query, return first row or None
cursor()	Raw cursor for advanced use
raw_connection	Underlying psycopg2 connection
close()	Close the connection
__enter__ / __exit__	Context manager — closes on exit

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.