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
| Option | Short | Default | Description |
|---|---|---|---|
TABLE_NAME |
(required) | Table to tail | |
--connection |
-C |
(required) | Catalog connection string |
--catalog |
-c |
lake |
Catalog name |
--data-path |
-d |
. |
Path to DuckLake data files |
--namespace |
-n |
main |
Table namespace |
--interval |
-i |
1.0 |
Poll interval (seconds) |
--columns |
-col |
(all) | Columns to show (repeat for multiple) |
--filter |
-f |
(none) | CDC filter expression |
--mode |
-m |
pager |
pager or interactive |
Change symbols
| Symbol | Color | Meaning |
|---|---|---|
+ |
Green | Row inserted |
- |
Red | Row deleted |
Δ |
Yellow | Row updated — shows column: old → new for each changed field |
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
| Recipe | What it does |
|---|---|
just sync |
Install dependencies |
just fmt |
Format code |
just lint |
Lint |
just typecheck |
mypy strict |
just test |
Unit tests |
just test-integration |
Integration tests |
just test-all |
Both |
just ci |
fmt-check + lint + typecheck + test |
License
Apache License 2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ducktail-1.0.4.tar.gz.
File metadata
- Download URL: ducktail-1.0.4.tar.gz
- Upload date:
- Size: 680.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
79fecb01a01992f6ab45a1ac6a707b4b26bd00102d5a84302d1806397105968c
|
|
| MD5 |
7cfda60eb0da89fe3b52edc3341e7977
|
|
| BLAKE2b-256 |
3652d4bff80b5bbf754451af64b42b4c8c3a112fd580c94645948c828ce3473d
|
Provenance
The following attestation bundles were made for ducktail-1.0.4.tar.gz:
Publisher:
release.yml on jghoman/ducktail
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ducktail-1.0.4.tar.gz -
Subject digest:
79fecb01a01992f6ab45a1ac6a707b4b26bd00102d5a84302d1806397105968c - Sigstore transparency entry: 2456776542
- Sigstore integration time:
-
Permalink:
jghoman/ducktail@bcd8ab8f5809850f594f01bd1c7e3c6101ec65d5 -
Branch / Tag:
refs/tags/v1.0.4 - Owner: https://github.com/jghoman
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@bcd8ab8f5809850f594f01bd1c7e3c6101ec65d5 -
Trigger Event:
push
-
Statement type:
File details
Details for the file ducktail-1.0.4-py3-none-any.whl.
File metadata
- Download URL: ducktail-1.0.4-py3-none-any.whl
- Upload date:
- Size: 13.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d7ab59b00b5d8403832791f22eaf4da99373f033647c140e2183103ffa16c0ef
|
|
| MD5 |
9eb900fe7b0795130a56467679e379f4
|
|
| BLAKE2b-256 |
34294a91784b0cb69b3904151b3079b82065f5fcd2b8f0090d9fe39e34c7bef8
|
Provenance
The following attestation bundles were made for ducktail-1.0.4-py3-none-any.whl:
Publisher:
release.yml on jghoman/ducktail
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ducktail-1.0.4-py3-none-any.whl -
Subject digest:
d7ab59b00b5d8403832791f22eaf4da99373f033647c140e2183103ffa16c0ef - Sigstore transparency entry: 2456776878
- Sigstore integration time:
-
Permalink:
jghoman/ducktail@bcd8ab8f5809850f594f01bd1c7e3c6101ec65d5 -
Branch / Tag:
refs/tags/v1.0.4 - Owner: https://github.com/jghoman
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@bcd8ab8f5809850f594f01bd1c7e3c6101ec65d5 -
Trigger Event:
push
-
Statement type:
