Skip to content

README.md

Latest commit

 

History

History
109 lines (74 loc) · 2.5 KB

README.md

File metadata and controls

109 lines (74 loc) · 2.5 KB

pgcp

PostgreSQL Copy Tool - Copy databases like cp copies files.

Note: Currently macOS only.

npx pgcp <source_url> <destination_url>

Installation

# Run directly without installing
npx pgcp <source> <destination>

# Or install globally
npm install -g pgcp

Usage

# Default mode: copy between any postgres databases
pgcp <source> <destination>

# Supabase mode: copy to local Supabase (manages local instance lifecycle)
pgcp --supabase <source> <destination>

Arguments

  • <source> - Source database URL or env:VARNAME
  • <destination> - Destination database URL or env:VARNAME

Options

  • --supabase - Use Supabase mode (destination is local Supabase, managed automatically)
  • --schema-only, -s - Copy schema only, skip data
  • --keep-dumps, -k - Keep dump files after completion
  • --help, -h - Show help message

Examples

# Copy from remote postgres to local postgres
npx pgcp postgres://user:pass@remote:5432/prod postgresql://localhost:5433/local

# Use env variables from .env.local
npx pgcp env:PROD_DATABASE_URL env:LOCAL_DATABASE_URL

# Copy schema only (no data)
npx pgcp --schema-only env:PROD_DB env:LOCAL_DB

# Supabase mode: copy Supabase DB to local Supabase (automatic setup)
npx pgcp --supabase env:SUPABASE_DATABASE_URL postgresql://postgres:postgres@localhost:54322/postgres

Environment

Automatically loads .env and .env.local from the current directory. Use the env:VARNAME syntax to reference variables from these files.

Requirements

Default mode

  • pg_dump (brew install libpq && brew link --force libpq)
  • psql
  • Node.js >= 18

Supabase mode (--supabase)

  • Docker (running)
  • Supabase CLI (brew install supabase/tap/supabase)
  • psql
  • Node.js >= 18

How It Works

Default mode

  1. Checks prerequisites (pg_dump, psql)
  2. Verifies destination database is accessible
  3. Dumps source database using pg_dump
  4. Restores to destination using psql
  5. Cleans up dump files (unless --keep-dumps)

Supabase mode

  1. Checks prerequisites (Docker, Supabase CLI, psql)
  2. Stops existing local Supabase
  3. Starts fresh local Supabase
  4. Waits for Postgres readiness
  5. Dumps from source: roles -> schema -> data (optional)
  6. Restores to local: roles -> grant roles -> schema -> data (triggers disabled)
  7. Cleans up dump files (unless --keep-dumps)

Development

Requires bun for development and publishing.

bun install
bun run build

License

MIT