tabletrace

████████╗ █████╗ ██████╗ ██╗     ███████╗  ████████╗██████╗  █████╗  ██████╗███████╗
╚══██╔══╝██╔══██╗██╔══██╗██║     ██╔════╝  ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝
   ██║   ███████║██████╔╝██║     █████╗       ██║   ██████╔╝███████║██║     █████╗
   ██║   ██╔══██║██╔══██╗██║     ██╔══╝       ██║   ██╔══██╗██╔══██║██║     ██╔══╝
   ██║   ██║  ██║██████╔╝███████╗███████╗     ██║   ██║  ██║██║  ██║╚██████╗███████╗
   ╚═╝   ╚═╝  ╚═╝╚═════╝ ╚══════╝╚══════╝     ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝

Real-time PostgreSQL change monitoring CLI.

English | 日本語

Features

• 🔍 Real-time monitoring - Watch INSERT, UPDATE, DELETE operations as they happen
• 📊 Multiple tables - Monitor multiple tables simultaneously
• 🎨 Color-coded output - Green for INSERT, yellow for UPDATE, red for DELETE
• 🔄 Interactive mode - View change details, history, and switch tables on the fly
• ⚡ Lightweight - No triggers, no schema changes, minimal performance impact

💡 Note: This CLI is a development tool designed for local environments. For GUI version, see TableTrace OSS. For team development or staging environments, see TableTrace Pro(coming soon).

Installation

npm (recommended)

npm install -g @monorka/tabletrace

Or use directly with npx:

npx @monorka/tabletrace watch --preset postgres

Cargo (Rust)

cargo install --git https://github.com/monorka/tabletrace-cli

Manual download

Download the binary for your platform from GitHub Releases.

Quick Start

Using presets (recommended for local development)

# Local PostgreSQL (localhost:5432)
tabletrace watch --preset postgres

# Supabase local (localhost:54322)
tabletrace watch --preset supabase

Custom connection

# Basic connection
tabletrace watch -d mydb -u postgres -W mypassword

# Full options
tabletrace watch -H localhost -P 5432 -d mydb -u postgres -W mypassword

Using environment variable (recommended for security)

export PGPASSWORD=mypassword
tabletrace watch -d mydb -u postgres

Usage

tabletrace watch [OPTIONS]

Options:
      --preset <PRESET>      Preset: 'supabase' (localhost:54322) or 'postgres' (localhost:5432)
  -H, --host <HOST>          Database host [default: localhost]
  -P, --port <PORT>          Database port [default: 5432]
  -d, --database <DATABASE>  Database name (required unless using --preset)
  -u, --user <USER>          Database user [default: postgres]
  -W, --password <PASSWORD>  Database password (or use PGPASSWORD env var)
  -s, --schema <SCHEMA>      Schema to watch (use 'all' for all schemas) [default: public]
  -i, --interval <INTERVAL>  Polling interval in milliseconds [default: 1000]
      --interactive          Enable interactive mode [default: true]
  -h, --help                 Print help
  -V, --version              Print version

Interactive Commands

When running in interactive mode, you can use these commands:

| Key | Command | |-----|---------| | 1, 2, ... | Show details of change #N | | l | List all recorded changes | | c | Clear change history | | w | Show currently watching tables | | r | Reset/reselect tables to watch | | h | Show help | | q | Quit |

Example Output

████████╗ █████╗ ██████╗ ██╗     ███████╗  ████████╗██████╗  █████╗  ██████╗███████╗
╚══██╔══╝██╔══██╗██╔══██╗██║     ██╔════╝  ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝
   ██║   ███████║██████╔╝██║     █████╗       ██║   ██████╔╝███████║██║     █████╗
   ██║   ██╔══██║██╔══██╗██║     ██╔══╝       ██║   ██╔══██╗██╔══██║██║     ██╔══╝
   ██║   ██║  ██║██████╔╝███████╗███████╗     ██║   ██║  ██║██║  ██║╚██████╗███████╗
   ╚═╝   ╚═╝  ╚═╝╚═════╝ ╚══════╝╚══════╝     ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝

                      Real-time PostgreSQL Monitor

👁 Watching (2 tables)
  [1] public.users
  [2] public.orders

+ #1 [14:23:45] INSERT public.users (1 row)
    + id=123 { name=Alice, [email protected] }

~ #2 [14:23:52] UPDATE public.orders (1 row)
    ~ id=456 { status: pending → completed }

- #3 [14:24:01] DELETE public.users (1 row)
    - id=123 { name=Alice, [email protected] }

How it Works

TableTrace monitors PostgreSQL's pg_stat_user_tables system view to detect changes:

• ✅ No triggers required - Works with any PostgreSQL database
• ✅ No schema changes - Read-only monitoring
• ✅ Minimal impact - Uses lightweight polling
• ✅ Row-level diffs - Shows exactly what changed

Security

• Passwords can be passed via PGPASSWORD environment variable (recommended)
• Connection credentials are never logged
• Only reads from system catalogs and user tables

Requirements

• PostgreSQL 9.6 or higher
• Node.js 16 or higher (for npm installation)

Related

• TableTrace OSS - Desktop GUI application for local development
• TableTrace Pro - Team collaboration & staging support (coming soon)

License

MIT © Monorka Inc.