Module trase.tools.ducklake.connection

Open a DuckDB connection with the Trase DuckLake catalog attached.

Reads settings.ducklake.* (see trase.env), fetches the role's Postgres password from AWS Secrets Manager, and runs a INSTALL/LOAD/CREATE SECRET sequence

Password caching:

  • RO is cached on disk under ${XDG_RUNTIME_DIR:-/tmp}/trase-ducklake/ro_pw_<uid> for 12 h to share hits across connect("ro"), edr report, and other read-only workflows. The cache directory is 0700, the file is 0600, written atomically (tmp + os.replace), and validated on read (owner uid + permissions). Disable by setting TRASE_DUCKLAKE_PASSWORD_CACHE_ENABLED=false.
  • RW is never cached. ./dbt --target production and other RW callers fetch from Secrets Manager on every invocation (~2 s).

Functions

def clear_ro_cache() ‑> bool

Delete the RO password cache file (and dir if empty). Returns True if a file was removed.

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.

def ro_cache_path() ‑> pathlib.Path

Path of the on-disk RO password cache file (may not exist).