API 개발자에게 가장 중요한 PostgreSQL 19 신규 기능: 한 문장으로 get-or-create 엔드포인트를 구현하는 INSERT ... ON CONFLICT DO SELECT, 레플리카에서 read-your-writes를 보장하는 WAIT FOR LSN, 온라인 블로트 정리를 위한 REPACK (CONCURRENTLY), COPY의 JSON 출력, 새로운 jsonpath 문자열 메서드, 그리고 대량 삽입 시 더 빨라진 외래 키 검사입니다.
이 가이드는 핸들러, 레플리카, 업그레이드 계획에서 무엇이 달라지는지 다룹니다. 모든 문법 예제는 PostgreSQL 19 릴리스 노트와 레퍼런스 문서에서 가져왔습니다.
PostgreSQL 19의 새로운 기능 한눈에 보기
PostgreSQL 19는 오픈 소스 데이터베이스의 연간 메이저 릴리스로, 2026년 11월 19일 PostgreSQL Global Development Group에서 발표되었습니다. get-or-create 삽입, read-your-writes를 위한 레플리카 대기, 온라인 테이블 리패킹, 플랜 어드바이스, 시퀀스의 논리적 복제가 추가되었으며, 업그레이드 전에 확인해야 할 여러 기본값이 변경되었습니다.
| 기능 | 대체하는 기능 | 체감되는 부분 |
|---|---|---|
ON CONFLICT DO SELECT |
SELECT 후 INSERT 재시도 루프 | 멱등성 POST 및 회원가입 엔드포인트 |
WAIT FOR LSN |
쓰기 후 읽기를 프라이머리로 고정하는 라우팅 | API 뒤의 읽기 레플리카 |
REPACK (CONCURRENTLY) |
VACUUM FULL, CLUSTER, pg_repack |
블로트가 심한 핫 테이블, 무중단 처리 |
COPY ... (FORMAT json) |
애플리케이션 코드에서의 행-JSON 변환 | 내보내기 및 대량 다운로드 엔드포인트 |
jsonpath 문자열 메서드 |
애플리케이션 코드에서의 JSONB 후처리 | JSON 컬럼의 필터링 및 정규화 |
pg_plan_advice + pg_stash_advice |
플래너를 유도하기 위한 쿼리 재작성 | 운영 환경의 플랜 성능 저하 |
FOR ALL SEQUENCES 퍼블리케이션 |
전환(cutover) 후 수동 시퀀스 리셋 | 논리적 복제를 통한 블루-그린 업그레이드 |
공식 릴리스 발표에는 병렬 인덱스 vacuuming과 자동 확장되는 비동기 I/O 워커도 소개되어 있습니다. 이 기능들은 API가 보내는 SQL에 영향을 주지 않으므로 이 글에서는 다루지 않습니다.
ON CONFLICT DO SELECT: 한 문장으로 처리하는 get-or-create
모든 API에는 행이 존재하든 아니든 해당 행을 반환해야 하는 엔드포인트가 있습니다. 디바이스 등록, 태그 생성, 멱등성 결제 시작 등이 그 예입니다. 19 버전 이전에는 SELECT 후 INSERT를 실행하거나(부하 상황에서 경쟁 상태에 패배함), RETURNING이 동작하도록 하기 위해 무의미한 ON CONFLICT DO UPDATE를 작성해야 했고, 이는 아무 필요 없이 새로운 행 버전을 기록하는 일이었습니다.
PostgreSQL 19는 네 번째 충돌 동작을 추가했습니다. INSERT 레퍼런스는 이를 "멱등적인 삽입 또는 get or create"라고 부릅니다:
INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
ON CONFLICT (did) DO SELECT
RETURNING *;
did = 11이 비어 있으면 행이 삽입되고 반환됩니다. 이미 존재하면 기존 행이 반환되고 아무 것도 수정되지 않습니다. 문서에 나온 세 가지 규칙:
DO SELECT에는RETURNING절이 필수입니다.DO UPDATE와 마찬가지로conflict_target이 필요합니다.- 배타 제약 조건은 arbiter로 사용할 수 없습니다. 유니크 인덱스나
NOT DEFERRABLE유니크 제약 조건을 사용하세요.

