19강. PostgreSQL로 데이터베이스 확장

?1. 이번 강의에서 해결할 문제

SQLite는 학습과 단일 프로세스 개발에 편하지만 운영의 동시 연결, 계정, 서버 관리 요구를 대신하지 않습니다. PostgreSQL 환경으로 같은 앱을 실행합니다.

✓2. 학습 목표

✓이 강의를 마치면

• SQLite와 PostgreSQL의 운영 차이를 설명합니다.
• SQLAlchemy의 postgresql+psycopg:// URL을 구성합니다.
• 코드 수정 없이 환경 변수로 DB를 전환합니다.

◇3. 핵심 개념

SQLAlchemy dialect가 DB별 SQL과 DBAPI 차이를 연결합니다. Psycopg 3의 동기 연결 URL은 postgresql+psycopg://사용자:비밀번호@호스트:포트/DB입니다. 비밀번호에 특수문자가 있으면 URL 인코딩이 필요하며 실제 운영 연결은 TLS와 최소 권한 계정을 사용합니다.

</>4. 단계별 코드 예시

파일 경로: game-ranking-api/.env.postgresql.example

.env.postgresql.example

APP_ENV=production
DATABASE_URL=postgresql+psycopg://game_api:change-me@localhost:5432/game_ranking
JWT_SECRET=replace-with-at-least-32-random-bytes
ACCESS_TOKEN_EXPIRE_MINUTES=30
FRONTEND_ORIGINS=https://example.com

파일 경로: game-ranking-api/app/database.py

app/database.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from app.config import settings

connect_args = {"check_same_thread": False} if settings.database_url.startswith("sqlite") else {}
engine = create_engine(
    settings.database_url,
    connect_args=connect_args,
    pool_pre_ping=True,
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)

실행 위치: PostgreSQL의 psql이 설치된 터미널

psql -U postgres -c "CREATE USER game_api WITH PASSWORD 'change-me';"
psql -U postgres -c "CREATE DATABASE game_ranking OWNER game_api;"
$env:DATABASE_URL = 'postgresql+psycopg://game_api:change-me@localhost:5432/game_ranking'
$env:JWT_SECRET = 'development-only-change-me'
python -m uvicorn app.main:app --reload
Invoke-RestMethod http://127.0.0.1:8000/health

→5. 코드가 동작하는 이유

동일한 Engine 생성 코드가 URL scheme을 보고 PostgreSQL dialect와 Psycopg 3 DBAPI를 선택합니다. SQLite 전용 connect_args는 조건부로만 전달됩니다. pool_pre_ping은 풀에서 꺼낸 오래된 연결을 사용하기 전에 확인합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: postgresql://만 써서 의도하지 않은 드라이버가 선택됩니다. 해결: Psycopg 3를 명시하는 postgresql+psycopg://를 사용합니다.
• 실수: 최고 권한 postgres 계정으로 앱을 실행합니다. 해결: 앱 전용 최소 권한 사용자와 DB를 만듭니다.
• 실수: 운영 DB에서도 create_all로 변경합니다. 해결: 다음 강의부터 Alembic migration을 적용합니다.

✎7. 직접 실습

✎직접 실습

SQLite와 PostgreSQL에서 같은 기록 생성·조회 요청을 실행하세요. DB URL 외에 코드가 달라지지 않았는지 git diff로 확인하고 PostgreSQL의 \dt와 SELECT로 행을 조회합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. SQLAlchemy dialect와 DBAPI는 각각 무엇을 연결하나요?
2. Psycopg 3 동기 연결 URL의 scheme은 무엇인가요?
3. 앱 전용 DB 사용자가 필요한 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

DB URL을 환경 변수로 분리하면 같은 ORM 코드로 SQLite와 PostgreSQL을 전환할 수 있습니다. 운영에서는 전용 계정, TLS, migration을 함께 준비합니다.