PostgreSQL 백업 중 server version mismatch 오류 해결법: pg_dump와 서버 버전 확인 순서

PostgreSQL 백업 중 server version mismatch 오류가 발생하면, 실제 실행된 pg_dump 버전부터 확인해야 한다. 이어서 백업 대상 서버의 메이저 버전을 비교하고, 복원할 서버의 버전까지 따로 점검하면 해결 방향이 선명해진다.

이 오류는 오래된 백업 도구가 더 새로운 서버를 읽으려 할 때 나타나는 대표적인 호환성 문제다. 도구를 설치했는데도 같은 오류가 반복된다면 설치 여부보다 실행 경로를 먼저 살펴볼 필요가 있다.

1. pg_dump 오류 문구에서 메이저 버전 불일치 확인하기

server version mismatch는 pg_dump와 접속한 PostgreSQL 서버 사이의 버전 호환성 문제를 뜻한다. 다음은 원본 서버가 16이고 도구가 15인 상황을 설명하기 위한 오류 예시이며, 세부 출력 형식은 도구 버전에 따라 달라질 수 있다.

pg_dump: error: aborting because of server version mismatch

PostgreSQL 16 공식 문서는 pg_dump가 자신보다 높은 메이저 버전의 서버를 덤프할 수 없다고 명시한다. 잘못된 덤프를 만들 위험을 피하기 위해 실행을 거부하는 동작이므로, 우선 도구와 서버의 메이저 번호를 비교해야 한다. 근거: [PostgreSQL 16 공식 문서의 호환성 설명](https://www.postgresql.org/docs/16/app-pgdump.html).

예를 들어 16.3과 16.8은 모두 메이저 버전이 16이다. 버전 문자열 전체가 다르다는 이유만으로 이 오류라고 판단하면 안 되며, 마이너 버전 차이와 메이저 버전 차이를 구분하는 것이 출발점이다.

1. pg_dump 오류 문구에서 메이저 버전 불일치 확인하기

2. pg_dump --version과 SHOW server_version 확인 순서

1. 백업 작업이 실행되는 환경에서 도구 버전을 확인한다. 개인 PC에서 성공해도 예약 작업이나 컨테이너에서는 다른 실행 파일을 사용할 수 있다.
2. 백업과 동일한 접속 정보로 원본 서버 버전을 조회한다. 호스트와 포트를 생략하면 의도와 다른 로컬 서버에 접속할 수 있다.
3. 복원 대상 서버에도 접속해 버전을 기록한다. 백업을 읽는 단계와 복원 SQL을 실행하는 단계의 호환성은 따로 판단한다.

터미널에서 실제 백업 도구 확인

pg_dump --version
pg_restore --version

--version은 도구 버전을 출력하고 종료하는 옵션이다. 반면 psql --version은 psql 프로그램의 버전만 보여주므로, 원격 PostgreSQL 서버 버전을 확인하는 명령으로 대신 사용할 수 없다. 근거: [PostgreSQL 18 pg_dump 공식 문서](https://www.postgresql.org/docs/18/app-pgdump.html).

원본 DB와 복원 대상 DB에서 서버 버전 확인

SHOW server_version;
SELECT version();

SHOW server_version;으로 버전을 간단히 확인하고, 상세한 서버 버전 문자열이 필요하면 SELECT version();을 실행한다. PostgreSQL 공식 문서에서 version()은 서버 버전 정보를 반환하는 함수로 설명한다. 근거: [PostgreSQL 서버 정보 함수 문서](https://www.postgresql.org/docs/18/functions-info.html).

접속 대상을 함께 기록하면 환경을 혼동하는 실수를 줄일 수 있다. 아래 명령의 source-host, backup_user, appdb는 실제 환경 값으로 바꾸며, 복원 대상은 대상 호스트와 계정으로 별도 조회한다.

2. pg_dump --version과 SHOW server_ver… 바로가기

psql -h source-host -p 5432 -U backup_user -d appdb -c "SHOW server_version;"

3. 백업 도구·원본 서버·복원 대상 버전 판단표

다음 표는 공식 호환 기준을 적용한 판단 예시다. 숫자는 실제 장애 통계가 아니라 버전 조합이며, ‘가능’은 버전 조건에 대한 판단이다. 권한, 확장 기능, 저장 공간 등의 다른 조건까지 충족했다는 뜻은 아니다.

2026년 11월 확인한 PostgreSQL 18 공식 문서에는 pg_dump 18이 PostgreSQL 9.2까지의 이전 서버를 지원한다고 명시돼 있다. 따라서 도구와 원본 서버가 항상 같은 버전이어야 한다는 해석은 정확하지 않다. 다만 이 수치는 덤프 도구의 입력 지원 범위이며, PostgreSQL 9.2의 유지보수 지원을 뜻하지 않는다. 근거: [PostgreSQL 18 공식 호환 기준](https://www.postgresql.org/docs/18/app-pgdump.html).

3. 백업 도구·원본 서버·복원 대상 버전 판단표 신청하기

4. pg_dump 버전을 맞췄는데 오류가 반복될 때 실행 경로 수정

원본이 16이고 기존 도구가 15라면, 원본과 같은 메이저 버전인 16의 클라이언트를 설치하는 방식이 단순하다. 서버 자체를 변경하기 전에 백업 실행 환경의 클라이언트 패키지를 교체하고, 설치 후 실제 선택되는 경로를 확인한다.

Ubuntu·Debian 계열에서는 해당 버전을 제공하는 저장소가 설정돼 있을 때 다음과 같이 설치할 수 있다. 패키지를 찾을 수 없다면 운영체제 릴리스와 PostgreSQL 패키지 저장소 구성을 먼저 확인해야 한다.

sudo apt install postgresql-client-16
/usr/lib/postgresql/16/bin/pg_dump --version

여러 버전을 함께 설치했다면 절대 경로로 실행하는 방법이 확실하다. 다음 경로는 Debian·Ubuntu 계열의 일반적인 패키지 배치 예시이며, 설치 방식에 따라 실제 위치는 달라진다.

/usr/lib/postgresql/16/bin/pg_dump -h source-host -p 5432 -U backup_user -d appdb -Fc -f appdb_verified.dump

Windows·예약 작업·컨테이너별 확인 지점

Windows PowerShell에서는 아래 명령으로 검색되는 실행 파일을 확인할 수 있다. 여러 경로가 나오면 백업 명령과 작업 스케줄러 설정에 사용할 파일을 명시한다.

Get-Command pg_dump -All
& "C:\Program Files\PostgreSQL\16\bin\pg_dump.exe" --version

예약 작업은 터미널과 PATH가 다를 수 있으므로 작업 정의에 실행 파일의 절대 경로를 넣는 편이 관리하기 쉽다. Docker나 CI에서 백업한다면 호스트 PC가 아니라 해당 컨테이너나 작업 이미지 안에서 pg_dump --version을 실행해야 한다.

GUI 도구를 사용한다면 백업 설정의 PostgreSQL 바이너리 경로도 살펴봐야 한다. 새 클라이언트를 설치한 뒤에도 GUI가 기존 폴더를 참조하면 같은 오류가 이어질 수 있다.

4. pg_dump 버전을 맞췄는데 오류가 반복될 때 실행 경로 수정 지원하기

5. 낮은 PostgreSQL 버전으로 복원할 때의 제약

더 새로운 pg_dump로 백업했다고 해서 더 오래된 서버에 복원할 수 있는 것은 아니다. PostgreSQL 문서는 도구보다 낮은 메이저 버전으로의 복원을 보장하지 않으며, 원래 그 버전의 서버에서 가져온 데이터라도 예외가 아니라고 설명한다. 근거: [PostgreSQL 16 공식 문서의 복원 제약](https://www.postgresql.org/docs/16/app-pgdump.html).

예를 들어 원본과 복원 대상이 모두 16이어도 pg_dump 18로 생성했다면, 대상 16이 이해하지 못하는 출력이 포함될 가능성을 검토해야 한다. 같은 버전으로 복구하는 목적이라면 원본과 같은 메이저의 도구를 우선 선택하고, 상위 버전 이전이라면 대상 버전 도구 사용을 검토하는 편이 합리적이다.

버전 간 이동에는 --quote-all-identifiers 사용이 권장된다. 테이블명과 컬럼명 같은 식별자를 인용해 버전별 예약어 차이로 생기는 문제를 줄이는 옵션이며, 새로운 SQL 기능을 오래된 문법으로 변환하는 기능은 아니다.

pg_dump -h source-host -p 5432 -U backup_user -d appdb --quote-all-identifiers -Fc -f appdb_cross_version.dump

하위 버전 복원이 필수라면 별도 검증 환경에서 스키마, 데이터 타입, 확장 기능의 지원 여부를 먼저 확인해야 한다. 지원되지 않는 객체는 대체 설계나 변환 작업이 필요할 수 있으며, 단순히 덤프 파일의 버전 표시를 고치는 방식으로 해결할 수 없다.

5. 낮은 PostgreSQL 버전으로 복원할 때의 제약 조회하기

6. 백업 재실행 후 pg_restore 복원 검증 체크리스트

도구 경로를 수정한 뒤에는 기존 실패 파일과 구분되는 새 파일명으로 백업을 다시 실행한다. 작업의 종료 코드와 오류 출력을 확인하고, 파일 크기가 0보다 크다는 이유만으로 성공 처리하지 않는다.

• 실제 실행된 pg_dump의 경로와 버전이 의도한 값인지 확인한다.
• 백업 종료 코드가 0인지 확인하고 경고·오류 로그를 검토한다.
• 사용자 정의 형식인 -Fc 파일은 pg_restore --list로 목차를 읽어본다.
• 대상과 같은 버전의 별도 테스트 DB에 복원하고 오류가 발생하면 중단되도록 설정한다.
• 핵심 테이블, 인덱스, 제약 조건, 시퀀스, 확장 기능과 애플리케이션 주요 조회를 점검한다.

다음은 앞서 생성한 사용자 정의 형식 파일을 확인하고 복원하는 예시다. restore_test는 미리 준비한 빈 테스트 DB이며, pg_restore도 선택한 도구 경로를 명시해 실행한다.

/usr/lib/postgresql/16/bin/pg_restore --list appdb_verified.dump
/usr/lib/postgresql/16/bin/pg_restore --exit-on-error -h test-host -U restore_user -d restore_test appdb_verified.dump

목차를 읽는 작업은 전체 복원을 대신하지 않는다. 또한 운영 중인 원본은 계속 바뀔 수 있으므로, 행 수를 대조할 때는 비교 기준 시점을 함께 정해야 결과를 잘못 해석하지 않는다.

운영 관점에서 중요한 개선은 백업 파일과 함께 도구 버전, 원본 버전, 예상 복원 대상 버전을 기록하는 것이다. 이 세 정보를 남기면 서버 업그레이드나 실행 이미지 변경 후 문제가 생겼을 때 호환 조건을 빠르게 재구성할 수 있다.

6. 백업 재실행 후 pg_restore 복원 검증 체크리스트 자세히 보기