tail -f for PostgreSQL. Stream INSERT/UPDATE/DELETE events to your terminal in real time using the native logical replication protocol.

[12:01:03] INSERT public.orders  id=1 status=pending amount=99.99
[12:01:07] UPDATE public.orders  id=1
                                 status: pending → completed
[12:01:10] DELETE public.orders  id=1

Contents

• Requirements
• Install
• Quick start
• Usage
  • Flags
  • Examples
  • TUI mode
  • --where syntax
• How it works
• How is this different from other tools?
• Postgres setup
  • wal_level
  • Publication
  • UPDATE diffs (REPLICA IDENTITY)
• doctor subcommand
• Hosted Postgres
• Caveats
• License

Requirements

• Go 1.23+
• PostgreSQL 10+ with wal_level=logical

Install

Homebrew (macOS / Linux):

brew install AndreaBeggiato/tap/pg-tail

Go:

go install github.com/AndreaBeggiato/pg-tail/cmd/pg-tail@latest

Pre-built binaries: download from the releases page (linux / darwin / windows, amd64 / arm64).

From source:

git clone https://github.com/AndreaBeggiato/pg-tail
cd pg-tail
go build -o pg-tail ./cmd/pg-tail

Quick start

1. Start Postgres with logical replication enabled

podman run --rm \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16 -c wal_level=logical

2. Check your setup

DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres ./pg-tail doctor

3. Create a test table and start streaming

psql postgres://postgres:postgres@localhost:5432/postgres \
  -c "CREATE TABLE orders (id SERIAL PRIMARY KEY, status TEXT, amount NUMERIC);"

DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres ./pg-tail
# → prompted to create the publication on first run, type y

4. Fire some events in a second terminal

psql postgres://postgres:postgres@localhost:5432/postgres

INSERT INTO orders (status, amount) VALUES ('pending', 99.99);
UPDATE orders SET status = 'completed' WHERE id = 1;
DELETE FROM orders WHERE id = 1;

Press Ctrl-C to stop. The temporary replication slot is dropped automatically on exit.

Usage

pg-tail [flags]              # opens the interactive TUI by default
pg-tail --stream [flags]     # plain streaming output for terminals and pipes
pg-tail doctor [--dsn <dsn>]

Flags

