POSTGRESQL TRIAGE
SAFE OPERATING BOUNDARY
application pool·timeout·release 변경은 기록한 이전 정상 설정과 표준 배포 절차로 되돌립니다. pg_cancel_backend로 취소된 query는 자동 복구되지 않으며 pg_terminate_backend는 열린 transaction을 rollback하므로 업무 idempotency와 외부 side effect를 확인합니다. replay resume은 데이터 변경을 되돌리는 명령이 아니며, 원래 승인된 지연 복제 목적이 있을 때만 담당자 확인 후 별도 절차로 pause를 복구합니다.
BEFORE YOU START
CHECK THE BRANCH
max_connections만 올리기 전에 상태별·DB별·사용자별·application_name별 연결 수와 pool 설정을 확인합니다. idle in transaction은 단순 idle과 달리 락과 vacuum 진행을 방해할 수 있습니다.
query 원문 대신 query_id, 실행 시간, wait event와 pg_blocking_pids를 사용해 범위를 좁힙니다. query_id는 compute_query_id 설정과 pg_stat_statements·query ID 계산 상태에 따라 NULL일 수 있으므로 NULL을 정상·이상 판정으로 단정하지 않습니다. pg_stat_statements가 사전에 활성화되지 않았다면 장애 중 재시작해 켜지 않습니다.
sent·write·flush·replay LSN의 바이트 차이와 WAL receiver 상태를 함께 봅니다. write_lag·replay_lag는 idle 시 NULL이 될 수 있고 따라잡을 예상 시간을 뜻하지 않습니다.
장기 transaction이 WAL 보존과 락을 늘리고 과도한 연결이 CPU·I/O를 악화할 수 있습니다. 동일 시각 스냅샷을 남긴 뒤 최초 원인과 2차 증상을 분리합니다.
FOLLOW THE FLOW
비밀번호를 명령행이나 URI에 넣지 않습니다. 사전에 검토한 libpq service와 0600 패스워드 파일을 사용하고, SQL 원문을 조회하지 않는 집계부터 실행합니다.
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT version(), current_database(), pg_is_in_recovery(), clock_timestamp();"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT datname, usename, application_name, state, count(*) AS sessions, max(clock_timestamp() - state_change) AS oldest_state FROM pg_stat_activity WHERE pid <> pg_backend_pid() GROUP BY datname, usename, application_name, state ORDER BY sessions DESC;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT coalesce(wait_event_type, 'CPU_or_not_waiting') AS wait_type, coalesce(wait_event, '-') AS wait_event, count(*) AS sessions FROM pg_stat_activity WHERE pid <> pg_backend_pid() GROUP BY wait_event_type, wait_event ORDER BY sessions DESC;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT application_name, state, sync_state, sent_lsn, write_lsn, flush_lsn, replay_lsn, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn)) AS replay_byte_lag, write_lag, flush_lag, replay_lag, reply_time FROM pg_stat_replication ORDER BY application_name;"연결 수만 높으면 pool·누수 분기를, blocking PID와 Lock wait가 있으면 락 분기를, primary에서 replay LSN 차이가 크거나 standby receiver가 비정상이면 복제 분기를 우선합니다.
설정 상한과 PID 단위 대기·blocking 관계를 읽기 전용으로 확인합니다.
각 분기는 필요한 명령만 실행합니다. 통계 view 권한이 부족하면 superuser 비밀번호를 공유받지 말고 DBA에게 최소 pg_monitor 또는 pg_read_all_stats 역할로 수집을 요청합니다.
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT current_setting('max_connections') AS max_connections, current_setting('superuser_reserved_connections') AS superuser_reserved, current_setting('reserved_connections', true) AS reserved_connections;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pid, datname, usename, application_name, state, wait_event_type, wait_event, clock_timestamp() - xact_start AS xact_age, clock_timestamp() - query_start AS query_age, query_id, pg_blocking_pids(pid) AS blocking_pids FROM pg_stat_activity WHERE pid <> pg_backend_pid() AND (wait_event_type IS NOT NULL OR state = 'idle in transaction') ORDER BY xact_start NULLS LAST;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT queryid, calls, round(total_exec_time::numeric, 1) AS total_ms, round(mean_exec_time::numeric, 1) AS mean_ms, rows, shared_blks_read, temp_blks_written FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pg_is_in_recovery(), pg_is_wal_replay_paused(), pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn(), pg_last_xact_replay_timestamp(); SELECT status, sender_host, sender_port, slot_name, latest_end_lsn, latest_end_time, last_msg_receipt_time FROM pg_stat_wal_receiver;"blocking_pids가 비어 있고 유효한 query_id의 누적 시간만 크면 실행 계획·I/O 분기, blocker가 있으면 transaction 소유자 분기입니다. query_id가 NULL이면 compute_query_id·extension 상태와 다른 증거를 확인하고 임의로 같은 SQL을 묶지 않습니다. receive LSN은 전진하지만 replay LSN이 멈추면 replay·standby 부하를, 둘 다 멈추면 sender·network·slot을 봅니다.
취소·종료 또는 replay resume 전에 로그·timeout·pool·배포 변경 이력을 확보합니다.
로그에는 SQL literal과 개인정보가 포함될 수 있습니다. 제한된 터미널에서 오류 코드와 시각 주변만 확인하고, 외부 전달본은 SQL·client address·role을 마스킹합니다.
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SHOW statement_timeout; SHOW lock_timeout; SHOW idle_in_transaction_session_timeout; SHOW deadlock_timeout; SELECT extversion FROM pg_extension WHERE extname = 'pg_stat_statements';"journalctl -u <POSTGRESQL_SERVICE>.service --since '<INCIDENT_START>' --until '<INCIDENT_END>' --no-pager | grep -Ei -C 3 'too many clients|remaining connection slots|deadlock detected|lock timeout|canceling statement|replication|wal receiver|could not receive data'git -C <APPLICATION_REPOSITORY> diff <LAST_KNOWN_GOOD_REVISION> -- <REVIEWED_POOL_AND_DATABASE_CONFIG_PATH>install -d -m 0700 <APPROVED_EVIDENCE_DIR>
umask 077
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --tuples-only --no-align --command "SELECT clock_timestamp(), count(*) FILTER (WHERE state = 'active'), count(*) FILTER (WHERE state = 'idle in transaction'), count(*) FILTER (WHERE wait_event_type = 'Lock') FROM pg_stat_activity;" > <APPROVED_EVIDENCE_DIR>/postgresql-incident-counts.txt
chmod 0600 <APPROVED_EVIDENCE_DIR>/postgresql-incident-counts.txt장기 transaction 소유자, connection pool 상한 합계, query ID 통계, 복제 LSN 구간과 직전 배포를 한 타임라인에 놓습니다. 로그에서 본 SQL literal을 티켓에 그대로 붙이지 않습니다.
업무 소유자와 DBA가 승인한 최소 조치 한 가지만 선택합니다.
대상 PID·업무 영향·transaction rollback 가능성을 확인합니다. max_connections 즉시 증설, PostgreSQL 재시작, replication slot 삭제, standby promote는 이 가이드의 즉시 조치가 아닙니다.
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pg_cancel_backend(<APPROVED_PID>);"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pg_terminate_backend(<APPROVED_PID>, 5000);"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pg_wal_replay_resume();"git -C <APPLICATION_REPOSITORY> diff --check <LAST_KNOWN_GOOD_REVISION> -- <REVIEWED_POOL_AND_DATABASE_CONFIG_PATH>cancel은 query 취소, terminate는 session과 열린 transaction 종료, replay_resume은 standby apply 재개입니다. 서로 대체 관계가 아니며 원인에 맞지 않는 명령을 함께 실행하지 않습니다.
동일 조회를 반복해 연결 여유·wait·WAL 진전과 업무 정확성을 확인하고, 악화되면 승인된 이전 상태로 복구합니다.
변경 직후와 정상 트래픽 구간을 나눠 확인합니다. 숫자가 잠깐 좋아진 것만으로 종료하지 말고 application error rate와 transaction 정확성도 함께 검증합니다.
psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT state, wait_event_type, wait_event, count(*) FROM pg_stat_activity WHERE pid <> pg_backend_pid() GROUP BY state, wait_event_type, wait_event ORDER BY count(*) DESC;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pid, application_name, query_id, pg_blocking_pids(pid) AS blocking_pids, clock_timestamp() - query_start AS query_age FROM pg_stat_activity WHERE cardinality(pg_blocking_pids(pid)) > 0 ORDER BY query_start;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT application_name, state, sync_state, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn)) AS replay_byte_lag, replay_lag, reply_time FROM pg_stat_replication ORDER BY application_name;"psql "service=<PGSERVICE>" -X --set=ON_ERROR_STOP=1 --command "SELECT pg_is_wal_replay_paused(), pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn(), pg_last_xact_replay_timestamp(), clock_timestamp();"새 연결이 안정적으로 수용되고 blocking chain이 해소되며 query ID latency와 WAL byte lag가 정상 기준으로 돌아와야 합니다. idle primary의 lag interval NULL은 단독 실패 신호가 아닙니다.
pool·release 변경은 이전 정상 버전으로 되돌립니다. 취소된 query는 자동 재실행하지 않고 업무 idempotency를 확인하며, 종료된 transaction은 rollback 여부를 확인해 보정합니다. replay를 다시 pause하는 것은 원래 승인 목적이 명확한 경우에만 별도 승인합니다.
PRIMARY REFERENCES
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.