SEO 키워드: PostgreSQL, psycopg, Pydantic

---

# 📌 서론 – n+1 문제가 왜 문제인가?

웹·API 서버에서 관계형 데이터베이스를 사용할 때 가장 흔히 마주치는 성능 병목 중 하나가 n+1 문제입니다.

예를 들어, 게시글 10개를 조회하고 각각의 작성자를 다시 조회한다면 총 11개의 SQL이 실행됩니다.

데이터 양이 늘어나면 쿼리 수는 기하급수적으로 증가해 응답 시간이 급격히 늘어나고 서버 부하도 크게 올라갑니다.

이 글에서는 PostgreSQL, psycopg, Pydantic이라는 내가 즐겨 쓰는 세 가지 도구를 이용해

한 번의 쿼리만으로 중첩된 객체를 효율적으로 가져오는 방법을 단계별로 설명합니다.

코드 예제와 레포지토리 링크를 통해 바로 실습해볼 수 있으니, 초보자도 안심하고 따라오세요!

---

# 🛠️ 본문

# 1️⃣ 프로젝트 환경 설정

bash

# 가상환경 생성·활성화

python -m venv venv

source venv/bin/activate

# 필수 패키지 설치

pip install psycopg2-binary pydantic

위 명령어만으로 psycopg와 Pydantic을 사용할 준비가 끝납니다.

# 2️⃣ 데이터베이스 스키마 예시

sql

CREATE TABLE authors (

    id   SERIAL PRIMARY KEY,

    name TEXT NOT NULL

);

CREATE TABLE posts (

    id        SERIAL PRIMARY KEY,

    title     TEXT NOT NULL,

    content   TEXT,

    author_id INT REFERENCES authors(id)

);

posts와 authors는 1:N 관계이며, 게시글과 작성자 정보를 동시에 가져와야 하는 상황을 가정합니다.

# 3️⃣ Pydantic 모델 정의 – 타입 검증과 직렬화

python

from pydantic import BaseModel

from typing import Optional

class Author(BaseModel):

    id: int

    name: str

class Post(BaseModel):

    id: int

    title: str

    content: Optional[str]

    author: Author          # 중첩된 객체

Pydantic은 데이터 검증과 JSON 직렬화를 자동으로 처리해 주어, API 응답을 만들 때 매우 편리합니다.

# 4️⃣ 한 번에 데이터를 가져오는 SQL – JOIN + JSON_AGG 활용

n+1 문제를 방지하려면 JOIN과 PostgreSQL의 JSON 함수를 조합해 한 번의 쿼리로

게시글과 작성자 정보를 모두 받아와야 합니다.

sql

SELECT

    p.id,

    p.title,

    p.content,

    jsonb_build_object('id', a.id, 'name', a.name) AS author

FROM posts p

JOIN authors a ON a.id = p.author_id;

• jsonb_build_object는 각 행에 author 라는 JSON 객체를 포함시켜 반환합니다.

• 이렇게 하면 네트워크 라운드 트립이 1회만 발생합니다.

# 5️⃣ psycopg로 쿼리 실행하고 Pydantic에 매핑하기

python

import psycopg2

import json

from pydantic import parse_obj_as

from typing import List

# DB 연결

conn = psycopg2.connect(

    dbname='mydb',

    user='myuser',

    password='secret',

    host='localhost'

)

with conn.cursor() as cur:

    cur.execute('''

        SELECT

            p.id,

            p.title,

            p.content,

            jsonb_build_object('id', a.id, 'name', a.name) AS author

        FROM posts p

        JOIN authors a ON a.id = p.author_id;

    ''')

    rows = cur.fetchall()

# psycopg는 JSON을 문자열로 반환하므로 파이썬 dict 로 변환

posts_data = [

    {

        'id': row[0],

        'title': row[1],

        'content': row[2],

        'author': json.loads(row[3])

    }

    for row in rows

]

# Pydantic 모델에 바로 매핑

posts: List[Post] = parse_obj_as(List[Post], posts_data)

# 결과 출력 (JSON 형태)

for post in posts:

    print(post.json())

• 한 번의 네트워크 호출만으로 모든 데이터를 받아옵니다.

• json.loads 로 JSON 문자열을 딕셔너리로 변환하고, parse_obj_as 로 타입 안전하게 Post 객체 리스트를 생성합니다.

# 6️⃣ 대용량 데이터와 페이징 처리

한 번에 수천 건을 가져오면 메모리 사용량이 급증할 수 있습니다. 이를 방지하려면 OFFSET/LIMIT 혹은 키셋 페이징을 적용합니다.

sql

SELECT

    p.id,

    p.title,

    p.content,

    jsonb_build_object('id', a.id, 'name', a.name) AS author

FROM posts p

JOIN authors a ON a.id = p.author_id

ORDER BY p.id

LIMIT 20 OFFSET %s;

또는 WHERE p.id > %s 로 마지막 조회 ID를 기준으로 키셋 페이징을 구현하면 인덱스 활용도가 높아져 성능이 더욱 향상됩니다.

# 7️⃣ 트랜잭션과 오류 처리 – 안전하게 마무리하기

python

try:

    with conn:                     # 자동 커밋/롤백

        with conn.cursor() as cur:

            cur.execute(sql, (offset,))

            # 위와 동일한 변환 로직

except psycopg2.Error as e:

    print('Database error:', e)

finally:

    conn.close()

with conn: 블록을 사용하면 예외 발생 시 자동 롤백이 이루어져 데이터 무결성을 보장할 수 있습니다.

---

# 🎯 결론 – 지금 바로 적용해 보세요!

• n+1 문제는 단순히 쿼리 수를 줄이는 것이 아니라 네트워크 비용과 서버 부하를 크게 낮춥니다.

• psycopg와 PostgreSQL의 JSON 기능을 활용하면 복잡한 객체 구조도 한 번에 받아올 수 있습니다.

• Pydantic은 받은 데이터를 검증·직렬화하는 과정을 자동화해 코드 가독성을 크게 향상시킵니다.

행동 유도: 위 코드를 그대로 복사해 프로젝트에 적용하고, 직접 실행해 보세요.

실행 결과가 기대와 다르면 댓글이나 GitHub 이슈로 알려 주세요. 여러분의 피드백이 더 나은 튜토리얼을 만드는 원동력이 됩니다!

---

# 📚 참고 자료

• PostgreSQL JSON 함수 공식 문서: https://www.postgresql.org/docs/current/functions-json.html

• psycopg2 사용 가이드: https://www.psycopg.org/docs/

• Pydantic 문서: https://docs.pydantic.dev/

이 글은 PostgreSQL, psycopg, Pydantic을 핵심 키워드로 SEO 최적화되었습니다. “PostgreSQL n+1 문제 해결”, “psycopg JSON 조회”, “Pydantic 데이터 모델링” 등으로 검색하면 바로 찾아볼 수 있습니다.