SQLAlchemy 마이그레이션 없이 ALTER TABLE로 컬럼 추가한 실전 패턴: 작은 API를 급히 고칠 때

SQLAlchemy에서 마이그레이션 도구 없이 컬럼을 추가해야 한다면, 핵심은 간단합니다. DB에 ALTER TABLE을 먼저 적용하고, SQLAlchemy 모델을 같은 커밋에서 맞춘 뒤, 배포 전후로 기존 데이터와 기본값을 확인하면 됩니다.

DB 변경 전 체크리스트를 만들고, ALTER TABLE SQL과 SQLAlchemy 모델 diff를 함께 검토해보세요.

다만 이 방식은 “빨리 끝내는 편법”이 아니라 조건을 따져야 하는 운영 패턴입니다. 작은 SQLite/PostgreSQL 기반 사이드 프로젝트, 내부 어드민, 초기 SaaS의 단순 컬럼 추가에는 충분히 실용적이지만, 팀 개발·복잡한 스키마·무중단 배포가 필요하면 Alembic을 쓰는 편이 맞습니다.

언제 ALTER TABLE 직접 실행이 괜찮을까

제가 작은 FastAPI + SQLAlchemy 프로젝트를 만들 때 가장 자주 만나는 상황은 “사용자 테이블에 플래그 하나만 추가하면 되는” 케이스였습니다. 예를 들어 users 테이블에 is_beta_user 같은 boolean 컬럼을 붙이는 작업입니다.

이 정도 변경 때문에 Alembic 설정, revision 생성, 배포 파이프라인까지 손대기 부담스러운 초기 프로젝트라면 직접 SQL을 실행하는 편이 빠릅니다. 대신 변경 이력을 README나 운영 노트에 남겨야 나중에 스키마가 꼬이지 않습니다.

추천 대상: 이런 프로젝트라면 현실적입니다

• 혼자 또는 2~3명이 관리하는 초기 API 서버
• SQLite, PostgreSQL, MySQL 중 하나를 단순하게 쓰는 프로젝트
• 컬럼 추가가 nullable이거나 안전한 default가 있는 경우
• Claude Code, Cursor, ChatGPT로 코드를 빠르게 고치되 DB 변경은 직접 확인하는 워크플로

반대로 결제, 권한, 주문처럼 장애 비용이 큰 테이블은 직접 SQL 한 줄로 끝내지 않는 게 좋습니다. 특히 NOT NULL 컬럼을 기본값 없이 추가하는 작업은 기존 행 때문에 바로 실패하거나 서비스 코드에서 오류를 만들 수 있습니다.

실전 흐름: DB 변경 → 모델 반영 → 검증

1) 먼저 SQL로 컬럼을 추가합니다

아래는 PostgreSQL 예시입니다. 기존 사용자에게 기본값을 줄 수 있는 컬럼이라면 default를 명시하는 쪽이 안전합니다.

ALTER TABLE users ADD COLUMN is_beta_user BOOLEAN DEFAULT false;

SQLite라면 환경에 따라 지원 범위가 다릅니다. 단순 컬럼 추가는 가능하지만 제약 조건이 복잡하면 테이블 재생성이 필요할 수 있어, 실행 전 공식 문서를 확인하는 편이 좋습니다.

2) SQLAlchemy 모델을 같은 의미로 맞춥니다

from sqlalchemy import Boolean

class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True)
    email = Column(String, nullable=False)
    is_beta_user = Column(Boolean, default=False)

여기서 자주 헷갈리는 지점이 있습니다. default=False는 보통 SQLAlchemy가 새 객체를 만들 때 적용하는 파이썬 쪽 기본값입니다. DB 자체 기본값까지 보장하려면 server_default나 실제 ALTER TABLE의 DEFAULT를 같이 고려해야 합니다.

3) 최소 검증 쿼리를 바로 돌립니다

컬럼 추가 후에는 애플리케이션을 띄우기 전에 DB에서 직접 확인합니다.

SELECT id, email, is_beta_user FROM users LIMIT 5;

그 다음 FastAPI 엔드포인트나 관리자 화면에서 생성·조회가 모두 되는지 봅니다. 저는 이 단계에서 Cursor나 Claude Code에게 “이 모델 변경으로 깨질 수 있는 serializer, Pydantic schema, 테스트를 찾아줘”라고 시키는 편이 가장 빨랐습니다.

