Command Reference¶

Complete reference for all pg commands with usage, examples, and flag conflicts.

Command Structure¶

pg <command> [subcommand] [pg-options] [tool-options]

pg options must come before tool options. pg options are connection options and general options.

Connection Options¶

Flag	Long Form	Description
`-c`	`--pg-connection-string`	LibPQ connection string
`-s`	`--pg-service`	Service name (pg_service.conf)
`-h`	`--pg-host`	Hostname or socket path
`-p`	`--pg-port`	Port number
`-d`	`--pg-database`	Database name (name only, not connection string)
`-u`	`--pg-user`	Username

General Options¶

Long Form	Description
`--pg-dry-run`	Show command without executing
`--pg-verbose`	Set verbosity for debugging

Flag Conflict Workarounds¶

When PostgreSQL tool flags conflict with pg's options, you have two solutions:

1. Use Long Form (Recommended)¶

# ❌ Conflicts
pg query -s production -c "select version();"

# ✅ Use long form
pg query -s production --command "select version();"

# ❌ Conflicts
pg query -c "service=production

# ✅ Use long form
pg query --pg-connection-string "service=production"

2. Use Non-Conflicting Flag First¶

Since pg stops parsing after encountering unknown flags, you can use a non-conflicting tool flag first:

# ❌ Conflicts (-c gets interpreted as connection string)
pg query -s production -c "select version();"

# ✅ Use non-conflicting flag first, then conflicting ones
pg query -s production --echo-queries -c "select version();"

This works because --echo-queries is unknown to pg, so everything after it gets passed to psql.

Query¶

Aliases: run, exec

Usage: pg query [pg-options] [psql-options]

Examples:

pg query -s production
pg query -s production --command "select version();"
pg query -h localhost -u admin -d myapp

Conflicting Options:

-c → use --command (to run SQL commands)
-n → use --no-readline (disable readline)
-s → use --single-step (single-step mode)

📖 psql documentation

Dump¶

dump db¶

Aliases: export db

Usage: pg dump db [pg-options] [pg_dump-options]

Examples:

pg dump db -s production -f dump.sql
pg dump db -s production --format=custom -f dump.dump

Conflicting Options:

-c → use --clean (clean before restore)
-n → use --schema (dump specific schema)

📖 pg_dump documentation

dump all¶

Aliases: export all

Usage: pg dump all [pg-options] [pg_dumpall-options]

Examples:

pg dump all -s production cluster-dump.sql

Conflicting Options:

-c → use --clean (clean before restore)
-s → use --schema-only (schema only)

📖 pg_dumpall documentation

dump restore¶

Aliases: import

Usage: pg dump restore [pg-options] input-file [pg_restore-options]

Examples:

pg dump restore -s staging dump.sql
pg dump restore -s staging dump.dump

Conflicting Options:

-c → use --clean (clean before restore)
-n → use --schema (restore specific schema)
-s → use --schema-only (schema only)

📖 pg_restore documentation

Backup¶

backup base¶

Aliases: none

Usage: pg backup base [pg-options] [pg_basebackup-options]

Examples:

pg backup base -s production /backups/$(date +%Y%m%d)

Conflicting Options: None

📖 pg_basebackup documentation

backup combine¶

Aliases: none

Usage: pg backup combine [pg-options] [pg_combinebackup-options]

Examples:

pg backup combine /backups/full /backups/inc /backups/combined

Conflicting Options:

-d → use --debug (debug mode)
-n → CONFLICT: Both pg and tool use --dry-run

📖 pg_combinebackup documentation

backup verify¶

Aliases: none

Usage: pg backup verify [pg-options] [pg_verifybackup-options]

Examples:

pg backup verify /backups/20241201

Conflicting Options:

-n → use --no-parse-wal (skip WAL parsing)
-s → use --skip-checksums (skip checksum verification)

📖 pg_verifybackup documentation

Maintain¶

maintain vacuum¶

Aliases: none

Usage: pg maintain vacuum [pg-options] [vacuumdb-options]

Examples:

pg maintain vacuum -s production
pg maintain vacuum -s production --analyze

Conflicting Options:

-n → use --schema (vacuum specific schema)

📖 vacuumdb documentation

maintain reindex¶

Aliases: none

Usage: pg maintain reindex [pg-options] [reindexdb-options]

Examples:

pg maintain reindex -s production

Conflicting Options:

-s → use --system (reindex system catalogs)

📖 reindexdb documentation

maintain cluster¶

Aliases: none

Usage: pg maintain cluster [pg-options] [clusterdb-options]

Examples:

pg maintain cluster -s production

Conflicting Options: None

📖 clusterdb documentation

maintain check¶

Aliases: none

Usage: pg maintain check [pg-options] [pg_amcheck-options]

Examples:

pg maintain check -s production

Conflicting Options:

-s → use --schema (check specific schema)

📖 pg_amcheck documentation

Create & Drop¶

create db¶

Aliases: none

Usage: pg create db [pg-options] database-name [createdb-options]

Examples:

pg create db -s development newapp
pg create db -s development newapp --encoding=UTF8

Conflicting Options: None

📖 createdb documentation

create user¶

Aliases: none

Usage: pg create user [pg-options] username [createuser-options]

Examples:

pg create user -s production newuser
pg create user -s production appuser --createdb

Conflicting Options:

-c → use --connection-limit (connection limit)
-d → use --createdb (can create databases)
-s → use --superuser (superuser privileges)

📖 createuser documentation

drop db¶

Aliases: none

Usage: pg drop db [pg-options] database-name [dropdb-options]

Examples:

pg drop db -s development oldapp

Conflicting Options: None

📖 dropdb documentation

drop user¶

Aliases: none

Usage: pg drop user [pg-options] username [dropuser-options]

Examples:

pg drop user -s production olduser

Conflicting Options: None

📖 dropuser documentation

Stream¶

stream wal¶

Aliases: none

Usage: pg stream wal [pg-options] [pg_receivewal-options]

Examples:

pg stream wal -s production --directory=/wal-archive

Conflicting Options:

-n → use --no-loop (exit after one WAL file)
-s → use --status-interval (status interval)

📖 pg_receivewal documentation

stream logical¶

Aliases: none

Usage: pg stream logical [pg-options] [pg_recvlogical-options]

Examples:

pg stream logical -s production --slot=replica_slot

Conflicting Options:

-n → use --no-loop (exit after one record)
-s → use --status-interval (status interval)

📖 pg_recvlogical documentation

Bench¶

Aliases: none

Usage: pg bench [pg-options] [pgbench-options]

Examples:

pg bench -s testing
pg bench -s testing --clients=10 --transactions=1000

Conflicting Options:

-s → use --scale (scale factor)
-n → use --no-vacuum (skip vacuum)

📖 pgbench documentation

Info¶

info ready¶

Aliases: ready

Usage: pg info ready [pg-options] [pg_isready-options]

Examples:

pg info ready -s production
pg info ready -s production --timeout=5

Conflicting Options: None

📖 pg_isready documentation

info config¶

Aliases: none

Usage: pg info config [pg_config-options]

Examples:

pg info config

Conflicting Options: None

📖 pg_config documentation

Dev¶

Aliases: none

Usage: pg dev [pg-options] input-file [ecpg-options]

Examples:

pg dev application.pgc

Conflicting Options ⚠️¶

UNSOLVABLE CONFLICTS:

-c (compile only) - Conflicts with -c/--pg-connection-strings
-h (parse header) - Conflicts with -h/--host

Workaround: Use a non-conflicting flag first (like -v).

📖 ecpg documentation

Next: See PostgreSQL Tools Flags for complete flag compatibility tables.