PostgreSQL 오류 "relation does not exist" 해결법 총정리 (Position 에러 포함)

PostgreSQL에서 자주 마주치는 "relation does not exist" 오류는 대부분 테이블 이름과 관련된 문제입니다. 이 글에서는 해당 오류의 원인과 해결법을 초보자도 쉽게 이해할 수 있도록 정리했습니다.

---

목차 (Table of Contents)

1. PostgreSQL relation does not exist 오류란?
2. 오류 메시지에서 Position 숫자의 의미
3. 자주 발생하는 원인과 해결 방법
4. 대문자 테이블명과 쿼리 오류 사례
5. JDBC, Java 사용 시 주의사항
6. 디버깅을 쉽게 하는 팁
7. 결론 및 정리

---

1. PostgreSQL relation does not exist 오류란?

PostgreSQL에서 다음과 같은 에러 메시지를 본 적 있으신가요?

org.postgresql.util.PSQLException: ERROR: relation "테이블명" does not exist
Position: 189

이 에러는 데이터베이스가 특정 테이블(또는 뷰, 시퀀스 등)을 찾을 수 없을 때 발생합니다. 간단히 말해, 쿼리 안에 쓴 테이블명이 PostgreSQL에 존재하지 않는다는 뜻이에요.

---

2. 오류 메시지의 Position 숫자는 무엇인가요?

에러 메시지에 나오는 Position: 189는 테이블명이 잘못된 문자 위치를 의미합니다.
중요한 점은 이 숫자가 눈에 보이는 줄(Line) 번호가 아니라, SQL 전체 문자열에서 몇 번째 글자인지를 나타낸다는 것이에요.

예를 들어 줄이 20줄밖에 안 돼도, 줄바꿈(\n)과 공백까지 포함하면 쉽게 189번째 위치가 될 수 있습니다.

TIP: 긴 쿼리는 줄이 짧아 보여도 실제 문자열 길이는 길 수 있으니 substr() 함수를 이용해 확인할 수 있습니다.

---

3. 자주 발생하는 원인과 해결 방법

3.1 테이블명 오타

가장 흔한 이유입니다. 테이블 이름에 철자가 틀린 경우 해당 테이블을 찾을 수 없습니다.
해결: \dt 명령어나 pg_tables 뷰로 테이블 이름을 정확히 확인하세요.

---

3.2 대소문자 문제

PostgreSQL은 기본적으로 소문자로 테이블명을 인식합니다.
예를 들어 다음과 같이 테이블을 만들었다면:

CREATE TABLE "Users" (
  id SERIAL,
  name TEXT
);

이후 SELECT * FROM Users;를 하면 오류가 납니다. 왜냐하면 PostgreSQL은 이 쿼리를 users로 인식하기 때문입니다.

해결:

• 쿼리에서도 "Users"처럼 큰따옴표로 감싸 사용
• 혹은 아예 테이블 생성 시에도 소문자만 사용

---

3.3 스키마 누락

테이블이 public 외의 다른 스키마에 있는 경우, PostgreSQL은 찾지 못할 수 있습니다.
해결: 테이블을 사용할 때 스키마명을 명시하세요.

SELECT * FROM my_schema.users;

또는:

SET search_path TO my_schema;

---

3.4 테이블 미생성

간혹 테이블을 생성하지 않고 조회하려 할 때도 발생합니다.
해결: pg_tables에서 테이블 존재 여부를 확인하세요.

SELECT * FROM pg_tables WHERE tablename = 'users';

---

4. 대문자 테이블명과 쿼리 오류 사례

-- 테이블 생성
CREATE TABLE "Employees" (
  id SERIAL,
  name TEXT
);

-- 조회 (오류 발생)
SELECT * FROM Employees;

-- 해결 방법
SELECT * FROM "Employees";

대문자로 생성한 테이블은 항상 "큰따옴표"로 감싸야 정상 작동합니다.

---

5. JDBC, Java 사용 시 주의사항

Java의 JDBC나 ORM 도구(JPA 등)는 대부분 쿼리 내에서 테이블명을 자동으로 소문자 처리합니다.
그래서 "Users"처럼 대문자 테이블명은 찾지 못하게 되는 거죠.

해결책:

• 테이블 생성 시 소문자만 사용
• 또는 쿼리 내에서 큰따옴표로 정확하게 감싸주기

---

6. 디버깅을 쉽게 하는 팁

쿼리의 오류 위치 보기

WITH q AS (
  SELECT
    'SELECT * FROM users u JOIN orders o ON u.id = o.user_id;'::text AS query
)
SELECT substr(query, 180, 20) FROM q;

위와 같이 하면 Position: 189 근처의 문자열을 쉽게 확인할 수 있습니다.

---

7. 결론 및 정리

PostgreSQL에서 "relation does not exist" 오류는 단순한 실수에서 시작됩니다.
테이블명을 정확히 확인하고, 대소문자 구분과 스키마 명시를 잘 해주면 대부분의 오류는 쉽게 해결됩니다.

정리하자면:

• PostgreSQL은 테이블명을 기본적으로 소문자로 처리
• 대문자 테이블을 쓰려면 "큰따옴표" 필수
• Position: 숫자는 전체 문자열 기준 위치
• pg_tables, \dt 등으로 테이블 존재 여부 확인