Alembic을 안 쓰는 방식과 쓰는 방식 비교

중요한 점은 Base.metadata.create_all()이 기존 테이블에 새 컬럼을 자동으로 붙여주지 않는다는 사실입니다. 이걸 기대하고 모델만 수정하면 로컬에서는 된 것처럼 보이다가 운영에서 column does not exist 오류를 만날 수 있습니다.

구체적 예시: 베타 사용자 플래그 추가

가정해보겠습니다. 작은 AI 코드 리뷰 SaaS에서 베타 기능을 일부 사용자에게만 열고 싶습니다. 현재 users 테이블에는 id, email, created_at만 있습니다.

이때 가장 단순한 순서는 다음입니다.

1. 운영 DB를 백업합니다.
2. ALTER TABLE users ADD COLUMN is_beta_user BOOLEAN DEFAULT false;를 실행합니다.
3. SQLAlchemy User 모델에 컬럼을 추가합니다.
4. Pydantic 응답 스키마에 필요한 경우 필드를 반영합니다.
5. 베타 대상 계정만 UPDATE users SET is_beta_user = true WHERE email = ...로 변경합니다.

이 작업은 작아 보이지만, 프론트엔드에서 해당 값을 기대하거나 캐시가 끼어 있으면 바로 이상해질 수 있습니다. 그래서 SQL, 모델, API 응답, 화면 조건문을 한 번에 묶어 확인하는 게 좋습니다.

가장 흔한 실수 하나

가장 많이 막히는 지점은 “DB에는 컬럼을 추가했는데 모델에는 안 넣거나, 반대로 모델만 수정하는” 경우입니다. SQLAlchemy는 ORM일 뿐이고, 운영 DB의 테이블 구조를 마법처럼 바꿔주지 않습니다.

또 하나는 NOT NULL 컬럼을 기본값 없이 추가하는 실수입니다. 기존 행이 있는 테이블이라면 먼저 nullable로 추가하고 데이터를 채운 뒤, 필요할 때 제약을 강화하는 순서가 더 안전합니다.

FAQ

마이그레이션 없이 해도 정말 괜찮나요?

단순한 additive 변경이면 가능합니다. 하지만 변경 이력 관리가 필요하거나 여러 환경에 같은 스키마를 재현해야 한다면 Alembic을 도입하는 편이 낫습니다.

SQLAlchemy 모델에 default만 쓰면 DB 기본값도 생기나요?

항상 그렇지는 않습니다. 애플리케이션 레벨 기본값과 DB 서버 기본값은 다릅니다. 운영 안정성이 중요하면 ALTER TABLE의 DEFAULT 또는 server_default를 함께 검토하세요.

Claude Code나 ChatGPT에게 맡겨도 될까요?

코드 수정 후보를 찾는 데는 유용합니다. 다만 실제 SQL 실행, 백업, 운영 DB 반영 순서는 사람이 확인해야 합니다. AI가 제안한 SQL은 DB 종류와 버전에 맞는지 반드시 검토하세요.

지금 바로 할 다음 행동

오늘 해야 할 일이 단순 컬럼 추가라면, 먼저 “nullable인지, default가 필요한지, 기존 데이터가 몇 건인지”만 적어보세요. 그 다음 ALTER TABLE SQL과 SQLAlchemy 모델 diff를 한 화면에 놓고 확인하면 실수 확률이 크게 줄어듭니다.

프로젝트가 계속 커질 것 같다면 이번 변경까지만 수동으로 처리하고, 다음 스키마 변경부터 Alembic을 붙이는 선을 정해두는 것도 좋은 선택입니다.

관련 링크

• AutoWP 개발기 — OpenAI로 WordPress 콘텐츠 파이프라인을 만들고 사람이 검수하는 반자동 시스템
• PyInstaller onefile exe가 윈도우 디펜더에 오탐 차단될 때 뚫은 방법: 우회 말고 신뢰도부터 올렸다
• 임베딩 코사인 유사도로 중복 글 자동으로 걸러낸 실전: 워드프레스 발행 전 체크 파이프라인
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크