테이블 메타데이터

테이블 메타데이터 (Table Metadata)

SQLAlchemy에서 데이터베이스 스키마는 파이썬 객체로 표현돼요. MetaData는 테이블·컬럼·제약 등 스키마 정보를 담는 컨테이너이고, Table과 Column으로 테이블 구조를 정의해요. 이 구조는 ORM 매핑과 Core 모두의 기반이 돼요.

출처: SQLAlchemy — Table Metadata

MetaData와 Table

MetaData 객체에 Table 객체를 담아 스키마를 구성해요. 컬럼은 Column()으로 정의하며, 타입으로 Integer, String, DateTime 등을 지정해요.

from sqlalchemy import MetaData, Table, Column, Integer, String

metadata = MetaData()

user_table = Table(
    "user_account",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("name", String(30)),
    Column("fullname", String),
)

스키마를 데이터베이스에 반영

정의한 메타데이터를 실제 데이터베이스에 테이블로 만들려면 metadata.create_all(engine)을 호출해요. 존재하지 않는 테이블만 생성하며, 기존 테이블은 건드리지 않아요.

metadata.create_all(engine)

표준 타입 어노테이션 매핑 (2.0)

2.0부터는 ORM에서 DeclarativeBase와 Mapped, mapped_column()을 써서 클래스 자체로 테이블을 선언할 수 있어요. 이때도 내부적으로는 MetaData와 Table 구조가 생성되며, Base.metadata로 접근할 수 있어요.

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "user_account"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))
    fullname: Mapped[str | None]

# 실제 테이블 생성
Base.metadata.create_all(engine)

메타데이터가 중요한 이유

메타데이터는 스키마의 단일 진실원천이에요. 이를 바탕으로 테이블 생성뿐 아니라, 검사(반영), 쿼리 구성(Core expression), 마이그레이션(Alembic)이 모두 동작해요. 테이블 구조를 한곳에서 관리할 수 있게 해 주는 것이 핵심이에요.

테이블 메타데이터