핸들러는 보통 201 Created 또는 200 OK로 응답할 수 있도록 어느 분기가 실행되었는지 알아야 합니다. 문서에 따르면 행이 충돌했을 때 RETURNING의 old 값들이 NULL이 아니게 되므로, 하나의 컬럼으로 판단할 수 있습니다:
INSERT INTO users (email, name) VALUES ($1, $2)
ON CONFLICT (email) DO SELECT
RETURNING *, (old.id IS NULL) AS created;
관련 테이블을 다루기 전에 기존 행을 잠그고 싶으신가요? 잠금 절을 추가하세요: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. WHERE로 필터링할 수도 있습니다. 예를 들어 DO SELECT WHERE d.dname != EXCLUDED.dname처럼 사용하면 조건을 통과하는 행만 반환됩니다.
권한: DO SELECT에는 테이블에 대한 SELECT 권한이 필요하고, FOR UPDATE/FOR SHARE 형태는 최소 한 컬럼에 대한 UPDATE 권한도 필요합니다.
WAIT FOR LSN: 레플리카에서의 read-your-writes
전형적인 레플리카 버그: 사용자가 프로필을 저장했는데, 다음 GET 요청이 아직 변경 사항을 재생하지 않은 비동기 레플리카에 도착하면 예전 데이터가 반환됩니다. 대부분의 팀은 쓰기 후 읽기를 프라이머리로 고정하는데, 이는 레플리카를 낭비하는 셈입니다.
PostgreSQL 19는 WAIT FOR 명령을 추가했습니다. 쓰기 후 프라이머리의 WAL 위치를 가져옵니다:
UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
SELECT pg_current_wal_insert_lsn(); -- returns 0/0306EE20
그 LSN을 사용자 세션에 저장하세요(Simon Willison이 자신의 글에서 서명된 쿠키 사용을 제안했습니다). 다음 요청에서 읽기 전에 레플리카에서 아래를 실행합니다:
WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW);
SELECT * FROM movie WHERE genre = 'Drama';

