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

42702 ambiguous column 란?

PostgreSQL 에러 코드 42702는 ambiguous column, 즉 열 이름이 모호하다는 의미입니다. 이 에러는 주로 두 개 이상의 테이블을 JOIN하거나 서브쿼리를 사용할 때, 동일한 이름의 컬럼이 여러 테이블에 존재하여 PostgreSQL이 어떤 테이블의 컬럼을 참조해야 할지 판단하지 못할 경우 발생합니다. 실무에서는 대규모 데이터베이스 마이그레이션, 복잡한 리포팅 쿼리, 또는 ORM이 자동 생성한 쿼리에서도 빈번하게 만날 수 있는 에러입니다.

---

주요 발생 원인

1. JOIN 시 동일한 컬럼 이름 사용

가장 흔한 원인입니다. 두 개 이상의 테이블을 JOIN할 때 양쪽 테이블 모두 id, name, created_at과 같은 공통 컬럼을 가지고 있는 경우, SELECT 절이나 WHERE 절에서 테이블 지정 없이 해당 컬럼을 참조하면 PostgreSQL은 어떤 테이블의 컬럼인지 확신할 수 없습니다. 특히 id 컬럼은 거의 모든 테이블에 존재하기 때문에 JOIN 쿼리에서 반드시 주의가 필요합니다.

2. 서브쿼리 또는 CTE에서 컬럼 명 충돌

서브쿼리나 CTE(Common Table Expression)를 사용할 때, 내부 쿼리와 외부 쿼리 혹은 여러 CTE 블록 간에 동일한 컬럼 이름이 노출되면 모호성 에러가 발생합니다. 특히 WITH 절을 여러 단계로 중첩하거나, 서브쿼리 결과를 외부에서 참조할 때 별칭(alias)을 부여하지 않으면 이 문제가 자주 나타납니다.

3. USING 절 또는 NATURAL JOIN 사용 후 컬럼 참조

USING 절이나 NATURAL JOIN을 사용하면 조인 컬럼이 자동으로 병합되어 하나처럼 보이지만, 이후 WHERE 절이나 SELECT 절에서 해당 컬럼을 다른 테이블 컬럼과 함께 사용할 때 여전히 모호성 문제가 생길 수 있습니다. 또한 USING 절로 조인한 컬럼에 테이블 접두사를 붙이면 오히려 에러가 발생하는 등 예상치 못한 동작이 나타날 수 있어 주의가 필요합니다.

---

해결 방법

원인 1 해결: 테이블 별칭(Alias)으로 컬럼 한정

JOIN 쿼리에서 컬럼 앞에 반드시 테이블명 또는 테이블 별칭을 붙여 명시적으로 참조하세요.

문제가 되는 쿼리:

-- 에러 발생: column reference "id" is ambiguous
SELECT id, name, email
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE created_at > '2024-01-01';

수정된 쿼리:

-- 테이블 별칭을 사용하여 모호성 제거
SELECT o.id        AS order_id,
       c.id        AS customer_id,
       c.name      AS customer_name,
       c.email     AS customer_email,
       o.created_at AS order_date
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE o.created_at > '2024-01-01';

---

원인 2 해결: CTE 및 서브쿼리에서 명시적 별칭 사용

CTE나 서브쿼리를 작성할 때는 반드시 각 컬럼에 명확한 별칭을 부여하고, 외부에서 참조할 때도 CTE명을 접두사로 사용하세요.

문제가 되는 쿼리:

-- 에러 발생: column "name" is ambiguous
WITH recent_orders AS (
    SELECT o.id, o.created_at, c.name
    FROM orders o
    JOIN customers c ON o.customer_id = c.id
)
SELECT id, name
FROM recent_orders
JOIN products p ON recent_orders.id = p.order_id;

수정된 쿼리:

-- 각 컬럼에 명시적 별칭 부여
WITH recent_orders AS (
    SELECT o.id          AS order_id,
           o.created_at  AS order_date,
           c.name        AS customer_name
    FROM orders o
    JOIN customers c ON o.customer_id = c.id
)
SELECT ro.order_id,
       ro.customer_name,
       p.name AS product_name
