Python psycopg2.errors 사용법: PostgreSQL 오류 코드보다 편한 예외 처리

Python과 PostgreSQL을 연결하고, 오류까지 똑똑하게 처리하는 방법을 배워봅니다.

1. PostgreSQL: 데이터 저장소

• 정의:
  PostgreSQL(포스트그레스큐엘, 줄여서 Postgres)은 **오픈소스 관계형 데이터베이스 관리 시스템(RDBMS)**입니다.

• 하는 일:
  데이터를 표(table) 형태로 저장하고, SQL이라는 언어를 사용해 데이터를 검색·추가·수정·삭제할 수 있게 해줍니다.

• 예시:

  ┌────────────┬──────────┐
  │ name       │ age      │
  ├────────────┼──────────┤
  │ Alice      │ 25       │
  │ Bob        │ 32       │
  └────────────┴──────────┘

  • "25살인 사람만 찾아줘" → SQL로 요청 → PostgreSQL이 결과를 반환

• 특징:

  • 무료이면서도 기업급 성능
  • 복잡한 쿼리, 대량 데이터 처리, 확장성 우수
  • 금융, 통계, GIS(지도 데이터) 등 다양한 분야에서 사용

---

2. psycopg2: PostgreSQL을 다루는 Python 도구 상자

• 정의:
  psycopg2는 Python 코드에서 PostgreSQL 데이터베이스에 접속하고, SQL을 실행하고, 결과를 가져올 수 있게 해주는 라이브러리입니다.

• 역할:

  1. 연결(Connection): 데이터베이스에 접속
  2. 명령 실행(Execute SQL): SELECT, INSERT, UPDATE, DELETE 실행
  3. 결과 가져오기(Fetch): 실행 결과를 Python에서 활용
  4. 에러 처리(Error Handling): 실행 중 발생한 문제 확인 및 대응

• 간단한 예시:

  import psycopg2
  
  # 1. 데이터베이스 연결
  conn = psycopg2.connect(
      host="localhost",
      dbname="mydb",
      user="myuser",
      password="mypassword"
  )
  
  cur = conn.cursor()
  
  # 2. SQL 실행
  cur.execute("SELECT * FROM users")
  
  # 3. 결과 가져오기
  rows = cur.fetchall()
  print(rows)
  
  conn.close()

---

3. psycopg2.errors: PostgreSQL 오류를 다루는 작은 상자

• 정의:
  psycopg2.errors는 psycopg2 안에 들어 있는 오류 처리 전용 모듈입니다.

• 하는 일:
  PostgreSQL이 보낸 오류 코드(SQLSTATE)를 이름이 있는 예외 클래스로 변환해 줍니다.

• 장점:

  • 가독성 ↑: 코드에서 오류 이름만 보고 무슨 문제인지 바로 알 수 있음
  • 유지보수 ↑: 오타나 잘못된 코드 비교를 줄임
  • 호환성 ↑: 기존 DB-API 방식(IntegrityError 등)과도 함께 사용 가능

---

4. psycopg2.errors의 주요 특징

(1) SQLSTATE와 pgcode

• PostgreSQL 오류는 SQLSTATE라는 5자리 문자열 코드로 구분됨

• psycopg2 예외 객체의 .pgcode 속성에 저장

  except psycopg2.OperationalError as e:
      print(e.pgcode)  # 예: '55P03'

(2) 자동 생성된 예외 클래스

• PostgreSQL v9.1 ~ v15까지의 모든 오류를 클래스 형태로 제공

• 예:

  • 코드: 22012 (division_by_zero) → 클래스: DivisionByZero
  • 코드: 55P03 (lock_not_available) → 클래스: LockNotAvailable

(3) DB-API 호환성

• 새 예외 클래스는 기존 DB-API 예외를 상속받아 호환됨

  except psycopg2.errors.UniqueViolation:  # 더 구체적
      ...
  except psycopg2.IntegrityError:  # 상위 클래스
      ...

(4) 예전 방식 vs 새로운 방식

예전 방식 (오류 코드 비교)

try:
    cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
except psycopg2.OperationalError as e:
    if e.pgcode == psycopg2.errorcodes.LOCK_NOT_AVAILABLE:
        locked = True

새로운 방식 (클래스 직접 사용)

try:
    cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
except psycopg2.errors.LockNotAvailable:
    locked = True

(5) lookup 기능

• 오류 코드를 예외 클래스로 변환해 주는 함수

  psycopg2.errors.lookup("55P03")
  # → <class 'psycopg2.errors.LockNotAvailable'>

• 응용 예:

  try:
      cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
  except psycopg2.errors.lookup("55P03"):
      locked = True

---

5. 전체 요약 그림

[ PostgreSQL ]
   │  (SQL 실행, 결과/오류 반환)
   ▼
[ psycopg2 ]
   ├─ 데이터베이스 연결
   ├─ SQL 실행
   ├─ 결과 조회
   └─ 오류 처리
        │
        ▼
[ psycopg2.errors ]
   ├─ PostgreSQL 오류 코드(SQLSTATE) → 예외 클래스 변환
   ├─ DB-API 호환
   ├─ 가독성 높은 예외 처리
   └─ lookup()으로 코드 기반 예외 검색

---

💡 정리:

• PostgreSQL → 데이터를 저장·조회하는 ‘창고’
• psycopg2 → Python에서 PostgreSQL과 대화하는 ‘통역사 + 작업 도구 세트’
• psycopg2.errors → 발생한 오류를 읽기 쉽게 알려주는 ‘오류 사전 + 알람 시스템’

---