ducktail

tail -f for DuckLake tables.

Watch inserts, deletes, and updates flow through a DuckLake table in real time, powered by DuckLake's built-in CDC.

$ ducktail tail orders -C meta.duckdb

+ id=1 name=Alice amount=100.0
+ id=2 name=Bob amount=50.0
- id=2 name=Bob amount=50.0
Δ amount: 100.0 → 150.0

Install

pip install ducktail        # or: uv add ducktail

Requires Python 3.12+ and DuckDB 1.4+ (ducklake extension loads automatically).

Usage

Basic

ducktail tail TABLE -C CONNECTION

# DuckDB metadata catalog
ducktail tail events -C meta.duckdb -d /data

# Postgres metadata catalog
ducktail tail events -C "postgres:dbname=ducklake host=localhost user=ducklake password=ducklake"

Interactive mode

Full-screen TUI with color-coded rows (green inserts, red deletes, yellow updates):

ducktail tail events -C meta.duckdb -m interactive

Filter what you see

# Only specific columns
ducktail tail events -C meta.duckdb -col status -col amount

# Server-side filter (pushed into the CDC query)
ducktail tail events -C meta.duckdb -f "amount > 100"

# Faster polling
ducktail tail events -C meta.duckdb -i 0.5

Compose with Unix tools

Pager mode (the default) writes one line per change to stdout, so it plays nicely with the usual suspects:

# Inserts only
ducktail tail orders -C meta.duckdb | grep '^\+'

# Deletes only
ducktail tail orders -C meta.duckdb | grep '^\-'

# Count changes per second
ducktail tail orders -C meta.duckdb | pv -l > /dev/null

Options

ducktail tail [OPTIONS] TABLE_NAME

Change symbols

Try the demo

The repo includes a Docker-based demo that stands up a Postgres metadata catalog and a producer that streams a mix of inserts, deletes, and updates.

# Terminal 1 — infrastructure + producer
just demo-up
just demo-producer

# Terminal 2 — watch it happen
just demo-tail                # pager mode
just demo-tail-interactive    # or interactive mode

# Cleanup
just demo-down

Development

Requires flox and Docker (for integration tests and demo).

flox activate
just sync       # install deps
just test       # unit tests
just ci         # format + lint + typecheck + unit tests

License

Apache License 2.0