PostgreSQL 3D000 오류 원인과 해결 방법 완벽 가이드

3D000 invalid catalog name 는?

PostgreSQL 에러 코드 3D000은 invalid catalog name, 즉 잘못된 카탈로그(데이터베이스) 이름을 지정했을 때 발생하는 에러입니다. PostgreSQL에서 “카탈로그”는 데이터베이스를 의미하며, 클라이언트가 존재하지 않거나 접근할 수 없는 데이터베이스에 연결을 시도할 때 이 에러가 발생합니다. 특히 애플리케이션 설정 오류, 마이그레이션 작업, 또는 데이터베이스 삭제 후 연결 시도 시 자주 접하게 되는 에러입니다.

---

주요 발생 원인

1. 존재하지 않는 데이터베이스에 연결 시도

가장 흔한 원인은 단순히 해당 이름의 데이터베이스가 PostgreSQL 클러스터에 존재하지 않는 경우입니다. 오타(typo), 대소문자 불일치, 또는 데이터베이스가 실수로 삭제된 경우에 발생하며, 특히 개발/스테이징/운영 환경 간 데이터베이스 이름이 다를 때 혼동이 생기기 쉽습니다. 연결 문자열에 mydb를 입력했지만 실제 데이터베이스 이름이 my_db나 MyDB인 경우가 대표적입니다.

2. 애플리케이션 설정 파일의 잘못된 데이터베이스 이름

Spring Boot, Django, Rails 등 프레임워크의 application.properties, settings.py, database.yml 등 설정 파일에 잘못된 데이터베이스 이름이 기재된 경우입니다. 환경 변수(DATABASE_URL, DB_NAME 등)가 올바르게 주입되지 않았거나, .env 파일이 누락된 경우에도 이 에러가 발생합니다. CI/CD 파이프라인이나 컨테이너 환경(Docker, Kubernetes)에서 환경 변수가 제대로 전달되지 않을 때 특히 빈번하게 나타납니다.

3. \c 또는 연결 명령어에서의 잘못된 데이터베이스 지정

psql CLI나 pgAdmin에서 \c 데이터베이스명 명령으로 데이터베이스를 전환하려 할 때, 해당 데이터베이스가 존재하지 않으면 이 에러가 발생합니다. 또한 pg_dump, pg_restore, psql -d 옵션 등 명령행 도구 사용 시 -d 플래그에 잘못된 데이터베이스 이름을 전달하는 경우에도 동일하게 발생합니다. 스크립트 자동화 환경에서 변수 치환이 실패했을 때 빈 문자열이나 잘못된 값이 전달되는 경우가 많습니다.

---

해결 방법

원인 1 해결: 데이터베이스 존재 여부 확인 및 생성

먼저 현재 PostgreSQL 클러스터에 어떤 데이터베이스가 있는지 확인합니다.

-- 현재 존재하는 모든 데이터베이스 목록 확인
SELECT datname FROM pg_database ORDER BY datname;

-- 또는 psql 메타 명령어 사용
-- \l 또는 \list

데이터베이스가 존재하지 않는다면 생성합니다.

-- 데이터베이스 생성 (superuser 또는 CREATEDB 권한 필요)
CREATE DATABASE mydb
    WITH
    OWNER = myuser
    ENCODING = 'UTF8'
    LC_COLLATE = 'ko_KR.UTF-8'
    LC_CTYPE = 'ko_KR.UTF-8'
    TEMPLATE = template0;

-- 생성 후 확인
SELECT datname, datcollate, datctype FROM pg_database WHERE datname = 'mydb';

대소문자 문제가 의심될 경우 아래처럼 정확히 조회합니다.

-- 대소문자 구분하여 정확한 이름 확인
SELECT datname FROM pg_database WHERE datname ILIKE '%mydb%';

원인 2 해결: 연결 문자열 및 환경 변수 점검

애플리케이션에서 사용하는 연결 문자열을 직접 psql로 테스트합니다.

