PostgreSQL Tools Flags¶

How to use PostgreSQL tool flags with pg and compatibility reference for flag conflicts.

How to Pass Flags to PostgreSQL Tools¶

pg passes flags to PostgreSQL tools after its own options:

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

Basic Example¶

# pg handles connection, psql gets --echo-queries
pg query -s production --echo-queries

# Equivalent to:
psql -d 'service=production' --echo-queries

Multiple Tool Options¶

# Multiple options for pg_dump
pg dump db -s production --format=custom --compress=9 --verbose -f dump.dump

# Equivalent to:
pg_dump -d 'service=production' --format=custom --compress=9 --verbose -f dump.dump

Important: Order Matters¶

# ✅ Correct - pg options first
pg dump db -s production --format=custom -f dump.dump

# ❌ Wrong - tool options before pg options
pg dump db --format=custom -s production -f dump.dump

pg stops parsing options when it encounters an unknown flag and passes everything remaining to the PostgreSQL tool.

Flag Compatibility Matrix¶

Tool	`-c`	`-s`	`-h`	`-d`
`psql`	⚠️ `--command`	⚠️ `--single-step`	✅	✅
`pg_dump`	⚠️ `--clean`	✅	✅	✅
`pg_dumpall`	⚠️ `--clean`	⚠️ `--schema-only`	✅	✅
`pg_restore`	⚠️ `--clean`	⚠️ `--schema-only`	✅	✅
`pg_basebackup`	✅	✅	✅	✅
`pg_combinebackup`	✅	✅	✅	⚠️ `--debug`
`pg_verifybackup`	✅	⚠️ `--skip-checksums`	✅	✅
`createdb`	✅	✅	✅	✅
`createuser`	⚠️ `--connection-limit`	⚠️ `--superuser`	✅	⚠️ `--createdb`
`dropdb`	✅	✅	✅	✅
`dropuser`	✅	✅	✅	✅
`vacuumdb`	✅	✅	✅	✅
`reindexdb`	✅	⚠️ `--system`	✅	✅
`clusterdb`	✅	✅	✅	✅
`pg_amcheck`	✅	⚠️ `--schema`	✅	✅
`pg_receivewal`	✅	⚠️ `--status-interval`	✅	✅
`pg_recvlogical`	✅	⚠️ `--status-interval`	✅	✅
`pgbench`	✅	⚠️ `--scale`	✅	✅
`pg_isready`	✅	✅	✅	✅
`pg_config`	✅	✅	✅	✅
`ecpg`	❌ Use non-conflicting flag first	✅	❌ Use non-conflicting flag first	✅

Legend¶

✅ Compatible - No conflict with pg options
⚠️ Conflict - Use the long form shown instead of the short flag
❌ Same flag - Both pg and tool use same flag; use non-conflicting flag first

`pg` Option Reference¶

`pg` Flag	Purpose	Conflicting Tools
`-c`	Connection string	`psql`, `pg_dump`, `pg_dumpall`, `pg_restore`, `createuser`, `ecpg`
`-s`	Service name	`psql`, `pg_dumpall`, `pg_restore`, `createuser`, `pg_verifybackup`, `reindexdb`, `pg_amcheck`, `pg_receivewal`, `pg_recvlogical`, `pgbench`
`-h`	Host	`ecpg`
`-d`	Database	`createuser`, `pg_combinebackup`

Tools Requiring Workarounds¶

ecpg - -c and -h conflicts require using non-conflicting flags first

Example workaround:

# ❌ This fails (conflicting flags)
pg dev -h myfile.pgc

# ✅ Use non-conflicting flag first
pg dev -v -h myfile.pgc

See the non-conflicting flag workaround for more details.

For detailed workarounds, see the Command Reference.