Module trase.tools.ducklake

DuckLake connection helpers for Trase Python scripts.

Use :func:connect() to obtain an in-process DuckDB connection that has the trase DuckLake catalog already attached as trase_ducklake. The default role="ro" opens a READ-ONLY attach with the readonly Postgres user; pass role="rw" to write through the catalog.

Sub-modules

trase.tools.ducklake.connection

Open a DuckDB connection with the Trase DuckLake catalog attached …

trase.tools.ducklake.env_export

Print export TRASE_DUCKLAKE__*=... lines for bash sourcing …

Functions

def attach_metadata_postgres(con: duckdb.DuckDBPyConnection, alias: str = 'pg_meta', role: Role = 'ro') ‑> str

ATTACH the DuckLake metadata Postgres as a plain READ-ONLY postgres DB.

For diagnostics the DuckLake catalog attach doesn't surface — server GUCs (idle_in_transaction_session_timeout, statement_timeout) and pg_stat_activity. Query it via postgres_query('<alias>', $$ ... $$). Idempotent: returns alias without re-attaching (and without a redundant Secrets Manager fetch) if it is already attached. Returns the attach alias.

def connect(role: Role = 'ro') ‑> _duckdb.DuckDBPyConnection

Open a DuckDB connection with the Trase DuckLake catalog attached.

role="ro" (default) attaches READ-ONLY with the readonly Postgres user. role="rw" attaches read-write with the rw user; the RW password is fetched from Secrets Manager on every call (never cached).

The catalog is attached as trase_ducklake and made the current catalog (USE trase_ducklake), so callers can query main_elementary.elementary_test_results directly.