Apps

src/bin/ contains the user-facing command-line programs that ship with PostgreSQL. These are frontend programs — they link against libpq (the client library) and run as separate processes from the backend. They cannot use backend facilities like palloc or ereport.

The frontend tools are a separate world from the backend. They share src/common/ (utility code that compiles in both worlds) and src/fe_utils/ (frontend-only helpers), and they all link against libpq for talking to the server.

The tools

Binary	Source	Purpose
psql	src/bin/psql/	Interactive SQL client. Includes meta-commands (\d, \copy, \watch, ...), tab completion, \if-style scripting, variable substitution. The de facto standard for PostgreSQL.
pg_dump	src/bin/pg_dump/	Logical backup of a single database. Produces a SQL script or a custom-format archive.
pg_dumpall	src/bin/pg_dump/	Logical backup of an entire cluster, including roles and tablespaces.
pg_restore	src/bin/pg_dump/	Restore a custom-format dump.
pg_basebackup	src/bin/pg_basebackup/	Physical backup via the replication protocol. Also drives pg_receivewal and pg_recvlogical.
pg_receivewal	src/bin/pg_basebackup/	Stream WAL to a local directory in real time, for archive use.
pg_recvlogical	src/bin/pg_basebackup/	Stream logical changes from a logical slot.
pg_combinebackup	src/bin/pg_combinebackup/	Reassemble a full backup from a chain of incremental backups.
pg_walsummary	src/bin/pg_walsummary/	Inspect WAL summary files used for incremental backup.
pg_ctl	src/bin/pg_ctl/	Start, stop, restart, reload, status of a PostgreSQL cluster. Wraps the postmaster.
initdb	src/bin/initdb/	Initialize a new data directory: lay out the catalog, run bootstrap, create template databases.
pg_upgrade	src/bin/pg_upgrade/	In-place upgrade between major versions. Uses pg_dump's catalog-only output plus link-mode file moves.
pg_rewind	src/bin/pg_rewind/	Re-align a former primary to a new primary after failover, avoiding a full base backup.
pg_dump_log	(not a tool)	–
pg_amcheck	src/bin/pg_amcheck/	Run amcheck extension checks across one or more relations.
pg_archivecleanup	src/bin/pg_archivecleanup/	Delete archived WAL files older than a given LSN; used in archive_cleanup_command.
pg_checksums	src/bin/pg_checksums/	Enable, disable, or verify data-page checksums on an offline cluster.
pg_config	src/bin/pg_config/	Print compile-time settings (paths, version, configure flags). Used by build systems for extensions.
pg_controldata	src/bin/pg_controldata/	Dump pg_control from a stopped cluster. Useful for forensics.
pg_resetwal	src/bin/pg_resetwal/	Reset the WAL file when a cluster is too damaged to start. Last-resort tool; data loss is possible.
pg_test_fsync	src/bin/pg_test_fsync/	Benchmark fsync/fdatasync to choose wal_sync_method.
pg_test_timing	src/bin/pg_test_timing/	Benchmark gettimeofday() overhead.
pg_verifybackup	src/bin/pg_verifybackup/	Verify a pg_basebackup backup against its manifest.
pg_waldump	src/bin/pg_waldump/	Decode WAL files into human-readable records. Invaluable for replication / recovery debugging.
pgbench	src/bin/pgbench/	TPC-B-like benchmarking tool. The closest thing PostgreSQL has to an in-tree benchmark.
scripts	src/bin/scripts/	Small wrappers: createdb, createuser, dropdb, dropuser, clusterdb, reindexdb, vacuumdb.
pgevent	src/bin/pgevent/	Windows event-log message DLL.

Patterns shared across the tools

libpq client

Every tool uses libpq the same way: build a PGconn, call PQexec or PQsendQuery + PQgetResult, format results. See Interfaces / libpq. The frontend logging API (pg_log_error, pg_log_warning, ...) is in src/common/logging.c.

Argument parsing

The tools use getopt_long (src/include/getopt_long.h) for option parsing. Each tool's main() follows roughly the same shape:

1. pg_logging_init(argv[0]).
2. set_pglocale_pgservice(argv[0], PG_TEXTDOMAIN("...")).
3. Parse args with getopt_long.
4. Connect using shared connection-string helpers.
5. Do the work.

Connection-option handling

getopt_long plus pqconnopts plus keyword/value array — most tools accept the same -h/--host, -p/--port, -U/--username, -d/--dbname, -W/--password, --no-password set. Source: many places, but src/fe_utils/connect_utils.c consolidates a lot of it.

When to use which tool

graph TD
    A[Need to back up?] -->|logical, want SQL| pg_dump
    A -->|physical, want fast restore| pg_basebackup
    A -->|incremental from previous base| pg_basebackup_incr["pg_basebackup --incremental"]
    R[Need to restore?] -->|from pg_dump custom| pg_restore
    R -->|from pg_basebackup + WAL| recovery["restore_command + recovery.signal"]
    U[Major-version upgrade?] --> pg_upgrade
    F[After failover, salvage old primary?] --> pg_rewind
    D[Debug a recovery / replication issue?] --> pg_waldump
    Maint[Routine maintenance?] -->|VACUUM all DBs| vacuumdb
    Maint -->|REINDEX all DBs| reindexdb

Documenting individual tools

This wiki keeps the per-tool documentation light because the canonical reference is each tool's --help output and the SGML manual under doc/src/sgml/ref/. Where a tool is non-trivial enough to merit a dedicated note, the relevant subsystem's wiki page covers it (e.g., pg_basebackup is also discussed under Replication).

Each binary's directory has an SGML reference page: doc/src/sgml/ref/<binary>.sgml. Together they are what man postgres-binary prints.

Code-sharing layers

Frontend tools build on three strata:

• src/common/ — strict utility code that compiles in both the frontend and the backend (e.g., pg_lzcompress, wchar, file naming conventions, pg_crc32c).
• src/fe_utils/ — utilities that are frontend-only but shared across src/bin (e.g., simple_list, print table formatting, archive utilities).
• src/port/ — platform abstraction (only used when libc/sysstandards differ).

Frontend code uses pg_malloc / pg_strdup (src/common/fe_memutils.c), which exit(1) on OOM. There is no palloc here.

Entry points for modification

• Adding a feature to an existing tool: each src/bin/<tool>/ is self-contained C with its own Makefile; touch the source and make check runs the per-tool TAP suite.
• Adding a new binary: create src/bin/<newtool>/ with Makefile, meson.build, <newtool>.c. Add to src/bin/Makefile and src/bin/meson.build. Add an SGML reference page.

For client-library internals (which every tool uses) see libpq.