-- psql 연결 테스트 (터미널에서 실행)
-- psql "postgresql://myuser:mypassword@localhost:5432/mydb"

-- 현재 연결된 데이터베이스 확인
SELECT current_database();

-- 현재 연결 정보 전체 확인
SELECT current_database(), current_user, inet_server_addr(), inet_server_port();

환경 변수로 관리되는 경우, 아래 쿼리로 연결 상태를 진단할 수 있습니다.

-- pg_stat_activity로 현재 연결 상태 및 데이터베이스 확인 (관리자 권한 필요)
SELECT pid, datname, usename, application_name, client_addr, state
FROM pg_stat_activity
WHERE datname IS NOT NULL
ORDER BY datname;

원인 3 해결: psql 및 CLI 도구에서 올바른 데이터베이스 지정

-- psql에서 데이터베이스 전환 전 목록 확인
\l

-- 올바른 데이터베이스로 전환
\c mydb

-- pg_dump 사용 시 올바른 데이터베이스 지정 (터미널)
-- pg_dump -h localhost -U myuser -d mydb -f backup.sql

-- 데이터베이스 이름을 변수로 관리하는 스크립트 예시
-- DB_NAME=$(psql -U postgres -t -c "SELECT datname FROM pg_database WHERE datname = 'mydb';")
-- if [ -z "$DB_NAME" ]; then echo "Database not found!"; exit 1; fi

---

예방 방법

1. 연결 전 데이터베이스 존재 여부를 자동으로 검증하는 헬스체크 스크립트 구축

애플리케이션 배포 전 또는 시작 시 데이터베이스가 존재하는지 확인하는 로직을 반드시 포함시킵니다. 아래와 같은 SQL을 활용하여 존재 여부를 사전에 검증하면 런타임 에러를 방지할 수 있습니다.

-- 데이터베이스 존재 여부 확인 (존재하면 1, 없으면 0 반환)
SELECT COUNT(*) AS db_exists
FROM pg_catalog.pg_database
WHERE datname = 'mydb';

-- DO 블록을 이용한 조건부 생성 (PostgreSQL 9.x 이하 호환)
DO $$
BEGIN
    IF NOT EXISTS (
        SELECT 1 FROM pg_catalog.pg_database WHERE datname = 'mydb'
    ) THEN
        RAISE EXCEPTION 'Database "mydb" does not exist. Please create it first.';
    END IF;
END
$$;

2. 환경별 설정 파일 및 연결 문자열 관리 표준화

개발(dev), 스테이징(staging), 운영(prod) 환경별로 데이터베이스 이름 네이밍 컨벤션을 명확히 정의하고 문서화합니다. DATABASE_URL 환경 변수의 값이 비어 있거나 기본값으로 폴백되지 않도록 유효성 검사를 코드 레벨에서 강제하고, Vault나 AWS Secrets Manager 같은 시크릿 관리 도구를 활용하여 연결 정보를 중앙에서 관리하는 것을 권장합니다.

---

관련 에러

• 28000 invalid_authorization_specification: 데이터베이스는 존재하지만 해당 사용자로 접근이 거부된 경우 발생합니다. 3D000과 함께 연결 실패 시 자주 혼동됩니다.
• 08006 connection_failure: 네트워크 레벨에서 PostgreSQL 서버 자체에 접근하지 못할 때 발생하며, 3D000은 서버 접근 후 데이터베이스 선택 단계에서 발생한다는 점에서 구분됩니다.
• 42P04 duplicate_database: CREATE DATABASE 시 이미 동일한 이름의 데이터베이스가 존재할 때 발생하며, 3D000의 해결 과정에서 데이터베이스를 새로 생성하려 할 때 만날 수 있습니다.
• 08001 sqlclient_unable_to_establish_sqlconnection: JDBC 드라이버 등 클라이언트 라이브러리 레벨에서 3D000을 래핑하여 표시할 때 함께 등장하는 에러입니다.

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.