PostgreSQL 58P02 오류 원인과 해결 방법 완벽 가이드

58P02
2026년 07월 21일 | DBMS Error 가이드

이 글에서 다루는 내용

58P02 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

58P02 duplicate file 는?

PostgreSQL 에러 코드 58P02 duplicate file은 데이터베이스 시스템이 파일 시스템 수준에서 이미 존재하는 파일을 다시 생성하려 할 때 발생하는 에러입니다. 이 에러는 주로 데이터베이스 오브젝트(테이블, 인덱스, 시퀀스 등)에 해당하는 물리적 파일이 이미 디스크에 존재하는 상황에서 PostgreSQL이 새로운 릴레이션 파일을 생성하려 시도할 때 나타납니다. 일반적으로 비정상적인 서버 종료, 불완전한 복구 작업, 또는 수동으로 파일을 잘못 조작한 경우에 발생하며, 데이터 무결성과 시스템 안정성에 심각한 영향을 미칠 수 있습니다.

주요 발생 원인

비정상적인 서버 종료 후 불완전한 복구

PostgreSQL 서버가 강제 종료(kill -9, 전원 차단 등)된 이후 재시작 과정에서 WAL(Write-Ahead Log) 복구가 불완전하게 이루어지면 이 에러가 발생할 수 있습니다. 복구 과정에서 특정 릴레이션 파일이 이미 생성된 상태임에도 불구하고 WAL 레코드가 해당 파일을 다시 생성하도록 지시하면 충돌이 발생합니다. 이는 특히 pg_filenode.map이나 pg_internal.init 파일이 손상되었을 때 함께 발생하는 경우가 많습니다.

잘못된 백업 복원 및 파일시스템 조작

pg_basebackup, rsync, 또는 스냅샷 기반 백업을 복원하는 과정에서 일부 파일이 중복으로 복사되거나 올드 데이터 디렉터리의 파일이 잔류하는 경우 이 에러가 트리거됩니다. 특히 PGDATA 디렉터리를 수동으로 복사하거나 이동할 때 숨김 파일이나 임시 파일이 남아 PostgreSQL 내부의 파일 매핑과 충돌하는 상황이 생길 수 있습니다. 복원 후 반드시 pg_wal 디렉터리의 상태와 파일 권한을 점검해야 합니다.

OID 또는 Filenode 충돌

PostgreSQL은 각 릴레이션(테이블, 인덱스 등)에 고유한 OID와 filenode를 부여하여 물리적 파일과 매핑합니다. pg_class 시스템 카탈로그와 실제 파일 시스템 간의 불일치가 발생하면, 새로운 오브젝트를 생성할 때 이미 존재하는 파일 번호를 할당받아 58P02 에러가 발생합니다. 이는 데이터베이스 카탈로그를 직접 수정하거나 복제(Replication) 과정에서 OID 시퀀스가 어긋날 때 주로 나타납니다.

해결 방법

원인 1: 비정상 종료 후 복구 문제 해결

먼저 충돌 파일을 식별하고 PostgreSQL 로그를 확인합니다.

-- 현재 데이터베이스의 릴레이션 파일 매핑 확인
SELECT relname, relfilenode, reltablespace, relkind
FROM pg_class
WHERE relfilenode != 0
ORDER BY relfilenode;

-- 특정 테이블의 물리적 파일 경로 확인
SELECT pg_relation_filepath('your_table_name');

서버 로그에서 에러 발생 직전 메시지를 확인한 뒤, 중복 파일이 확인되면 pg_resetwal 명령 사용을 고려합니다. 단, 이 명령은 데이터 손실 위험이 있으므로 반드시 전체 백업 후 진행하세요.

# 운영체제 레벨에서 중복 파일 확인 (PGDATA 경로 기준)
ls -la $PGDATA/base/<database_oid>/

# WAL 리셋 (최후 수단, 반드시 백업 후 실행)
pg_resetwal -f $PGDATA

원인 2: 잘못된 백업 복원 후 정리

-- 고아(orphan) 파일 감지를 위한 카탈로그 조회
SELECT oid, datname FROM pg_database;

-- 특정 DB의 모든 릴레이션 파일노드 목록 추출
SELECT c.relname, c.relfilenode, c.relkind,
       pg_relation_filepath(c.oid) AS filepath
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relfilenode > 0
  AND n.nspname NOT IN ('pg_toast')
ORDER BY c.relfilenode;

복원 후 잔류 파일이 의심될 때는 파일시스템에서 직접 확인하고, 카탈로그에 매핑되지 않은 파일은 안전한 위치로 이동 후 서버를 재시작합니다.

# 카탈로그 매핑 없는 잔여 파일 확인 스크립트 예시
psql -c "SELECT relfilenode FROM pg_class WHERE relfilenode > 0" -t -A dbname > /tmp/mapped_filenodes.txt
ls $PGDATA/base/<db_oid>/ | grep -v -f /tmp/mapped_filenodes.txt

원인 3: OID/Filenode 충돌 해결

-- pg_class에서 filenode 중복 여부 확인
SELECT relfilenode, COUNT(*) as cnt, array_agg(relname) as tables
FROM pg_class
WHERE relfilenode > 0
GROUP BY relfilenode
HAVING COUNT(*) > 1;

-- 문제가 되는 테이블 재생성 (데이터 백업 후)
-- 1단계: 데이터 백업
CREATE TABLE your_table_backup AS SELECT * FROM your_table;

-- 2단계: 기존 테이블 삭제
DROP TABLE your_table;

-- 3단계: 새로운 filenode로 테이블 재생성
CREATE TABLE your_table (
    id SERIAL PRIMARY KEY,
    -- 기존 컬럼 정의
    col1 TEXT,
    col2 INTEGER
);

-- 4단계: 데이터 복원
INSERT INTO your_table SELECT * FROM your_table_backup;

-- 5단계: 백업 테이블 삭제
DROP TABLE your_table_backup;

-- VACUUM FULL로 새로운 파일노드 강제 할당
VACUUM FULL your_table;

-- 또는 CLUSTER 명령 활용
CLUSTER your_table USING your_index;

예방 방법

정기적인 파일시스템 정합성 검사 및 모니터링 자동화

PostgreSQL 데이터 디렉터리와 시스템 카탈로그 간의 파일 정합성을 주기적으로 점검하는 스크립트를 cron 또는 pg_agent로 자동화하세요. pg_relation_filepath() 함수를 활용하여 모든 릴레이션의 실제 파일 존재 여부를 확인하고, 불일치 발생 시 즉시 알림을 보내는 체계를 구축하면 문제가 커지기 전에 조기 발견이 가능합니다. 또한 pg_basebackup을 사용한 정기 백업과 함께 --checksum 옵션을 활성화하여 파일 무결성 검증을 습관화하세요.

안전한 백업·복원 절차 표준화 및 복원 테스트 정례화

백업 복원 작업은 반드시 문서화된 표준 절차(Runbook)를 따르고, 수동 파일 조작을 절대 금지하는 팀 내 규칙을 수립하세요. 특히 pg_basebackup 또는 pgBackRest, Barman 같은 검증된 백업 도구만을 사용하고, 복원 후에는 반드시 pg_dump를 이용한 논리적 검증과 SELECT COUNT(*) 수준의 기본 정합성 검사를 수행해야 합니다. 분기별 복원 테스트(Restore Drill)를 정례화하여 실제 장애 상황에서의 복구 절차를 팀 전체가 숙지하도록 유지하세요.