FROM recent_orders ro
JOIN products p ON ro.order_id = p.order_id;

---

원인 3 해결: USING 절 사용 시 주의사항

USING 절로 조인한 컬럼은 테이블 접두사 없이 사용하고, 나머지 동명 컬럼에는 반드시 테이블 별칭을 붙이세요.

문제가 되는 쿼리:

-- USING 절 사용 후 모호한 컬럼 참조
SELECT id, name, status
FROM orders
JOIN customers USING (customer_id)
WHERE status = 'active';  -- status가 어느 테이블인지 불분명

수정된 쿼리:

-- USING 조인 컬럼(customer_id)은 접두사 없이, 나머지는 명시
SELECT orders.id    AS order_id,
       customer_id,           -- USING 절 컬럼은 접두사 없이 사용
       customers.name,
       orders.status          AS order_status,
       customers.status       AS customer_status
FROM orders
JOIN customers USING (customer_id);

---

추가: 컬럼 목록 확인 쿼리

어떤 테이블에 동명 컬럼이 있는지 사전에 확인하는 방법입니다.

-- 특정 스키마 내 동일한 컬럼명을 가진 테이블 목록 조회
SELECT column_name,
       COUNT(table_name) AS table_count,
       STRING_AGG(table_name, ', ' ORDER BY table_name) AS tables
FROM information_schema.columns
WHERE table_schema = 'public'
GROUP BY column_name
HAVING COUNT(table_name) > 1
ORDER BY table_count DESC, column_name;

이 쿼리를 통해 어떤 컬럼 이름이 여러 테이블에 걸쳐 중복되는지 미리 파악하고 쿼리 작성 시 주의할 수 있습니다.

---

예방 방법

1. 모든 멀티 테이블 쿼리에서 완전한 컬럼 한정(Fully Qualified Column Reference) 사용

쿼리를 작성할 때부터 테이블이 하나뿐인 단순 SELECT를 제외하고, JOIN이나 서브쿼리가 포함된 모든 쿼리에서는 테이블별칭.컬럼명 형식을 의무화하는 코딩 컨벤션을 팀 내에서 확립하세요. 특히 id, name, status, created_at, updated_at과 같이 범용적으로 쓰이는 컬럼은 항상 테이블 별칭을 붙이는 습관을 들이면 42702 에러를 원천적으로 예방할 수 있습니다. 코드 리뷰 단계에서 이 규칙의 준수 여부를 체크리스트로 관리하는 것도 효과적입니다.

2. 뷰(View)와 함수에서 명시적 컬럼 별칭 정의

반복 사용되는 복잡한 JOIN 쿼리는 뷰(View)로 정의하고, 뷰 생성 시 모든 컬럼에 고유한 별칭을 반드시 부여하세요. 이렇게 하면 뷰를 사용하는 후속 쿼리에서 컬럼 이름 충돌이 원천 차단됩니다. 또한 pgTAP 등의 테스트 프레임워크를 활용하여 뷰와 함수의 출력 컬럼 명세를 자동화 테스트로 검증하면 배포 전에 문제를 조기에 발견할 수 있습니다.

---

관련 에러

• 42703 undefined_column: 존재하지 않는 컬럼을 참조할 때 발생하는 에러로, 42702와 함께 컬럼 참조 관련 에러로 자주 짝으로 등장합니다. 오타나 스키마 변경 후 쿼리를 수정하지 않았을 때 주로 발생합니다.
• 42P01 undefined_table: 존재하지 않는 테이블이나 뷰를 참조할 때 발생합니다. JOIN 대상 테이블을 잘못 지정하거나 별칭을 혼동했을 때 42702와 함께 나타나는 경우가 있습니다.
• 42601 syntax_error: 쿼리 문법 자체가 잘못된 경우로, 별칭 지정 실수로 인해 42702를 수정하다가 문법 오류를 유발하는 사례가 종종 있어 함께 알아두면 유용합니다.

---

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