psql

문서의 이전 판입니다!

[cli, postgres, postgresql, sql, client]

PostgreSQL interactive terminal이다. 대화형 SQL 실행, 스크립트 실행, 메타 커맨드 기반 점검에 가장 자주 쓰이는 기본 클라이언트다.

Summary

데이터베이스에 접속해 SQL과 \d, \l 같은 meta command를 실행한다.
-c로 단발성 SQL 실행, -f로 스크립트 실행, -X로 사용자 설정 파일 배제를 제어할 수 있다.
plain SQL dump 복원은 보통 psql -f backup.sql 형태로 처리한다.

psql [OPTION]... [DBNAME [USERNAME]]
psql -d appdb
psql -h 127.0.0.1 -p 5432 -U postgres -d appdb
psql -c 'SELECT now();' -d postgres
psql -f schema.sql -d appdb

psql [<switches>…] [DBNAME [USERNAME]]
psql -d DBNAME 대상 데이터베이스 지정
psql -h HOST -p PORT -U USER 원격 접속 정보 지정
psql -c COMMAND 단일 SQL 또는 internal command 실행 후 종료
psql -f FILE.sql 스크립트 파일 실행

-c, –command SQL 또는 internal command 한 번 실행 후 종료
-d, –dbname 접속할 데이터베이스 지정
-f, –file 파일에서 SQL 읽기
-l, –list 데이터베이스 목록 조회 후 종료
-v, –set, –variable psql 변수 설정. 예: -v ON_ERROR_STOP=1
-X, –no-psqlrc ~/.psqlrc를 읽지 않음
-1, –single-transaction 비대화형 실행을 단일 transaction으로 묶음
-A, –no-align unaligned 출력
-t, –tuples-only 결과 행만 출력
-x, –expanded expanded output
-h, –host 서버 호스트 또는 socket directory
-p, –port 서버 포트
-U, –username 접속 사용자
-w, –no-password 비밀번호 프롬프트 비활성화
-W, –password 비밀번호 프롬프트 강제

# 로컬 소켓으로 기본 사용자/DB 조합 접속
psql
 
# 특정 데이터베이스 접속
psql -d appdb
 
# 원격 서버 접속
psql -h 127.0.0.1 -p 5432 -U postgres -d appdb
 
# SQL 한 줄만 실행
psql -d appdb -c 'SELECT current_database(), current_user;'
 
# 에러 발생 시 즉시 중단하도록 스크립트 실행
psql -X -v ON_ERROR_STOP=1 -d appdb -f ./schema.sql
 
# plain SQL dump 복원
psql -X -v ON_ERROR_STOP=1 -d appdb -f ./backup.sql

접속 실패 시 PGHOST, PGPORT, PGUSER, PGDATABASE 환경 변수와 CLI 옵션 충돌 여부를 함께 확인한다.
automation에서는 -X와 -v ON_ERROR_STOP=1 조합을 쓰면 사용자별 .psqlrc 영향과 중간 실패 누락을 줄일 수 있다.
peer authentication failed가 나오면 Unix socket 접속과 pg_hba.conf 정책을 먼저 확인한다.
대화형 세션에서 object 탐색은 \dt, \dv, \du, \dn, \dx가 빠르다.

\l 데이터베이스 목록
\c DBNAME 데이터베이스 전환
\dt 테이블 목록
\d NAME object 상세
\du role 목록
\dn schema 목록
\i FILE.sql 스크립트 실행
\o FILE 결과를 파일로 저장
\q 종료

pg_dump의 plain format 출력은 보통 pg_restore가 아니라 psql로 복원한다. 반대로 custom, directory, tar format archive는 pg_restore로 다루는 편이 일반적이다.

이 페이지의 도움말은 로컬 설치된 PostgreSQL client 기준으로 정리했다.
현재 환경의 psql –help에는 기본 DB와 기본 사용자 예시가 master로 보인다. 다른 시스템에서는 현재 OS 사용자명이나 배포판 설정에 따라 값이 다를 수 있다.

psql --help

psql is the PostgreSQL interactive terminal.
 
Usage:
  psql [OPTION]... [DBNAME [USERNAME]]
 
General options:
  -c, --command=COMMAND    run only single command (SQL or internal) and exit
  -d, --dbname=DBNAME      database name to connect to (default: "master")
  -f, --file=FILENAME      execute commands from file, then exit
  -l, --list               list available databases, then exit
  -v, --set=, --variable=NAME=VALUE
                           set psql variable NAME to VALUE
                           (e.g., -v ON_ERROR_STOP=1)
  -V, --version            output version information, then exit
  -X, --no-psqlrc          do not read startup file (~/.psqlrc)
  -1 ("one"), --single-transaction
                           execute as a single transaction (if non-interactive)
  -?, --help[=options]     show this help, then exit
      --help=commands      list backslash commands, then exit
      --help=variables     list special variables, then exit
 
Input and output options:
  -a, --echo-all           echo all input from script
  -b, --echo-errors        echo failed commands
  -e, --echo-queries       echo commands sent to server
  -E, --echo-hidden        display queries that internal commands generate
  -L, --log-file=FILENAME  send session log to file
  -n, --no-readline        disable enhanced command line editing (readline)
  -o, --output=FILENAME    send query results to file (or |pipe)
  -q, --quiet              run quietly (no messages, only query output)
  -s, --single-step        single-step mode (confirm each query)
  -S, --single-line        single-line mode (end of line terminates SQL command)
 
Output format options:
  -A, --no-align           unaligned table output mode
  -F, --field-separator=STRING
                           field separator for unaligned output (default: "|")
  -H, --html               HTML table output mode
  -P, --pset=VAR[=ARG]     set printing option VAR to ARG (see \pset command)
  -R, --record-separator=STRING
                           record separator for unaligned output (default: newline)
  -t, --tuples-only        print rows only
  -T, --table-attr=TEXT    set HTML table tag attributes (e.g., width, border)
  -x, --expanded           turn on expanded table output
  -z, --field-separator-zero
                           set field separator for unaligned output to zero byte
  -0, --record-separator-zero
                           set record separator for unaligned output to zero byte
 
Connection options:
  -h, --host=HOSTNAME      database server host or socket directory (default: "local socket")
  -p, --port=PORT          database server port (default: "5432")
  -U, --username=USERNAME  database user name (default: "master")
  -w, --no-password        never prompt for password
  -W, --password           force password prompt (should happen automatically)

History

codex:: 2026-06-22 Reorganized psql into a structured CLI reference with connection, scripting, and restore workflow notes.

psql

Summary

Usage

Options

Examples

Troubleshooting

Internal Commands

Compatibility

Help

See Also

History

Command Line Interface Helper