PostgreSQL 0A000 오류 원인과 해결 방법 완벽 가이드

0A000 feature not supported 는?

PostgreSQL 에러 코드 0A000은 현재 사용하려는 기능이 PostgreSQL에서 지원되지 않거나, 특정 컨텍스트에서는 사용할 수 없음을 의미합니다. 주로 트랜잭션 내부에서 허용되지 않는 명령을 실행하거나, 해당 버전의 PostgreSQL에서 아직 구현되지 않은 SQL 표준 문법을 사용할 때, 또는 복제(Replication) 환경의 제약으로 인해 발생합니다. 실무에서는 특히 CREATE DATABASE, VACUUM, CLUSTER 같은 명령을 트랜잭션 블록 안에서 실행하거나, Logical Replication 슬롯과 관련된 작업을 수행할 때 자주 마주치는 에러입니다.

주요 발생 원인

1. 트랜잭션 블록 내에서 허용되지 않는 DDL 명령 실행

PostgreSQL은 일부 DDL 명령을 트랜잭션 블록(BEGIN ... COMMIT) 내에서 실행하는 것을 허용하지 않습니다. CREATE DATABASE, DROP DATABASE, CREATE TABLESPACE, DROP TABLESPACE, VACUUM, CLUSTER 등의 명령은 트랜잭션 컨텍스트 밖에서 단독으로 실행되어야 하며, 이를 무시하고 트랜잭션 내부에서 호출하면 0A000 에러가 발생합니다.

2. 특정 PostgreSQL 버전에서 지원하지 않는 문법 또는 기능 사용

SQL 표준에는 정의되어 있지만 PostgreSQL의 해당 버전에서 아직 구현되지 않은 기능을 사용할 때 이 에러가 발생합니다. 예를 들어, 구버전 PostgreSQL에서 LATERAL JOIN, MERGE 문, GENERATED ALWAYS AS (expression) STORED 컬럼 정의 등을 사용하거나, 특정 윈도우 함수 옵션 조합을 사용하는 경우 해당 에러를 만날 수 있습니다.

3. 논리 복제(Logical Replication) 또는 스트리밍 복제 환경에서의 제약 위반

Standby 서버나 Logical Replication 구독자(Subscriber) 측에서 쓰기 작업이나 특정 관리 명령을 실행하려 할 때 0A000 에러가 발생합니다. Hot Standby 상태의 서버에서 DDL을 실행하거나, Logical Replication 슬롯이 활성화된 상태에서 지원되지 않는 방식으로 복제 슬롯을 조작하려는 경우 이 에러를 마주치게 됩니다.

해결 방법

원인 1: 트랜잭션 블록 내 허용되지 않는 DDL 실행

트랜잭션 블록을 제거하고 해당 명령을 단독으로 실행하는 것이 핵심입니다. 아래는 잘못된 예제와 올바른 예제를 비교한 것입니다.

❌ 잘못된 예 (0A000 에러 발생)

BEGIN;

CREATE DATABASE myapp_db
    WITH OWNER = myapp_user
    ENCODING = 'UTF8'
    LC_COLLATE = 'ko_KR.UTF-8'
    LC_CTYPE = 'ko_KR.UTF-8';

COMMIT;
-- ERROR:  0A000: CREATE DATABASE cannot run inside a transaction block

✅ 올바른 예 (트랜잭션 블록 밖에서 실행)

-- 트랜잭션 블록 없이 단독 실행
CREATE DATABASE myapp_db
    WITH OWNER = myapp_user
    ENCODING = 'UTF8'
    LC_COLLATE = 'ko_KR.UTF-8'
    LC_CTYPE = 'ko_KR.UTF-8';

VACUUM 명령도 동일한 원칙이 적용됩니다.

-- ❌ 잘못된 예
BEGIN;
VACUUM ANALYZE public.orders;
COMMIT;

-- ✅ 올바른 예: 트랜잭션 밖에서 단독 실행
VACUUM ANALYZE public.orders;

-- ✅ 특정 테이블만 선택적으로 VACUUM
VACUUM (VERBOSE, ANALYZE) public.orders;

애플리케이션 코드(예: Python psycopg2)에서 자동 커밋을 끈 상태로 VACUUM을 호출하는 경우도 흔한 실수입니다.

import psycopg2

conn = psycopg2.connect(dsn="...")

# ❌ 잘못된 예: autocommit=False (기본값) 상태에서 VACUUM 호출
# cur.execute("VACUUM ANALYZE orders;")  # 0A000 에러 발생

# ✅ 올바른 예: autocommit=True 설정 후 실행
conn.autocommit = True
cur = conn.cursor()
cur.execute("VACUUM ANALYZE public.orders;")
cur.close()
conn.close()

원인 2: 지원하지 않는 문법 또는 기능 사용

먼저 현재 PostgreSQL 버전을 확인하고, 해당 기능이 지원되는 버전인지 검토해야 합니다.

-- 현재 PostgreSQL 버전 확인
SELECT version();
SHOW server_version;

-- 예: MERGE 문은 PostgreSQL 15부터 지원
-- PostgreSQL 14 이하에서 아래 구문 실행 시 0A000 에러 발생 가능
MERGE INTO target_table AS t
USING source_table AS s
ON t.id = s.id
WHEN MATCHED THEN
    UPDATE SET t.value = s.value
