ducklake-guard

Experimental — ducklake-guard is under active development. It works, but has not been audited. Review carefully before using in sensitive or production environments.

Per-table access control for DuckLake lakehouses on Hetzner Cloud. A single CLI manages S3 bucket policies, Postgres catalog visibility (RLS), and catalog roles, with an audit log.

Note

I'll add AWS and Scaleway, make sure to follow the repo for any updates.

Installation

pip install ducklake-guard

Or with uv:

uv pip install ducklake-guard

From source:

pip install git+https://github.com/berndsen-io/ducklake-guard.git

System overview

graph LR
    DGA["dga CLI"]
    PG_GUARD["ducklake_guard DB<br/>(source of truth)"]
    PG_CATALOG["ducklake_catalog DB<br/>(RLS + roles)"]
    S3["Hetzner S3<br/>(bucket policy)"]

    DGA -->|manages grants| PG_GUARD
    DGA -->|pushes RLS + roles| PG_CATALOG
    DGA -->|pushes bucket policy| S3

Loading

Prerequisites

• Hetzner server, PostgreSQL, Object Storage bucket. Recommendation, auto deploy with ducklake-hetzner.
• S3 credentials for each user, created manually in the Hetzner Console (no API exists for credential lifecycle)
• SSH access to the PostgreSQL server (for dga init)

Quick start

dga env > .env
# Fill in credentials

dga init                          # create guard DB, schema, enable RLS

dga user create tim \
  --access-key <KEY> \
  --project-id <PID>              # register user, create catalog role

dga allow tim --table customer --read-only
dga allow tim --table orders --read-write

duckdb -init init-tim.sql         # verify: SHOW TABLES, SELECT, INSERT

dga deny tim --table orders       # revoke access
dga user delete tim               # remove user, scrub policies, drop role

CLI quick reference

Command	Description
dga init	Create guard DB, schema, pg_hba, enable RLS
dga user create <name>	Register user + S3 creds, create catalog role
dga user delete <name>	Remove user, scrub policies, drop role
dga allow <user> --table T	Grant read-only or read-write access
dga deny <user> --table T	Revoke table access
dga sync	Converge S3 + RLS to match grant state

Documentation

• Architecture: enforcement layers, transaction flow, sync convergence, module dependencies
• Usage: setup, user management, granting and revoking access, DuckDB verification
• Schema: database tables, generated columns, composite keys
• Design decisions: why separate Hetzner projects, RLS limitations, policy size bundling
• Development: running tests, linting, pre-commit checklist

---

Need help deploying DuckLake to production? berndsen.io