pg_dump

PostgreSQL 데이터베이스를 logical backup으로 내보내는 명령이다. plain SQL, custom archive, directory, tar format을 지원하며 schema-only 또는 data-only dump에도 자주 쓴다.

Summary

단일 database 또는 schema/table 단위 logical backup 생성에 사용한다.
복원 경로를 생각하면 -F c custom format이나 -F d directory format이 유연하다.
plain SQL dump는 사람이 읽기 쉽고 diff가 가능하지만, 복원은 일반적으로 psql로 수행한다.

Usage

pg_dump [OPTION]... [DBNAME]
pg_dump -d appdb -f appdb.sql
pg_dump -Fc -d appdb -f appdb.dump
pg_dump -Fd -j 4 -d appdb -f appdb.dir

pg_dump [<switches>…] [DBNAME]
pg_dump -f FILE 출력 파일 또는 디렉터리 지정
pg_dump -F p|c|d|t 출력 형식 지정
pg_dump -s schema-only dump
pg_dump -a data-only dump
pg_dump -n SCHEMA, -t TABLE 범위 제한

Options

-f, –file 출력 파일 또는 directory 이름
-F, –format p plain, c custom, d directory, t tar
-j, –jobs 병렬 dump worker 수. directory format에서 자주 사용
-Z, –compress 압축 레벨 지정
-a, –data-only 데이터만 dump
-s, –schema-only schema만 dump
-c, –clean 복원 전에 object drop SQL 포함
-C, –create database 생성 SQL 포함
-n, –schema 특정 schema만 dump
-N, –exclude-schema 특정 schema 제외
-t, –table 특정 table만 dump
-T, –exclude-table 특정 table 제외
-O, –no-owner ownership 복원 정보 생략
-x, –no-privileges GRANT/REVOKE 정보 생략
-h, –host, -p, -U 접속 정보 지정 (미지정시 소켓연결)

Examples

# 사람이 읽을 수 있는 plain SQL dump
pg_dump -d appdb -f ./appdb.sql
 
# pg_restore로 다루기 좋은 custom archive
pg_dump -Fc -d appdb -f ./appdb.dump
 
# 병렬 dump용 directory format
pg_dump -Fd -j 4 -d appdb -f ./appdb.dir
 
# schema만 백업
pg_dump -s -d appdb -f ./appdb-schema.sql
 
# data만 백업
pg_dump -a -d appdb -f ./appdb-data.sql
 
# 특정 schema만 백업
pg_dump -n public -d appdb -f ./public.sql
 
# 특정 table만 백업
pg_dump -t public.users -d appdb -f ./users.sql

Troubleshooting

long-running transaction과 lock 대기가 심하면 –lock-wait-timeout을 검토한다.
restore 대상을 유연하게 제어하려면 plain SQL보다 -Fc 또는 -Fd가 보통 낫다.
ownership이나 privilege 차이 때문에 복원 실패가 예상되면 backup 단계에서 -O -x 조합을 검토한다.
very large database는 logical dump보다 physical backup 전략이 더 적절할 수 있다.

Compatibility

logical backup은 major version 간 이식성에 유리하지만, extension과 collation, role 구조 차이는 별도 확인이 필요하다.
plain format은 psql로 복원하고, custom/directory/tar archive는 pg_restore로 복원하는 흐름이 일반적이다.

pg_dump는 백업 생성 도구다. plain SQL dump에 -c 또는 -C를 넣으면 복원 시 기존 object를 drop하거나 database를 다시 만들 수 있으므로 production 적용 전에 내용을 확인한다.

Help

pg_dump --help

pg_dump dumps a database as a text file or to other formats.
 
Usage:
  pg_dump [OPTION]... [DBNAME]
 
General options:
  -f, --file=FILENAME          output file or directory name
  -F, --format=c|d|t|p         output file format (custom, directory, tar,
                               plain text (default))
  -j, --jobs=NUM               use this many parallel jobs to dump
  -v, --verbose                verbose mode
  -V, --version                output version information, then exit
  -Z, --compress=0-9           compression level for compressed formats
  --lock-wait-timeout=TIMEOUT  fail after waiting TIMEOUT for a table lock
  --no-sync                    do not wait for changes to be written safely to disk
  -?, --help                   show this help, then exit
 
Options controlling the output content:
  -a, --data-only              dump only the data, not the schema
  -b, --blobs                  include large objects in dump
  -B, --no-blobs               exclude large objects in dump
  -c, --clean                  clean (drop) database objects before recreating
  -C, --create                 include commands to create database in dump
  -E, --encoding=ENCODING      dump the data in encoding ENCODING
  -n, --schema=SCHEMA          dump the named schema(s) only
  -N, --exclude-schema=SCHEMA  do NOT dump the named schema(s)
  -o, --oids                   include OIDs in dump
  -O, --no-owner               skip restoration of object ownership in
                               plain-text format
  -s, --schema-only            dump only the schema, no data
  -S, --superuser=NAME         superuser user name to use in plain-text format
  -t, --table=TABLE            dump the named table(s) only
  -T, --exclude-table=TABLE    do NOT dump the named table(s)
  -x, --no-privileges          do not dump privileges (grant/revoke)
  --disable-triggers           disable triggers during data-only restore
  --exclude-table-data=TABLE   do NOT dump data for the named table(s)
  --if-exists                  use IF EXISTS when dropping objects
  --inserts                    dump data as INSERT commands, rather than COPY
  --no-publications            do not dump publications
  --no-security-labels         do not dump security label assignments
  --no-subscriptions           do not dump subscriptions
  --no-tablespaces             do not dump tablespace assignments
  --section=SECTION            dump named section (pre-data, data, or post-data)
 
Connection options:
  -d, --dbname=DBNAME      database to dump
  -h, --host=HOSTNAME      database server host or socket directory
  -p, --port=PORT          database server port number
  -U, --username=NAME      connect as specified database user
  -w, --no-password        never prompt for password
  -W, --password           force password prompt (should happen automatically)
  --role=ROLENAME          do SET ROLE before dump

History

codex:: 2026-06-22 Rebuilt pg_dump as a structured backup reference with format selection, examples, and restore guidance.

목차