파이썬 FastAPI 고급 ORM – 관계 모델링과 다중 테이블 연동
여러분의 FastAPI 앱이 점점 커지고 있나요?
단일 테이블로는 한계가 있다 느낄 때,
지금이 바로 관계형 모델링을 배워야 할 타이밍입니다!
안녕하세요, 개발자 여러분 😊
오늘은 FastAPI와 SQLAlchemy ORM을 활용하여 "다중 테이블 관계 설정"과 Pydantic 스키마 연계까지 다뤄볼 거예요.
특히 User와 Todo 같은 실용적인 예제를 중심으로 일대다(1:N), 다대다(N:M) 관계를 어떻게 모델링하는지, 그리고 이를 CRUD API로 어떻게 연결하는지 구체적으로 살펴봅니다.
FastAPI를 사용하다 보면 단일 테이블로 구현한 간단한 예제는 금방 만들 수 있지만, 실제 애플리케이션에서는 테이블 간의 관계가 필수입니다. 오늘은 이걸 제대로 배워볼 거예요.
목차
1. 테이블 간 관계 설정의 기초 🧩
FastAPI에서 데이터베이스를 제대로 다루기 위해선 SQLAlchemy ORM을 이용한 관계형 모델링이 거의 필수예요.
특히 다수의 테이블이 얽힌 구조에서는 일대다(One-to-Many), 다대다(Many-to-Many) 같은 관계 설정이 핵심이 됩니다.
예를 들어 한 명의 사용자가 여러 개의 Todo를 소유하거나, 여러 사용자가 여러 프로젝트에 동시에 참여할 수 있다면 관계형 설계가 반드시 필요하죠.
1.1 일대다 관계란 무엇인가요?
가장 흔한 관계가 바로 1:N 관계예요.
한 사람이 여러 개의 블로그 글을 작성하는 경우처럼요.
이를 SQLAlchemy에서는 다음과 같은 방식으로 표현합니다:
from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
username = Column(String, unique=True, index=True)
posts = relationship("Post", back_populates="author")
class Post(Base):
__tablename__ = "posts"
id = Column(Integer, primary_key=True)
title = Column(String)
content = Column(String)
author_id = Column(Integer, ForeignKey("users.id"))
author = relationship("User", back_populates="posts")
여기서 핵심은 ForeignKey와 relationship입니다.
Post.author_id는 User 테이블의 id를 참조하는 외래 키이고, 두 모델은 back_populates로 서로를 참조합니다.
이 설정 덕분에 user.posts로 해당 사용자의 모든 게시글을 가져올 수 있고, post.author로 작성자 정보를 조회할 수 있어요.
1.2 다대다 관계는 어떻게 구성할까요?
조금 더 복잡한 구조인 N:M 관계는 중간 테이블(association table)을 만들어야 합니다.
예를 들어 사용자와 프로젝트는 다음과 같이 설정할 수 있습니다.
association_table = Table(
"user_project",
Base.metadata,
Column("user_id", ForeignKey("users.id"), primary_key=True),
Column("project_id", ForeignKey("projects.id"), primary_key=True),
)
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
username = Column(String)
projects = relationship("Project", secondary=association_table, back_populates="members")
class Project(Base):
__tablename__ = "projects"
id = Column(Integer, primary_key=True)
title = Column(String)
members = relationship("User", secondary=association_table, back_populates="projects")
이처럼 secondary 파라미터를 이용해 중간 테이블을 지정하고, 관계를 서로 연결하면 user.projects, project.members로 양방향 접근이 가능해요.
실제 현업에서도 협업 앱, 팀 관리 시스템 등에서 자주 쓰이는 구조입니다.
📋 일대다 vs 다대다 – 요약 비교
| 구분 | 일대다 (1:N) | 다대다 (N:M) |
|---|---|---|
| 예시 | 사용자 – 게시글 | 사용자 – 프로젝트 |
| 테이블 구성 | 두 개의 테이블 + 외래 키 | 세 개의 테이블 (중간 테이블 포함) |
| SQLAlchemy 설정 | ForeignKey, relationship | association_table, secondary, relationship |
이제 관계 설정의 기초를 이해하셨다면, 다음 단계에서는 실제로 FastAPI에서 SQLAlchemy ORM 모델을 작성하고, 이 관계가 어떻게 작동하는지 하나씩 코드를 통해 살펴볼 거예요.
2. 관계를 표현하는 SQLAlchemy 모델 구조 🏗️
자, 이제 본격적으로 모델을 구성해볼 시간이에요.
FastAPI에서 SQLAlchemy ORM을 사용할 때는 클래스를 기반으로 테이블을 정의하고,
relationship()과 ForeignKey()를 통해 테이블 간의 관계를 표현합니다.
우리가 구현할 시나리오는 아주 현실적이에요:
사용자(User)가 여러 개의 할 일(Todo)을 가질 수 있는 일대다(1:N) 구조입니다.
2.1 사용자(User)와 할 일(Todo) 모델 정의
아래 코드는 SQLAlchemy ORM을 사용한 관계형 모델 정의 예시입니다.
중요한 건 각 모델이 서로를 어떻게 참조하고 있는지예요.
from sqlalchemy import Column, Integer, String, Boolean, ForeignKey
from sqlalchemy.orm import relationship
from database import Base # Base는 SQLAlchemy의 declarative_base()로 정의
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True, index=True)
username = Column(String, unique=True, index=True)
todos = relationship("Todo", back_populates="owner")
class Todo(Base):
__tablename__ = "todos"
id = Column(Integer, primary_key=True, index=True)
title = Column(String, index=True)
description = Column(String, nullable=True)
done = Column(Boolean, default=False)
owner_id = Column(Integer, ForeignKey("users.id"))
owner = relationship("User", back_populates="todos")
이 구조에서 User.todos는 해당 사용자가 작성한 모든 Todo 항목을 리스트로 반환하며, Todo.owner는 해당 항목의 작성자(User 객체)를 가리킵니다.
이렇게 하면 ORM 객체 간 탐색이 매우 쉬워져요.
🧠 관계형 구조의 장점은?
- ORM 객체 간 탐색이 쉬워져 복잡한 쿼리를 단순화할 수 있습니다.
- Pydantic과 함께 사용할 때 직관적인 JSON 변환이 가능합니다.
- 모델 간의 의존성 설계가 명확해져 유지보수가 쉬워집니다.
2.2 모델 구조 정리 예시
| 테이블 | 컬럼 | 비고 |
|---|---|---|
| users | id, username | username은 unique + index |
| todos | id, title, description, done, owner_id | owner_id는 users.id를 ForeignKey로 참조 |
이제 관계 설정이 완료된 ORM 모델 구조를 완성했어요!
다음 단계에서는 Pydantic 스키마를 통해 ORM 객체와 어떻게 연동하고 응답 데이터를 어떻게 구성하는지 다뤄볼게요.
이 부분이 바로 FastAPI의 강력함이 드러나는 순간입니다 💪
3. Pydantic 스키마와 ORM 연계하기 🔄
FastAPI의 가장 큰 장점 중 하나는 Pydantic을 활용한 데이터 유효성 검증과 직렬화예요.
특히 ORM 모델과 Pydantic BaseModel을 함께 사용하면, 우리가 만든 SQLAlchemy 객체를 JSON으로 변환하거나 사용자 입력을 유효성 있게 처리하는 게 정말 간단해집니다.
핵심은 orm_mode 설정을 통해 ORM 객체를 바로 변환할 수 있도록 만드는 거예요.
3.1 Todo 스키마 구성
먼저 Todo 항목을 표현할 Pydantic 스키마를 작성해보겠습니다.
아래처럼 기본 정보와 orm_mode 설정만 해주면 FastAPI에서 ORM 객체를 응답 모델로 사용할 수 있게 됩니다.
from pydantic import BaseModel
from typing import Optional
class TodoItem(BaseModel):
id: int
title: str
description: Optional[str] = None
done: bool
class Config:
orm_mode = True
이제 response_model=TodoItem으로 설정한 API에서 SQLAlchemy Todo 객체를 반환하면, FastAPI가 자동으로 이 객체를 JSON으로 변환해줍니다.
놀랍게도 따로 변환 로직을 만들 필요가 없어요.
3.2 User 입력/출력 스키마 분리
FastAPI에서는 API의 목적에 따라 입력용과 출력용 스키마를 분리해서 사용하는 게 일반적이에요.
예를 들어 사용자 등록 시엔 비밀번호를 받아야 하지만, 사용자 정보를 응답할 땐 비밀번호가 절대 노출되어선 안 되죠.
class UserCreate(BaseModel):
username: str
password: str # 실제로는 해싱 필요
class User(BaseModel):
id: int
username: str
class Config:
orm_mode = True
이처럼 분리함으로써 보안은 물론 API 명세도 깔끔해지고 유지보수가 쉬워져요.
특히 비밀번호 필드는 출력을 철저히 막는 게 기본입니다.
실습에서는 해싱을 생략하지만, 실제 서비스에서는 절대 평문 저장하면 안 된다는 거, 꼭 기억해주세요!
3.3 관계 필드를 포함한 응답 스키마
관계를 활용한 응답을 구성할 때는 중첩 모델(Nested Model)을 사용할 수 있어요.
예를 들어 사용자 조회 시 해당 사용자의 Todo 목록을 함께 반환하고 싶다면 아래처럼 구성합니다.
from typing import List
class UserWithTodos(BaseModel):
id: int
username: str
todos: List[TodoItem] = []
class Config:
orm_mode = True
주의할 점은 데이터량이 많아지면 응답 속도나 용량에 영향을 줄 수 있으므로 꼭 필요한 경우에만 중첩 구조를 사용하는 게 좋습니다.
예를 들어 Todo가 수천 개라면...? 페이지네이션이 필요하겠죠 😅
✅ 정리: ORM ↔ Pydantic 연동 요약
| 구분 | 내용 |
|---|---|
| 입력 스키마 | 필수 입력값 (비밀번호 포함 가능) |
| 출력 스키마 | 응답에 포함할 필드만 선택 |
| orm_mode | ORM 객체를 자동으로 Pydantic으로 변환 가능하게 함 |
| 중첩 스키마 | 관계 객체를 포함하고 싶을 때 List, Optional 등으로 표현 |
이제 ORM과 스키마 간의 연결 고리를 완성했습니다.
다음은 이걸 활용해서 실제 API를 만들고, 사용자와 Todo 항목을 어떻게 엮는지 실습으로 들어가볼게요.
4. 사용자 기반 Todo API 만들기 ⚙️
지금부터는 앞서 만든 User ↔ Todo 관계를 실제 API에서 어떻게 다룰 수 있는지 구체적으로 알아볼게요.
예제를 통해 사용자와 연동된 Todo 항목을 만들고, 조회하고, 연결 관계를 유지하면서 데이터를 다룰 수 있게 해볼 거예요.
4.1 사용자 등록 API
사용자 등록은 POST /users로 진행합니다.
중복 사용자명을 체크하고, 평문 비밀번호를 그대로 저장합니다(실습 단순화용).
@app.post("/users", response_model=User)
def create_user(user: UserCreate, db: Session = Depends(get_db)):
existing_user = db.query(User).filter(User.username == user.username).first()
if existing_user:
raise HTTPException(status_code=400, detail="이미 존재하는 사용자명입니다.")
new_user = User(username=user.username)
db.add(new_user)
db.commit()
db.refresh(new_user)
return new_user
여기선 비밀번호 해싱 없이 단순하게 처리하지만, 실제 서비스라면 반드시 bcrypt 등으로 암호화해야 한다는 점 잊지 마세요.
4.2 사용자 기반 Todo 생성
이제 Todo 항목을 만들면서 사용자와 연결해볼게요.
POST /users/{user_id}/todos로 요청 시 해당 사용자의 소유 Todo를 생성하는 방식입니다.
@app.post("/users/{user_id}/todos", response_model=TodoItem)
def create_todo_for_user(user_id: int, todo: TodoItemCreate, db: Session = Depends(get_db)):
user = db.query(User).filter(User.id == user_id).first()
if not user:
raise HTTPException(status_code=404, detail="해당 사용자를 찾을 수 없습니다.")
new_todo = Todo(**todo.dict(), owner_id=user_id)
db.add(new_todo)
db.commit()
db.refresh(new_todo)
return new_todo
이 API는 user_id를 URL로 받고, 실제로 존재하는 사용자인지 확인한 후 그 사용자에게 Todo 항목을 연결해요. 데이터 무결성을 유지하는 좋은 예입니다.
4.3 사용자 별 Todo 목록 조회
GET /users/{user_id}/todos 요청으로 해당 사용자의 할 일 목록을 조회할 수 있어요. List[TodoItem] 형태로 응답하므로 클라이언트 입장에서도 처리하기 쉽습니다.
@app.get("/users/{user_id}/todos", response_model=List[TodoItem])
def get_user_todos(user_id: int, db: Session = Depends(get_db)):
user = db.query(User).filter(User.id == user_id).first()
if not user:
raise HTTPException(status_code=404, detail="사용자가 존재하지 않습니다.")
return user.todos
🚀 라우팅 구조 요약
- POST /users → 사용자 생성
- POST /users/{user_id}/todos → Todo 생성 (소유자 연결)
- GET /users/{user_id}/todos → Todo 목록 조회
이러한 RESTful한 구조는 실무에서도 아주 자주 사용되는 패턴입니다.
리소스 기반 URL 설계와 HTTP 메서드 의미를 자연스럽게 활용할 수 있어 API의 일관성과 가독성을 높여줘요.
5. 관계 응답과 데이터 최적화 전략 📦
데이터베이스 관계를 설정하고 API를 만들다 보면, 관계 필드를 API 응답에 포함해야 할 때가 많아요.
예를 들어 사용자 정보를 조회할 때 해당 사용자가 등록한 모든 할 일 목록까지 함께 보내주고 싶은 경우가 있죠.
이럴 땐 orm_mode=True 설정과 함께 Nested Pydantic 모델을 사용하면 됩니다.
5.1 관계 필드 포함한 사용자 응답 예시
앞서 정의한 UserWithTodos 스키마를 활용하면 사용자와 해당 사용자의 할 일을 한꺼번에 응답할 수 있어요.
@app.get("/users/{user_id}", response_model=UserWithTodos)
def get_user_detail(user_id: int, db: Session = Depends(get_db)):
user = db.query(User).filter(User.id == user_id).first()
if not user:
raise HTTPException(status_code=404, detail="사용자를 찾을 수 없습니다.")
return user
이 API는 매우 직관적이고, 프론트엔드 입장에서도 한 번의 요청으로 사용자와 그에 따른 할 일을 모두 받아볼 수 있으니 편리하죠.
하지만 여기에는 중요한 함정이 있어요…
5.2 Lazy Loading의 한계
SQLAlchemy는 기본적으로 관계 데이터를 지연 로딩(Lazy Loading)합니다.
즉, 관계 필드를 실제로 접근하기 전까지는 쿼리를 실행하지 않죠.
이게 편리하긴 한데, 반복되는 쿼리 발생으로 N+1 문제가 생길 수 있어요.
예를 들어 1명의 사용자를 불러오고 todos를 포함해 응답하려면, user.todos 접근 시마다 새로운 SELECT 쿼리가 실행되기 때문에 비효율적입니다.
이런 상황에선 selectinload() 같은 Eager Loading 전략을 사용하면 좋아요.
from sqlalchemy.orm import selectinload
@app.get("/users/{user_id}", response_model=UserWithTodos)
def get_user_with_todos(user_id: int, db: Session = Depends(get_db)):
user = db.query(User).options(selectinload(User.todos)).filter(User.id == user_id).first()
if not user:
raise HTTPException(status_code=404, detail="해당 사용자가 없습니다.")
return user
selectinload()를 옵션에 포함시키면, 사용자와 할 일 목록을 단 두 번의 쿼리로 한번에 가져올 수 있어서 효율적이에요.
5.3 중첩 응답의 설계 전략
모든 관계 데이터를 항상 응답에 포함시키는 건 좋은 전략이 아닐 수 있어요.
데이터가 커질수록 성능에 악영향을 줄 수 있거든요.
그래서 보통은 아래와 같은 전략을 추천해요.
- 단순 응답: 기본적으로 ID, 이름 등 요약된 정보만 제공
- 선택적 확장: 필요할 때만 쿼리 파라미터(ex:
?include=todos)로 전체 정보 요청 - 페이지네이션 도입: 할 일 목록이 많다면 offset/limit 사용
🔍 이런 경우 주의하세요!
관계가 양방향(back_populates)으로 설정되어 있는 경우 순환 참조 문제가 생길 수 있어요.
예를 들어 User → Todo → User → Todo... 식으로 무한 루프가 발생할 수 있으니, 이런 경우엔 관계 필드를 Optional로 정의하거나 재귀 깊이를 제어하는 방법을 활용해야 합니다.
이처럼 관계 응답은 강력한 기능이지만 설계 전략이 명확해야 성능과 보안 모두 잡을 수 있어요.
다음 단계에서는 실제 서비스에서 모델 구조가 변경되었을 때 어떻게 대응하는지, 마이그레이션 도구 Alembic을 소개해볼게요!
6. (선택) Alembic으로 마이그레이션 관리하기 📜
여러분, ORM 모델을 작성하고 데이터베이스와 연동하는 단계까지는 성공했지만, 현실은 언제나 변화하죠. 테이블 구조가 바뀌면 어떻게 해야 할까요?
매번 수동으로 SQL ALTER TABLE 문을 쓰기엔 너무 번거롭고 위험하기까지 합니다.
그래서 등장한 게 바로 Alembic입니다!
6.1 Alembic이란 무엇인가요?
Alembic은 SQLAlchemy 프로젝트의 공식 마이그레이션 도구예요.
우리가 ORM 모델을 수정하면, 이를 자동 감지해 버전 기반 마이그레이션 파일로 만들어주고, 데이터베이스에 적용하거나 되돌리는 작업을 쉽게 해줍니다.
- 모델 → DB 테이블 생성
- 모델 수정 → 마이그레이션 스크립트 자동 생성
- 변경 사항 추적 및 롤백 가능
6.2 설치 및 초기 설정
pip install alembic
alembic init alembic
위 명령어를 입력하면 alembic 폴더와 설정 파일이 생성돼요.
그다음 env.py 파일에서 SQLAlchemy Base 모델과 데이터베이스 URL을 연결해줘야 해요.
6.3 자동 마이그레이션 생성
alembic revision --autogenerate -m "Add owner_id to Todo"
alembic upgrade head
이렇게 하면 모델 변경 사항을 기반으로 마이그레이션 파일이 생성되고, upgrade head 명령으로 DB에 실제 적용할 수 있어요.
테이블이 추가되거나 컬럼이 변경될 때도 자동으로 반영되니 정말 유용하죠.
💡 팁: 버전 관리 전략
- 모든 모델 변경 시 마이그레이션 생성 필수!
-
downgrade로 이전 버전으로 복구 가능 (테스트 환경에서 유용) - 버전 파일은 Git으로 함께 관리!
이번 글에서는 실습에 Alembic을 직접 적용하지는 않았지만, FastAPI + SQLAlchemy를 실제 서비스에 도입할 때는 반드시 필요한 도구입니다.
공식 문서를 꼭 참고해 보시고, 여러분의 프로젝트에 도입해보세요!
지금까지 FastAPI에서 SQLAlchemy를 활용한 고급 ORM 관계 모델링과 다중 테이블 연동에 대해 하나하나 살펴보았습니다.
단순한 CRUD를 넘어서 관계를 정의하고, Pydantic 모델과 연계하고, 사용자 기반의 RESTful API를 만드는 실전 흐름까지 따라오셨다면 정말 큰 도약을 하신 거예요!
처음에는 관계 설정이 어렵게 느껴질 수 있지만, 코드를 따라 치고, 하나씩 요청을 만들어보면 생각보다 명확해진답니다.
특히 ORM 객체와 Pydantic 스키마의 분리, Lazy vs Eager Loading 개념, API 응답 최적화 전략은 실무에서도 자주 마주하게 되니 이번 기회에 확실히 익혀두시길 추천드려요.
앞으로 여러분의 FastAPI 프로젝트에 더 복잡한 모델 구조나 비즈니스 로직을 추가하게 되면, 이 관계 모델링이 탄탄한 기반이 되어줄 거예요.
그리고 모델이 복잡해질수록 Alembic을 통한 마이그레이션 관리는 필수입니다. 꼭 연습해보세요!
다음 글에서는 사용자 인증(Authentication)과 권한 부여(Authorization), OAuth2 등 보안 요소를 어떻게 FastAPI에 적용하는지 다룰 예정이에요.
궁금하셨던 분들 많으시죠? 😉
'Python > Python 웹프로그래밍' 카테고리의 다른 글
| [FastAPI-⑦] 파이썬 FastAPI 실전 프로젝트 (1) – 블로그 API/Todo API 설계 및 구현 (0) | 2025.04.16 |
|---|---|
| [FastAPI-⑥] 파이썬 FastAPI 예외 처리, 테스트 및 프로젝트 구조화 (0) | 2025.04.16 |
| [FastAPI-④] 파이썬 FastAPI 데이터베이스 연동 – SQLAlchemy ORM 시작 (0) | 2025.04.16 |
| [FastAPI-③] 파이썬 FastAPI Pydantic을 통한 데이터 모델링과 검증 (0) | 2025.04.16 |
| [FastAPI-②] 파이썬 FastAPI 요청 처리 심화 – 경로와 쿼리 매개변수, 다양한 요청 방식 (0) | 2025.04.16 |