API에서 중요한 세부 사항들:
- 모드. 기본값인
MODE 'standby_replay'는 변경 사항이 적용될 때까지 기다리며, 이것이 read-your-writes에 필요한 동작입니다.standby_write,standby_flush,primary_flush는 내구성 검사용으로 존재합니다. - 타임아웃.
TIMEOUT이 없거나TIMEOUT '0'이면 영원히 기다립니다. 요청 경로에서는 반드시 타임아웃을 설정하세요. NO_THROW. 이 옵션이 없으면 타임아웃 시 에러가 발생하고 트랜잭션이 중단됩니다. 있으면success,timeout,not in recovery상태가 반환되어 프라이머리로 폴백할 수 있습니다.- 위치.
WAIT는 최상위 명령이어야 하며, 함수나DO블록 안에 있을 수 없습니다. 트랜잭션 밖에서 실행하거나, 잠금을 획득하는 작업 전에 트랜잭션의 첫 번째 문장으로 실행해야 하며, 그렇지 않으면 거부됩니다.
REPACK (CONCURRENTLY), 라이브 테이블의 VACUUM FULL 대체
sessions나 webhook_deliveries처럼 트래픽이 많은 엔드포인트 뒤의 테이블은 블로트가 빠르게 쌓입니다. VACUUM FULL과 CLUSTER가 이를 해결하지만 테이블을 잠급니다. PostgreSQL 19는 온라인 옵션을 추가했습니다:
REPACK (CONCURRENTLY) webhook_deliveries;
REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx;
릴리스 노트에 따르면 REPACK (CONCURRENTLY)는 읽기나 쓰기를 차단하지 않으면서 공간을 회수하고 인덱스 기준으로 테이블을 재정렬할 수 있습니다. VACUUM FULL과 CLUSTER는 호환성을 위해 유지됩니다. 새로운 pg_stat_progress_repack 뷰에서 진행 상황을 확인하고, 클러스터를 튜닝할 때 새로운 max_repack_replication_slots 서버 설정을 살펴보세요.
COPY의 JSON 출력과 새로운 jsonpath 문자열 메서드
내보내기 엔드포인트는 행을 JSON으로 변환하기 위해 애플리케이션 코드를 통해 스트리밍하는 경우가 많습니다. 이제 COPY TO가 COPY 레퍼런스에 따라 데이터베이스에서 이 작업을 수행할 수 있습니다:
COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY);
이 명령은 [, {"id":1}, ,{"id":2}, ]를 각각 별도의 줄에 출력하므로 결과는 하나의 유효한 JSON 배열입니다. FORCE_ARRAY 없이는 줄마다 하나의 JSON 객체가 출력되어 NDJSON 친화적입니다. SQL NULL은 JSON null로 변환되며, json 형식은 COPY TO에서만 동작합니다.
JSONB 컬럼의 경우 jsonpath에 문자열 메서드가 추가되었습니다: lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace(), split_part(). 문서의 예제:
jsonb_path_query('"TOM"', '$.lower()') -- "tom"
jsonb_path_query('" hello "', '$.btrim()') -- "hello"
jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)') -- "ghi"
릴리스 노트는 이 메서드들을 immutable로 표시하며, 이를 통해 JSONB 필드를 정규화(트림, 소문자화, 분할)하는 작업을 핸들러가 아닌 쿼리 안에서 수행할 수 있습니다.
또한, 행이 없을 때 json_array()는 이제 NULL 대신 []를 반환합니다. 이는 null을 검사하는 클라이언트를 깨뜨릴 수 있습니다.
API 팀이 알아야 할 기타 PostgreSQL 19 변경 사항
- 더 빨라진 외래 키 검사. 발표에 따르면 테스트에서 대량 삽입이 거의 2배 빨라졌습니다. 자식 행을 기록하는 임포트 엔드포인트에 유용합니다.
- 플랜 어드바이스.
pg_plan_advice확장은 플래너의 선택을 고정하고,pg_stash_advice는 쿼리 ID 기준으로 해당 어드바이스를 적용합니다. 따라서 재배포 없이 성능이 저하된 쿼리를 수정할 수 있습니다. - UUID와 인코딩.
bytea와uuid간 캐스팅이 가능하며,encode()/decode()가base64url(경로와 토큰의 ID에 사용되는 URL 안전 형식)을 지원합니다. - 업그레이드를 위한 논리적 복제.
CREATE PUBLICATION all_sequences FOR ALL SEQUENCES;는 시퀀스를 동기화하고,FOR ALL TABLES EXCEPT (TABLE users, departments)는 테이블을 제외합니다. 이는 블루-그린 마이그레이션에서 "전환 후 ID 충돌" 문제를 해소합니다.
업그레이드 전에 확인해야 할 호환성 깨짐 변경 사항
릴리스 노트의 마이그레이션 섹션에는 스테이징 환경에서 쿼리 하나도 실패하지 않고도 API에 영향을 줄 수 있는 변경 사항들이 나열되어 있습니다:
| PostgreSQL 19의 변경 사항 | 확인할 항목 |
|---|---|
max_locks_per_transaction 기본값이 64에서 128로 변경, 기존 설정은 두 배로 조정해야 함 |
설정 파일 또는 관리형 서비스 파라미터 그룹의 커스텀 값 |
| JIT 기본 비활성화 | 긴 쿼리에 JIT를 의존하던 분석 엔드포인트 |
기본 TOAST 압축이 pglz에서 lz4로 변경 |
기능은 문제없으나 저장소와 CPU 프로파일이 달라짐 |
standard_conforming_strings가 강제로 on |
off 상태로 덤프한 오래된 덤프는 복원되지 않음 |
| MD5 비밀번호 인증 시 경고 로그 기록, RADIUS 제거 | 앱 역할을 SCRAM-SHA-256으로 전환 |
행이 없을 때 json_array()가 [] 반환 |
null을 검사하는 클라이언트 |
READ ONLY가 postgres_fdw로 전달됨 |
외래 테이블을 통해 쓰기를 수행한 읽기 전용 트랜잭션 |
log_lock_waits 기본 활성화 |
로그 볼륨과 알림 노이즈 |
이전 메이저 버전에서의 업그레이드는 여전히 pg_upgrade, pg_dumpall 덤프 및 복원, 또는 논리적 복제가 필요합니다. PostgreSQL 14를 사용 중이라면 지금 이전을 계획하세요. 버전 관리 정책에 따르면 PostgreSQL 14의 최종 릴리스는 2026년 11월 12일이었습니다.
Apidog CLI로 코딩 에이전트에게 업그레이드 후 API 회귀 테스트 맡기기
Postgres 메이저 업그레이드는 SQL 문법을 깨뜨리는 경우가 드뭅니다. 깨뜨리는 것은 동작입니다. []를 반환하는 json_array(), 잠금 한도, 느려진 플랜 등이 그 예입니다. PostgreSQL 19 스테이징 데이터베이스를 대상으로 API의 테스트 시나리오를 실행하고, HTTP 응답과 그 이면의 행을 검증(assertion)하면 이를 잡아낼 수 있습니다. Apidog CLI로 코딩 에이전트에게 이 작업을 맡겨보세요.
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
그런 다음 에이전트에게 프롬프트 하나를 주면 됩니다:
In Apidog project <projectId>, add a test case for POST /users that sends the same
email twice and asserts the first call returns 201 and the second returns 200 with the
same id. Then run test scenario <scenarioId> against the pg19-staging environment with
database assertions, and summarize every failure next to the PostgreSQL 19 change
that could explain it.
에이전트는 페이로드 스키마를 읽고 검증한 뒤 테스트 케이스를 생성하고, 데이터베이스 연결 파일과 함께 시나리오를 실행하여 데이터베이스 단계가 새 클러스터에 적용되도록 합니다:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
--database-connection ./database-connections.json -r cli,junit
Apidog의 데이터베이스 기능은 Free 플랜에서 PostgreSQL을 지원하므로, 각 요청 후 테이블을 조회하여 get-or-create 엔드포인트가 정확히 한 행을 기록했는지 검증할 수 있습니다. 문서에서는 API 테스트에서의 데이터베이스 쿼리와 CLI에서 데이터베이스 연결로 시나리오 실행하기를 안내합니다. 동일한 apidog run ... -r junit 명령을 CI 파이프라인에 넣으면 이후 모든 마이너 릴리스에 동일한 검사가 적용됩니다. 에이전트가 Postgres에 직접 쿼리하도록 하고 싶다면 PostgreSQL MCP 서버 가이드를 참고하세요.
FAQ
PostgreSQL 19는 언제 출시되었나요? 2026년 11월 19일입니다. PostgreSQL 프로젝트는 각 메이저 버전을 5년간 지원하므로, 19 버전은 2031년 11월 19일까지 수정 사항을 받습니다.
ON CONFLICT DO SELECT는 upsert와 같은가요? 아닙니다. DO UPDATE는 기존 행을 변경하지만, DO SELECT는 그대로 반환합니다. get-or-create와 멱등성 POST에 사용하세요. RETURNING 절과 충돌 대상(conflict target)이 필요합니다.
WAIT FOR LSN은 프라이머리에서도 동작하나요? 기본 standby_replay 모드는 복구 중인 스탠바이에서만 동작합니다. 프라이머리에서는 에러가 발생하거나, NO_THROW 사용 시 not in recovery가 반환됩니다. 프라이머리 자체에서 대기해야 한다면 MODE 'primary_flush'를 사용하세요.
PostgreSQL 18에서 19로 인플레이스 업그레이드가 가능한가요? 네, pg_upgrade로 가능합니다. 덤프 후 복원이나 논리적 복제도 사용할 수 있으며, 이제는 FOR ALL SEQUENCES로 시퀀스도 복제됩니다. 먼저 위의 호환성 깨짐 변경 사항 표를 검토하세요.
PostgreSQL 19가 pg_repack을 대체하나요? 대부분의 경우 그렇습니다. REPACK (CONCURRENTLY)는 읽기나 쓰기를 차단하지 않고 블로트를 회수하고 인덱스 기준으로 테이블을 재정렬하며, 코어에 포함되어 있습니다.
