quacktui

A Python TUI for managing DuckLake datalakes. Browse your catalog, inspect table metadata, run SQL queries, and perform maintenance operations — all from your terminal.

Install

With uv (recommended)

uv tool install quacktui

With pip

pip install quacktui

From source

git clone https://github.com/arksigma/quacktui
cd quacktui
uv sync
uv run quacktui

Run it in Docker

A self-contained sandbox image bundles quacktui, an in-container MinIO, and a pre-seeded DuckLake demo catalog:

./testing/setup.sh                                    # default connection: duckdb-demo
./testing/setup.sh --connection duckdb-demo-readonly  # any quacktui flag passes through

When you're done:

./testing/teardown.sh             # stop + remove container
./testing/teardown.sh --volumes   # also wipe persisted config/history/state

MinIO console (optional) at http://localhost:9001 (creds: minioadmin/minioadmin).

setup.sh rebuilds the image from your current working tree every run — no PyPI roundtrip, no version pin to bump. Iterate on source, re-run setup, the container has the new code.

Quickstart

Create a connections.toml file in your home directory:

[[connections]]
name = "demo"
type = "duckdb"
uri = "md:demo"

[connections.storage]
type = "s3"
bucket = "my-data"
endpoint = "http://localhost:9000"
access_key_id = "minioadmin"
secret_access_key = "minioadmin"

Then launch quacktui:

quacktui --connection demo

For DuckDB with local files:

[[connections]]
name = "local"
type = "duckdb"
database = "/path/to/database.duckdb"

[connections.storage]
type = "s3"
bucket = "local-bucket"
endpoint = "http://localhost:9000"

Features

Catalog Views

Browse and inspect your datalake with eight dedicated views:

• Schema Browser — Explore tables and views organized by schema
• Table Details — Inspect table structure, columns, constraints, and statistics
• Snapshot Timeline — View table snapshot history and retention policies
• File Inventory — List all data files backing a table
• Partition Explorer — Navigate and manage table partitions
• Schema Evolution — Track column additions, renames, and type changes over time
• Health Dashboard — Monitor table health, data quality, and maintenance metrics
• Catalog Database Info — View version, format configuration, and settings

Query Editor

Multi-tab SQL editor with the following capabilities:

• Syntax highlighting for SQL and Python
• Schema-aware autocomplete for table and column names
• Query history stored in persistent SQLite
• Saved query snippets for frequent operations
• Result export to CSV, Parquet, JSON, or clipboard
• Multiple concurrent queries with separate result tabs
• Query timeline to review and re-run historical queries

Maintenance Operations

Perform five critical datalake maintenance tasks, all requiring explicit confirmation:

1. Compaction — Consolidate small files into larger files to improve query performance and reduce file count
2. Expire Snapshots — Remove old snapshots based on retention policies to free storage
3. Delete Orphaned Files — Clean up unreferenced files in S3 storage
4. Refresh Statistics — Update table statistics for query optimization
5. Optimize Manifests — Reorganize manifest files (version-dependent, available when supported by catalog format)

Destructive operations require pressing Ctrl+Enter to confirm.

Safety

By default, quacktui operates in read-only mode. Pass the --allow-writes flag to enable mutations:

quacktui --connection demo --allow-writes

Without this flag, all write operations are disabled and maintenance ops are grayed out.

Catalog Backends

quacktui supports the following catalog backends via DuckLake's extension:

• DuckDB (default, embedded)
• PostgreSQL (remote)
• SQLite (file-based)
• MySQL (remote)

Specify the backend in connections.toml using the type field.

Storage

In v1, quacktui supports S3 and S3-compatible storage backends:

• AWS S3
• MinIO (local or remote)
• Cloudflare R2
• DigitalOcean Spaces
• Any S3-compatible endpoint

Configure the storage endpoint, bucket, and credentials in the [connections.storage] section of connections.toml.

Configuration

Create a connections.toml file to define your datalake connections:

[[connections]]
name = "production"
type = "duckdb"
uri = "md:prod"

[connections.storage]
type = "s3"
bucket = "prod-data"
endpoint = "https://s3.amazonaws.com"
region = "us-east-1"
access_key_id = "YOUR_KEY"
secret_access_key = "YOUR_SECRET"

[[connections]]
name = "staging"
type = "postgresql"
host = "localhost"
port = 5432
database = "datalake"
user = "admin"
password = "secret"

[connections.storage]
type = "s3"
bucket = "staging-data"
endpoint = "http://minio:9000"

For more detailed configuration options, see docs/CONFIGURATION.md.

Keybindings

Navigate and control quacktui with these keyboard shortcuts:

Development

For development and contribution guidelines, see:

• docs/CONTRIBUTING.md — How to contribute
• docs/COMPATIBILITY.md — Supported versions and compatibility matrix
• .sisyphus/plans/ducklake-tui.md — Current implementation status and milestones

License

Apache License 2.0. See LICENSE for details.