501 lines
14 KiB
Markdown
501 lines
14 KiB
Markdown
# ORM 동기식 전환 보고서
|
|
|
|
## 개요
|
|
|
|
현재 프로젝트는 **SQLAlchemy 2.0+ 비동기 방식**으로 구현되어 있습니다. 이 보고서는 동기식으로 전환할 경우 필요한 코드 수정 사항을 정리합니다.
|
|
|
|
---
|
|
|
|
## 1. 현재 비동기 구현 현황
|
|
|
|
### 1.1 사용 중인 라이브러리
|
|
- `sqlalchemy[asyncio]>=2.0.45`
|
|
- `asyncmy>=0.2.10` (MySQL 비동기 드라이버)
|
|
- `aiomysql>=0.3.2`
|
|
|
|
### 1.2 주요 비동기 컴포넌트
|
|
| 컴포넌트 | 현재 (비동기) | 변경 후 (동기) |
|
|
|---------|-------------|--------------|
|
|
| 엔진 | `create_async_engine` | `create_engine` |
|
|
| 세션 팩토리 | `async_sessionmaker` | `sessionmaker` |
|
|
| 세션 클래스 | `AsyncSession` | `Session` |
|
|
| DB 드라이버 | `mysql+asyncmy` | `mysql+pymysql` |
|
|
|
|
---
|
|
|
|
## 2. 파일별 수정 사항
|
|
|
|
### 2.1 pyproject.toml - 의존성 변경
|
|
|
|
**파일**: `pyproject.toml`
|
|
|
|
```diff
|
|
dependencies = [
|
|
"fastapi[standard]>=0.115.8",
|
|
- "sqlalchemy[asyncio]>=2.0.45",
|
|
+ "sqlalchemy>=2.0.45",
|
|
- "asyncmy>=0.2.10",
|
|
- "aiomysql>=0.3.2",
|
|
+ "pymysql>=1.1.0",
|
|
...
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
### 2.2 config.py - 데이터베이스 URL 변경
|
|
|
|
**파일**: `config.py` (라인 74-96)
|
|
|
|
```diff
|
|
class DatabaseSettings(BaseSettings):
|
|
@property
|
|
def MYSQL_URL(self) -> str:
|
|
- return f"mysql+asyncmy://{self.MYSQL_USER}:{self.MYSQL_PASSWORD}@{self.MYSQL_HOST}:{self.MYSQL_PORT}/{self.MYSQL_DB}"
|
|
+ return f"mysql+pymysql://{self.MYSQL_USER}:{self.MYSQL_PASSWORD}@{self.MYSQL_HOST}:{self.MYSQL_PORT}/{self.MYSQL_DB}"
|
|
```
|
|
|
|
---
|
|
|
|
### 2.3 app/database/session.py - 세션 설정 전면 수정
|
|
|
|
**파일**: `app/database/session.py`
|
|
|
|
#### 현재 코드 (비동기)
|
|
```python
|
|
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
|
|
from typing import AsyncGenerator
|
|
|
|
engine = create_async_engine(
|
|
url=db_settings.MYSQL_URL,
|
|
echo=False,
|
|
pool_size=10,
|
|
max_overflow=10,
|
|
pool_timeout=5,
|
|
pool_recycle=3600,
|
|
pool_pre_ping=True,
|
|
pool_reset_on_return="rollback",
|
|
)
|
|
|
|
AsyncSessionLocal = async_sessionmaker(
|
|
bind=engine,
|
|
class_=AsyncSession,
|
|
expire_on_commit=False,
|
|
autoflush=False,
|
|
)
|
|
|
|
async def get_session() -> AsyncGenerator[AsyncSession, None]:
|
|
async with AsyncSessionLocal() as session:
|
|
try:
|
|
yield session
|
|
except Exception as e:
|
|
await session.rollback()
|
|
raise e
|
|
```
|
|
|
|
#### 변경 후 코드 (동기)
|
|
```python
|
|
from sqlalchemy import create_engine
|
|
from sqlalchemy.orm import Session, sessionmaker
|
|
from typing import Generator
|
|
|
|
engine = create_engine(
|
|
url=db_settings.MYSQL_URL,
|
|
echo=False,
|
|
pool_size=10,
|
|
max_overflow=10,
|
|
pool_timeout=5,
|
|
pool_recycle=3600,
|
|
pool_pre_ping=True,
|
|
pool_reset_on_return="rollback",
|
|
)
|
|
|
|
SessionLocal = sessionmaker(
|
|
bind=engine,
|
|
class_=Session,
|
|
expire_on_commit=False,
|
|
autoflush=False,
|
|
)
|
|
|
|
def get_session() -> Generator[Session, None, None]:
|
|
with SessionLocal() as session:
|
|
try:
|
|
yield session
|
|
except Exception as e:
|
|
session.rollback()
|
|
raise e
|
|
```
|
|
|
|
#### get_worker_session 함수 변경
|
|
|
|
```diff
|
|
- from contextlib import asynccontextmanager
|
|
+ from contextlib import contextmanager
|
|
|
|
- @asynccontextmanager
|
|
- async def get_worker_session() -> AsyncGenerator[AsyncSession, None]:
|
|
- worker_engine = create_async_engine(
|
|
+ @contextmanager
|
|
+ def get_worker_session() -> Generator[Session, None, None]:
|
|
+ worker_engine = create_engine(
|
|
url=db_settings.MYSQL_URL,
|
|
poolclass=NullPool,
|
|
)
|
|
- session_factory = async_sessionmaker(
|
|
- bind=worker_engine,
|
|
- class_=AsyncSession,
|
|
+ session_factory = sessionmaker(
|
|
+ bind=worker_engine,
|
|
+ class_=Session,
|
|
expire_on_commit=False,
|
|
autoflush=False,
|
|
)
|
|
|
|
- async with session_factory() as session:
|
|
+ with session_factory() as session:
|
|
try:
|
|
yield session
|
|
finally:
|
|
- await session.close()
|
|
- await worker_engine.dispose()
|
|
+ session.close()
|
|
+ worker_engine.dispose()
|
|
```
|
|
|
|
---
|
|
|
|
### 2.4 app/*/dependencies.py - 타입 힌트 변경
|
|
|
|
**파일**: `app/song/dependencies.py`, `app/lyric/dependencies.py`, `app/video/dependencies.py`
|
|
|
|
```diff
|
|
- from sqlalchemy.ext.asyncio import AsyncSession
|
|
+ from sqlalchemy.orm import Session
|
|
|
|
- SessionDep = Annotated[AsyncSession, Depends(get_session)]
|
|
+ SessionDep = Annotated[Session, Depends(get_session)]
|
|
```
|
|
|
|
---
|
|
|
|
### 2.5 라우터 파일들 - async/await 제거
|
|
|
|
**영향받는 파일**:
|
|
- `app/home/api/routers/v1/home.py`
|
|
- `app/lyric/api/routers/v1/lyric.py`
|
|
- `app/song/api/routers/v1/song.py`
|
|
- `app/video/api/routers/v1/video.py`
|
|
|
|
#### 예시: lyric.py (라인 70-90)
|
|
|
|
```diff
|
|
- async def get_lyric_by_task_id(
|
|
+ def get_lyric_by_task_id(
|
|
task_id: str,
|
|
- session: AsyncSession = Depends(get_session),
|
|
+ session: Session = Depends(get_session),
|
|
):
|
|
- result = await session.execute(select(Lyric).where(Lyric.task_id == task_id))
|
|
+ result = session.execute(select(Lyric).where(Lyric.task_id == task_id))
|
|
lyric = result.scalar_one_or_none()
|
|
...
|
|
```
|
|
|
|
#### 예시: CRUD 작업 (라인 218-260)
|
|
|
|
```diff
|
|
- async def create_project(
|
|
+ def create_project(
|
|
request_body: ProjectCreateRequest,
|
|
- session: AsyncSession = Depends(get_session),
|
|
+ session: Session = Depends(get_session),
|
|
):
|
|
project = Project(
|
|
store_name=request_body.customer_name,
|
|
region=request_body.region,
|
|
task_id=task_id,
|
|
)
|
|
session.add(project)
|
|
- await session.commit()
|
|
- await session.refresh(project)
|
|
+ session.commit()
|
|
+ session.refresh(project)
|
|
return project
|
|
```
|
|
|
|
#### 예시: 플러시 작업 (home.py 라인 340-350)
|
|
|
|
```diff
|
|
session.add(image)
|
|
- await session.flush()
|
|
+ session.flush()
|
|
result = image.id
|
|
```
|
|
|
|
---
|
|
|
|
### 2.6 서비스 파일들 - Raw SQL 쿼리 변경
|
|
|
|
**영향받는 파일**:
|
|
- `app/lyric/services/lyrics.py`
|
|
- `app/song/services/song.py`
|
|
- `app/video/services/video.py`
|
|
|
|
#### 예시: lyrics.py (라인 20-30)
|
|
|
|
```diff
|
|
- async def get_store_default_info(conn: AsyncConnection):
|
|
+ def get_store_default_info(conn: Connection):
|
|
query = """SELECT * FROM store_default_info;"""
|
|
- result = await conn.execute(text(query))
|
|
+ result = conn.execute(text(query))
|
|
return result.fetchall()
|
|
```
|
|
|
|
#### 예시: INSERT 쿼리 (라인 360-400)
|
|
|
|
```diff
|
|
- async def insert_song_result(conn: AsyncConnection, params: dict):
|
|
+ def insert_song_result(conn: Connection, params: dict):
|
|
insert_query = """INSERT INTO song_results_all (...) VALUES (...)"""
|
|
- await conn.execute(text(insert_query), params)
|
|
- await conn.commit()
|
|
+ conn.execute(text(insert_query), params)
|
|
+ conn.commit()
|
|
```
|
|
|
|
---
|
|
|
|
### 2.7 app/home/services/base.py - BaseService 클래스
|
|
|
|
**파일**: `app/home/services/base.py`
|
|
|
|
```diff
|
|
- from sqlalchemy.ext.asyncio import AsyncSession
|
|
+ from sqlalchemy.orm import Session
|
|
|
|
class BaseService:
|
|
- def __init__(self, model, session: AsyncSession):
|
|
+ def __init__(self, model, session: Session):
|
|
self.model = model
|
|
self.session = session
|
|
|
|
- async def _get(self, id: UUID):
|
|
- return await self.session.get(self.model, id)
|
|
+ def _get(self, id: UUID):
|
|
+ return self.session.get(self.model, id)
|
|
|
|
- async def _add(self, entity):
|
|
+ def _add(self, entity):
|
|
self.session.add(entity)
|
|
- await self.session.commit()
|
|
- await self.session.refresh(entity)
|
|
+ self.session.commit()
|
|
+ self.session.refresh(entity)
|
|
return entity
|
|
|
|
- async def _update(self, entity):
|
|
- return await self._add(entity)
|
|
+ def _update(self, entity):
|
|
+ return self._add(entity)
|
|
|
|
- async def _delete(self, entity):
|
|
- await self.session.delete(entity)
|
|
+ def _delete(self, entity):
|
|
+ self.session.delete(entity)
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 모델 파일 - 변경 불필요
|
|
|
|
다음 모델 파일들은 **변경이 필요 없습니다**:
|
|
- `app/home/models.py`
|
|
- `app/lyric/models.py`
|
|
- `app/song/models.py`
|
|
- `app/video/models.py`
|
|
|
|
모델 정의 자체는 비동기/동기와 무관하게 동일합니다. `Mapped`, `mapped_column`, `relationship` 등은 그대로 사용 가능합니다.
|
|
|
|
단, **관계 로딩 전략**에서 `lazy="selectin"` 설정은 동기 환경에서도 작동하지만, 필요에 따라 `lazy="joined"` 또는 `lazy="subquery"`로 변경할 수 있습니다.
|
|
|
|
---
|
|
|
|
## 4. 수정 패턴 요약
|
|
|
|
### 4.1 Import 변경 패턴
|
|
|
|
```diff
|
|
# 엔진/세션 관련
|
|
- from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
|
|
+ from sqlalchemy import create_engine
|
|
+ from sqlalchemy.orm import Session, sessionmaker
|
|
|
|
# 타입 힌트
|
|
- from typing import AsyncGenerator
|
|
+ from typing import Generator
|
|
|
|
# 컨텍스트 매니저
|
|
- from contextlib import asynccontextmanager
|
|
+ from contextlib import contextmanager
|
|
```
|
|
|
|
### 4.2 함수 정의 변경 패턴
|
|
|
|
```diff
|
|
- async def function_name(...):
|
|
+ def function_name(...):
|
|
```
|
|
|
|
### 4.3 await 제거 패턴
|
|
|
|
```diff
|
|
- result = await session.execute(query)
|
|
+ result = session.execute(query)
|
|
|
|
- await session.commit()
|
|
+ session.commit()
|
|
|
|
- await session.refresh(obj)
|
|
+ session.refresh(obj)
|
|
|
|
- await session.flush()
|
|
+ session.flush()
|
|
|
|
- await session.rollback()
|
|
+ session.rollback()
|
|
|
|
- await session.close()
|
|
+ session.close()
|
|
|
|
- await engine.dispose()
|
|
+ engine.dispose()
|
|
```
|
|
|
|
### 4.4 컨텍스트 매니저 변경 패턴
|
|
|
|
```diff
|
|
- async with SessionLocal() as session:
|
|
+ with SessionLocal() as session:
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 영향받는 파일 목록
|
|
|
|
### 5.1 반드시 수정해야 하는 파일
|
|
|
|
| 파일 | 수정 범위 |
|
|
|-----|---------|
|
|
| `pyproject.toml` | 의존성 변경 |
|
|
| `config.py` | DB URL 변경 |
|
|
| `app/database/session.py` | 전면 수정 |
|
|
| `app/database/session-prod.py` | 전면 수정 |
|
|
| `app/home/api/routers/v1/home.py` | async/await 제거 |
|
|
| `app/lyric/api/routers/v1/lyric.py` | async/await 제거 |
|
|
| `app/song/api/routers/v1/song.py` | async/await 제거 |
|
|
| `app/video/api/routers/v1/video.py` | async/await 제거 |
|
|
| `app/lyric/services/lyrics.py` | async/await 제거 |
|
|
| `app/song/services/song.py` | async/await 제거 |
|
|
| `app/video/services/video.py` | async/await 제거 |
|
|
| `app/home/services/base.py` | async/await 제거 |
|
|
| `app/song/dependencies.py` | 타입 힌트 변경 |
|
|
| `app/lyric/dependencies.py` | 타입 힌트 변경 |
|
|
| `app/video/dependencies.py` | 타입 힌트 변경 |
|
|
| `app/dependencies/database.py` | 타입 힌트 변경 |
|
|
|
|
### 5.2 수정 불필요한 파일
|
|
|
|
| 파일 | 이유 |
|
|
|-----|-----|
|
|
| `app/home/models.py` | 모델 정의는 동기/비동기 무관 |
|
|
| `app/lyric/models.py` | 모델 정의는 동기/비동기 무관 |
|
|
| `app/song/models.py` | 모델 정의는 동기/비동기 무관 |
|
|
| `app/video/models.py` | 모델 정의는 동기/비동기 무관 |
|
|
|
|
---
|
|
|
|
## 6. 주의사항
|
|
|
|
### 6.1 FastAPI와의 호환성
|
|
|
|
FastAPI는 동기 엔드포인트도 지원합니다. 동기 함수는 스레드 풀에서 실행됩니다:
|
|
|
|
```python
|
|
# 동기 엔드포인트 - FastAPI가 자동으로 스레드풀에서 실행
|
|
@router.get("/items/{item_id}")
|
|
def get_item(item_id: int, session: Session = Depends(get_session)):
|
|
return session.get(Item, item_id)
|
|
```
|
|
|
|
### 6.2 성능 고려사항
|
|
|
|
동기식으로 전환 시 고려할 점:
|
|
- **동시성 감소**: 비동기 I/O의 이점 상실
|
|
- **스레드 풀 의존**: 동시 요청이 많을 경우 스레드 풀 크기 조정 필요
|
|
- **블로킹 I/O**: DB 쿼리 중 다른 요청 처리 불가
|
|
|
|
### 6.3 백그라운드 작업
|
|
|
|
현재 `get_worker_session()`으로 별도 이벤트 루프에서 실행되는 백그라운드 작업이 있습니다. 동기식 전환 시 스레드 기반 백그라운드 작업으로 변경해야 합니다:
|
|
|
|
```python
|
|
from concurrent.futures import ThreadPoolExecutor
|
|
|
|
executor = ThreadPoolExecutor(max_workers=4)
|
|
|
|
def background_task():
|
|
with get_worker_session() as session:
|
|
# 작업 수행
|
|
pass
|
|
|
|
# 실행
|
|
executor.submit(background_task)
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 마이그레이션 단계
|
|
|
|
### Step 1: 의존성 변경
|
|
1. `pyproject.toml` 수정
|
|
2. `pip install pymysql` 또는 `uv sync` 실행
|
|
|
|
### Step 2: 설정 파일 수정
|
|
1. `config.py`의 DB URL 변경
|
|
2. `app/database/session.py` 전면 수정
|
|
|
|
### Step 3: 라우터 수정
|
|
1. 각 라우터 파일의 `async def` → `def` 변경
|
|
2. 모든 `await` 키워드 제거
|
|
3. `AsyncSession` → `Session` 타입 힌트 변경
|
|
|
|
### Step 4: 서비스 수정
|
|
1. 서비스 파일들의 async/await 제거
|
|
2. Raw SQL 쿼리 함수들 수정
|
|
|
|
### Step 5: 의존성 수정
|
|
1. `dependencies.py` 파일들의 타입 힌트 변경
|
|
|
|
### Step 6: 테스트
|
|
1. 모든 엔드포인트 기능 테스트
|
|
2. 성능 테스트 (동시 요청 처리 확인)
|
|
|
|
---
|
|
|
|
## 8. 결론
|
|
|
|
비동기에서 동기로 전환은 기술적으로 가능하지만, 다음을 고려해야 합니다:
|
|
|
|
**장점**:
|
|
- 코드 복잡도 감소 (async/await 제거)
|
|
- 디버깅 용이
|
|
- 레거시 라이브러리와의 호환성 향상
|
|
|
|
**단점**:
|
|
- 동시성 처리 능력 감소
|
|
- I/O 바운드 작업에서 성능 저하 가능
|
|
- FastAPI의 비동기 장점 미활용
|
|
|
|
현재 프로젝트가 FastAPI 기반이고 I/O 작업(DB, 외부 API 호출)이 많다면, **비동기 유지를 권장**합니다. 동기 전환은 특별한 요구사항(레거시 통합, 팀 역량 등)이 있을 때만 고려하시기 바랍니다.
|