pg-tail reads DATABASE_URL from the environment. If a .env file is present in the current directory it is auto-loaded. The connection string can be a URL (postgres://user:pass@host/db) or a key-value DSN (host=localhost dbname=mydb).

Examples

# Watch a single table (TUI)
pg-tail --tables orders

# Plain streaming output (good for logs / pipes)
pg-tail --stream

# Watch inserts and updates only
pg-tail --events insert,update

# Combine table, event type, and row filters
pg-tail --tables orders --events update --where "amount > 100"

# UPDATE diffs only, NDJSON to jq
pg-tail --stream --diff --format ndjson | jq .

# Hide noisy columns
pg-tail --ignore-fields updated_at,search_vector

# SQL WHERE expressions
pg-tail --where "status = 'pending'"
pg-tail --where "status IN ('pending', 'processing') AND amount > 50"
pg-tail --where "email LIKE '%@example.com'"
pg-tail --where "deleted_at IS NULL"
pg-tail --where "NOT (status = 'archived')"

# Show transaction boundaries
pg-tail --verbose

TUI mode

The TUI is the default. It opens an interactive split-pane view on top of the same event stream — see the demo above.

The top pane shows one box per table with the most recent event at the cursor position. The bottom pane is the live event stream. [LIVE] / [PAUSED] indicator shows current state in the help bar.

Key bindings

The where-filter is persisted to ~/.config/pg-tail/state.json and reloaded on next start. Use --stream for non-interactive output — e.g. pg-tail --stream --format ndjson | jq ..

--where syntax

--where accepts standard SQL WHERE expressions evaluated against each row's column values.

Numeric comparison is used automatically when both sides parse as numbers; string comparison is the fallback.

How it works

pg-tail uses PostgreSQL's logical replication protocol — the same protocol used by tools like Debezium and pglogical. On start it:

1. Opens a replication connection to Postgres
2. Creates a temporary logical replication slot (dropped automatically on exit)
3. Streams WAL changes decoded by the pgoutput plugin
4. Decodes and prints INSERT/UPDATE/DELETE events in real time

No polling. No triggers. No schema changes required beyond a publication.

How is this different from other tools?

vs. pg_recvlogical + jq (Postgres' built-in CLI). pg_recvlogical streams the raw pgoutput byte protocol — you'd have to write your own decoder before you could read anything. pg-tail decodes pgoutput for you and adds colorized diffs, table/event/row filtering, and a publication-aware UX. Use pg_recvlogical for replication transport; use pg-tail for seeing what's happening.

vs. CDC platforms (Debezium, Sequin, PeerDB, etc.). Those are production pipelines that ship changes to Kafka, SQS, webhooks, search indexes, and other destinations. You operate them as services, often via Docker. pg-tail is the opposite — a single binary you run in your terminal for interactive debugging. No infrastructure, no sinks, no configuration files. The replication slot is ephemeral and dropped when you Ctrl-C. If you need a CDC pipeline, Sequin is great. If you need to see what just happened, pg-tail is the tool.

vs. other projects named pg-tail / pgtail / pg_tail. A few projects share this naming territory. Worth disambiguating:

• willibrandon/pgtail is an actively-maintained interactive tailer for Postgres log files with a Textual TUI. Excellent tool — solves a different problem (server logs, not row changes).
• aaparmeggiani/pg_tail (C) and ChillarAnand/pgtail (Python) tail table rows via polling — repeated queries on an interval. pg-tail uses logical replication instead, which captures every change including intermediate updates without per-poll query load.

Postgres setup

wal_level

Logical replication requires wal_level = logical. Check with:

If it is not logical, change it (requires a server restart):

ALTER SYSTEM SET wal_level = logical;
-- then restart Postgres

Publication

pg-tail needs a publication to subscribe to. If you run pg-tail without one it will offer to create it. To create it manually:

-- All tables (simplest)
CREATE PUBLICATION pg_tail FOR ALL TABLES;

-- Specific tables only
CREATE PUBLICATION pg_tail FOR TABLE orders, users;

Use a different publication name with --publication.

UPDATE diffs (REPLICA IDENTITY)

By default, Postgres only includes the primary key in UPDATE and DELETE events. To see old → new diffs for all columns, set REPLICA IDENTITY FULL on the table:

ALTER TABLE orders REPLICA IDENTITY FULL;

Without it, UPDATE events show the new state of all columns but no diff. The pg-tail doctor command reports the replica identity for each table in your publication.

doctor subcommand

pg-tail doctor checks your Postgres instance and reports everything pg-tail needs:

  ✓  connection                    connected to postgres
  ✓  wal_level                     logical
  ✓  postgres version              16.2
  ✓  publications                  pg_tail (ALL TABLES)
  ℹ  replication slots             none (pg-tail creates a temporary one on start)
  ⚠  replica identity: public.orders  DEFAULT (key columns only) — UPDATE diffs show changed fields only with REPLICA IDENTITY FULL

It also prints the exact SQL to fix any issues it finds.

Hosted Postgres

pg-tail uses the standard PostgreSQL logical replication protocol, so it works with any provider that supports it. Confirmed:

If your connection is being routed through a pooler (PgBouncer, Supabase pooler, etc.), pg-tail doctor will detect it and tell you to switch to the direct URL.

Caveats

• Temporary slot: the replication slot is dropped when pg-tail exits. If the process is killed hard (e.g. kill -9), the slot may linger. Check with SELECT slot_name FROM pg_replication_slots; and drop manually if needed: SELECT pg_drop_replication_slot('pg_tail_tmp');
• WAL retention: while pg-tail is running, Postgres retains WAL from the slot's restart LSN. For long-running sessions on busy databases this can grow. Monitor disk usage.
• DELETE columns: with default replica identity, DELETE events only include the primary key. Non-key columns appear as NULL. Use REPLICA IDENTITY FULL to capture the full deleted row.
• Managed Postgres: see the Hosted Postgres section above for per-provider setup.

License

MIT