PostgreSQL 연결 시 encoding 문제

✒️ 2026-03-01 13:19 내용 수정

📋 문제 개요

문제 설명
FastAPI와 psycopg2로 PostgreSQL 연결 시 인코딩 문제로 인해 DB 연결이 생성되지 않음.

🔍 상세 정보

발생 환경

• 환경: 개발
• 서버/인스턴스: 데이터베이스(PostgreSQL 16.11v)
• 브라우저/디바이스:
• 관련 버전: psycopg2-binary==2.9.11

재현 방법

1. FastAPI 0.128.0v에서 psycopg2-binary로 PostgreSQL 연결을 진행
2. 연결 설정

# DB 연결 관리
import psycopg2

# PostgreSQL 데이터베이스 연결 생성
def get_db_connection():
    return psycopg2.connect("dbname=testdb user=postgres password=secret client_encoding=UTF8")

에러 메시지 및 로그

  File "C:\\Users\\...\\fastapi-env\\Lib\\site-packages\\psycopg2\\__init__.py", line 135, in connect
    conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xb8 in position 63: invalid start byte

🔎 원인 분석

조사 과정

• ChatGPT로 에러 원인 분석과 제안 받은 해결 방안 진행
  • .env 에서 가져오는 환경 변수 값들의 특수 문자 포함 여부
  • .env 파일에서 불러오는 환경 변수 값들의 인코딩 여부
  • PostgreSQL의 서버와 클라이언트 인코딩이 UTF8인지 확인

근본 원인

PostgreSQL의 인코딩 문제

✅ 해결 방법

적용한 솔루션

1. UTF8 인코딩을 적용한 테스트 데이터베이스 생성하기

CREATE DATABASE testdb 
with encoding='UTF8' 
LC_COLLATE='ko_KR.UTF-8' 
LC_CTYPE='ko_KR.UTF-8' 
TEMPLATE=template0;

2. FastAPI에서 데이터베이스 연결하기
3. 설치된 데이터베이스 전체의 인코딩이 문제라면 재설치 진행
   1. Locale을 ko_KR 로 설정

🛡️ 재발 방지

예방 조치

• 데이터베이스 설치 시 Locale을 ko_KR 로 설정 (운영체제가 한글 기반일 경우)