{{tag>[cli postgres postgresql backup dump]}} ====== 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** [...] [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는 [[postgresql: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

++++ ===== See Also ===== * [[postgresql:psql]] * [[postgresql:pg_restore]] * [[postgresql:command]] ===== History ===== * codex:: 2026-06-22 Rebuilt pg_dump as a structured backup reference with format selection, examples, and restore guidance.