WHEN NOT MATCHED THEN
    INSERT (id, value) VALUES (s.id, s.value);

-- PostgreSQL 14 이하에서는 INSERT ... ON CONFLICT 로 대체
INSERT INTO target_table (id, value)
SELECT id, value FROM source_table
ON CONFLICT (id)
DO UPDATE SET value = EXCLUDED.value;

Generated Column 관련 에러인 경우 버전 확인 후 대안을 사용합니다.

-- PostgreSQL 12 미만에서는 GENERATED ALWAYS AS 미지원
-- ❌ 에러 발생 (12 미만 버전)
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    price NUMERIC(10,2),
    tax_rate NUMERIC(5,4) DEFAULT 0.1,
    total_price NUMERIC(10,2) GENERATED ALWAYS AS (price * (1 + tax_rate)) STORED
);

-- ✅ 대안: 트리거를 활용한 자동 계산 컬럼 구현
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    price NUMERIC(10,2),
    tax_rate NUMERIC(5,4) DEFAULT 0.1,
    total_price NUMERIC(10,2)
);

CREATE OR REPLACE FUNCTION fn_calc_total_price()
RETURNS TRIGGER AS $$
BEGIN
    NEW.total_price := NEW.price * (1 + NEW.tax_rate);
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_products_total_price
BEFORE INSERT OR UPDATE ON products
FOR EACH ROW EXECUTE FUNCTION fn_calc_total_price();

원인 3: 복제 환경에서의 제약 위반

Standby 서버에서 현재 역할을 먼저 확인하고, Primary에서만 가능한 작업인지 검토해야 합니다.

-- 현재 서버가 Primary인지 Standby인지 확인
SELECT pg_is_in_recovery();
-- true이면 Standby(읽기 전용), false이면 Primary

-- Replication 슬롯 현황 확인
SELECT slot_name, slot_type, active, restart_lsn
FROM pg_replication_slots;

-- ❌ Standby에서 Replication Slot 생성 시 0A000 에러
-- SELECT pg_create_logical_replication_slot('my_slot', 'pgoutput');

-- ✅ Primary 서버에서만 Replication Slot 생성
-- Primary에 접속 후 실행
SELECT pg_create_logical_replication_slot('my_slot', 'pgoutput');

-- 논리 복제 Publication 생성 (Primary에서만 가능)
CREATE PUBLICATION my_publication
FOR TABLE public.orders, public.customers;

-- Subscription 상태 확인
SELECT subname, subenabled, subslotname
FROM pg_subscription;

-- 문제가 있는 Subscription 재초기화
ALTER SUBSCRIPTION my_subscription REFRESH PUBLICATION;

Hot Standby에서 허용되는 작업과 허용되지 않는 작업을 구분하는 쿼리도 확인해 두는 것이 좋습니다.

-- Standby에서 허용: SELECT 조회
SELECT COUNT(*) FROM public.orders WHERE created_at >= NOW() - INTERVAL '1 day';

-- Standby에서 허용: 복제 지연 확인
SELECT
    now() - pg_last_xact_replay_timestamp() AS replication_delay,
    pg_is_in_recovery() AS is_standby,
    pg_last_wal_receive_lsn() AS received_lsn,
    pg_last_wal_replay_lsn() AS replayed_lsn;

-- ❌ Standby에서 허용 안 됨 (0A000 에러)
-- CREATE TABLE, INSERT, UPDATE, DELETE 등 모든 쓰기 작업

예방 방법

1. 배포 스크립트에서 DDL 명령과 트랜잭션 블록을 명확히 분리하라

마이그레이션 툴(Flyway, Liquibase, Alembic 등)을 사용하는 실무 환경에서는 CREATE DATABASE, VACUUM, CREATE TABLESPACE 같은 트랜잭션 비호환 명령을 별도의 마이그레이션 파일로 분리하고, 해당 파일에는 -- transactionMode=none 또는 transactional: false 옵션을 명시하는 것이 좋습니다. 또한 CI/CD 파이프라인에서 개발/스테이징 환경에 먼저 배포해 에러를 사전에 검출하는 프로세스를 갖추어야 합니다.

-- Flyway에서 트랜잭션 비호환 마이그레이션 파일 예시
-- 파일명: V1__create_database.sql
-- 주석으로 트랜잭션 비활성화 지시

-- flyway:transactional=false
CREATE DATABASE analytics_db
    WITH OWNER = analytics_user
    ENCODING = 'UTF8';

2. 신규 기능 도입 전 반드시 버전 호환성 매트릭스를 문서화하라

팀 내에서 사용 중인 PostgreSQL 최소 지원 버전을 명시하고, 해당 버전에서 지원하지 않는 기능 목록을 위키나 README에 관리하세요. 코드 리뷰 시 새로운 SQL 문법이 포함된 경우 반드시 PostgreSQL 공식 문서의 버전별 Release Notes를 참조하여 호환성을 검토하는 절차를 팀 컨벤션으로 정착시켜야 합니다. 특히 ORM(SQLAlchemy, Hibernate 등)이 생성하는 SQL도 직접 로깅하여 주기적으로 점검하는 것을 권장합니다.

推荐订阅源

DEV Community