databaas-utils

Lakekeeper/Iceberg lakehouse access for Databaas: catalog, remote-signed object storage, an Airflow integration, and user access from notebooks — in JupyterHub or on a laptop.

Notebooks

from databaas_utils.notebook import get_catalog, get_store, get_zarr_group

catalog = get_catalog()
catalog.load_table("open_meteo.daily_summary").scan(limit=10).to_arrow()

group = get_zarr_group("harmonie_zarr", namespace="knmi", read_only=True)

databaas_utils.notebook authenticates as the person running the notebook and picks how by itself:

• In a Databaas JupyterHub pod it asks the hub for the logged-in user's access token (GET /hub/api/oauth-token, using the JUPYTERHUB_API_URL/JUPYTERHUB_API_TOKEN every singleuser pod has). The catalog is CATALOG_URI (default http://lakekeeper:8181) and the warehouse LAKEKEEPER_WAREHOUSE (default databaas-lakehouse).
• Anywhere else it uses the session saved by databaas login (below).

So the same notebook runs on the platform and on a laptop. Pass profile= to force a databaas login profile, or warehouse= to override the warehouse. DAGs must not use this module — a task authenticates through its Airflow connection (databaas_utils.airflow).

Local (analyst) quickstart

pip install "databaas-utils[local]"
databaas login https://<your-environment>.databaas.eu

databaas login discovers the environment's Zitadel/Lakekeeper settings from the portal, opens a browser to sign in with your own identity, and caches the session (in your OS keychain) so future Python processes don't prompt again. If no browser is reachable (e.g. over SSH), pass --device to use the OAuth2 device-code flow instead.

from databaas_utils import LakehouseSettings, rest_catalog

settings = LakehouseSettings.from_profile()  # picks up the login from `databaas login`
catalog = rest_catalog(settings)
catalog.list_namespaces()

resolve()/GenericTableStore/open_zarr_group() work the same way once you have settings — see their docstrings. An admin still has to grant your Lakekeeper user (databaas whoami shows its id, oidc~<sub>) access to a warehouse before any of this returns data.

Useful commands:

Several environments can be configured at once as named profiles in ~/.config/databaas/config.toml; select one with --profile NAME or DATABAAS_PROFILE.

Admin runbook: registering the local-login app in Zitadel

Local login needs one Zitadel Native app per environment, created by hand today — databaas-core/packages/bootstrap does not yet support the app type or grant this needs (see "Follow-up" below). In the Zitadel console, under the Databaas project:

1. New application → type Native, authentication method None (PKCE proves possession instead of a secret).
2. Grant types: Authorization Code, Refresh Token, and Device Code.
3. Redirect URIs: http://127.0.0.1/callback and http://localhost/callback — the CLI binds an OS-assigned loopback port and matches on path only, so a single registered host is enough (confirm this against the deployed Zitadel version; if it requires an exact port, pin one with the profile's redirect_port and register that port explicitly instead).
4. Token settings: Auth Token Type JWT (Lakekeeper validates access tokens against Zitadel's JWKS; an opaque token is rejected).
5. Note the app's Client ID and the project's Project ID — a user provides these (or the portal's discovery document supplies them) when running databaas login.

Portal discovery document

databaas login <portal-url> expects the portal to serve, unauthenticated:

GET /.well-known/databaas-client.json

{
  "issuer": "https://auth.<env>.databaas.eu",
  "client_id": "<native app client id>",
  "project_id": "<zitadel project id>",
  "catalog_url": "https://catalog.<env>.databaas.eu",
  "warehouse": "databaas-lakehouse",
  "region": "nl-ams"
}

Until the portal ships this, pass the equivalent --issuer/--client-id/--project-id/ --catalog-url/--warehouse flags to databaas login instead.

Follow-up: bootstrap support

databaas-core/packages/bootstrap's schema (bootstrap-config.schema.json) and Zitadel client currently only support appType ∈ {WEB, USER_AGENT} and grantTypes ∈ {AUTHORIZATION_CODE, REFRESH_TOKEN}. Extending both to NATIVE and DEVICE_CODE would let a "Databaas CLI" app be declared in bootstrap.example.yaml like the other apps and remove the manual step above. Out of scope for this package.