Alembic 및 SQLAlchemy 모범 사례

이 기사에서는 Alembic 및 SQLAlchemy를 사용할 때 프로젝트를 체계적으로 정리하고 데이터베이스 유지 관리를 단순화하며 일반적인 함정을 방지하는 데 도움이 되는 몇 가지 모범 사례를 간략하게 살펴보겠습니다. 이러한 기술을 통해 여러 번 문제를 겪을 수 있었습니다. 우리가 다룰 내용은 다음과 같습니다.

1. 명명 규칙
2. 날짜별 마이그레이션 정렬
3. 테이블, 열 및 마이그레이션 설명
4. 모델 없이 마이그레이션 시 데이터 처리
5. 이동 테스트(계단 테스트)
6. 마이그레이션 실행 서비스
7. 모델용 믹스인 사용

1. 명명 규칙

SQLAlchemy를 사용하면 마이그레이션을 생성할 때 모든 테이블과 제약 조건에 자동으로 적용되는 명명 규칙을 설정할 수 있습니다. 이렇게 하면 인덱스, 외래 키 및 기타 제약 조건의 이름을 수동으로 지정하지 않아도 되므로 데이터베이스 구조를 예측 가능하고 일관되게 만들 수 있습니다.

새 프로젝트에서 이를 설정하려면 Alembic이 자동으로 원하는 명명 형식을 사용하도록 기본 클래스에 규칙을 추가하세요. 다음은 대부분의 경우에 잘 작동하는 규칙의 예입니다.

from sqlalchemy import MetaData
from sqlalchemy.orm import DeclarativeBase

convention = {
    'all_column_names': lambda constraint, table: '_'.join(
        [column.name for column in constraint.columns.values()]
    ),
    'ix': 'ix__%(table_name)s__%(all_column_names)s',
    'uq': 'uq__%(table_name)s__%(all_column_names)s',
    'ck': 'ck__%(table_name)s__%(constraint_name)s',
    'fk': 'fk__%(table_name)s__%(all_column_names)s__%(referred_table_name)s',
    'pk': 'pk__%(table_name)s',
}

class BaseModel(DeclarativeBase):
    metadata = MetaData(naming_convention=convention)

2. 날짜별로 마이그레이션 정렬

Alembic 마이그레이션 파일 이름은 일반적으로 개정 태그로 시작하므로 디렉터리의 마이그레이션 순서가 무작위로 나타날 수 있습니다. 때로는 시간순으로 정렬하는 것이 유용할 때도 있습니다.

Alembic을 사용하면 file_template 설정을 사용하여 alembic.ini 파일의 마이그레이션 파일 이름 템플릿을 사용자 정의할 수 있습니다. 마이그레이션을 체계적으로 유지하기 위한 두 가지 편리한 이름 지정 형식은 다음과 같습니다.

1. 날짜 기준:

file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(rev)s_%%(slug)s

1. Unix 타임스탬프 기준:

file_template = %%(epoch)d_%%(rev)s_%%(slug)s

파일 이름에 날짜 또는 Unix 타임스탬프를 사용하면 마이그레이션을 체계적으로 정리하여 탐색이 더 쉬워집니다. 저는 Unix 타임스탬프를 사용하는 것을 선호하며 다음 섹션에서 예시를 제공하겠습니다.

3. 테이블 및 마이그레이션에 대한 설명

팀으로 일하는 경우 속성에 댓글을 달는 것은 좋은 습관입니다. SQLAlchemy 모델을 사용하면 독스트링에 의존하는 대신 열과 테이블에 직접 주석을 추가하는 것이 좋습니다. 이렇게 하면 코드와 데이터베이스 모두에서 주석을 사용할 수 있으므로 DBA 또는 분석가가 테이블 및 필드 목적을 더 쉽게 이해할 수 있습니다.

class Event(BaseModel):
    __table_args__ = {'comment': 'System (service) event'}

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        primary_key=True,
        comment='Event ID - PK',
    )
    service_id: Mapped[int] = mapped_column(
        sa.Integer,
        sa.ForeignKey(
            f'{IntegrationServiceModel.__tablename__}.id',
            ondelete='CASCADE',
        ),
        nullable=False,
        comment='FK to integration service that owns the event',
    )
    name: Mapped[str] = mapped_column(
        sa.String(256), nullable=False, comment='Event name'
    )

파일 시스템에서 마이그레이션을 더 쉽게 찾을 수 있도록 마이그레이션에 설명을 추가하는 것도 도움이 됩니다. -m 를 사용하여 주석을 추가할 수 있습니다. 마이그레이션을 생성할 때. 주석은 독스트링과 파일 이름에 나타날 것입니다. 이 이름을 사용하면 필요한 마이그레이션을 훨씬 쉽게 찾을 수 있습니다.

from sqlalchemy import MetaData
from sqlalchemy.orm import DeclarativeBase

convention = {
    'all_column_names': lambda constraint, table: '_'.join(
        [column.name for column in constraint.columns.values()]
    ),
    'ix': 'ix__%(table_name)s__%(all_column_names)s',
    'uq': 'uq__%(table_name)s__%(all_column_names)s',
    'ck': 'ck__%(table_name)s__%(constraint_name)s',
    'fk': 'fk__%(table_name)s__%(all_column_names)s__%(referred_table_name)s',
    'pk': 'pk__%(table_name)s',
}

class BaseModel(DeclarativeBase):
    metadata = MetaData(naming_convention=convention)

4. 마이그레이션에서 모델 사용을 피하세요

모델은 한 테이블에서 다른 테이블로 데이터를 전송하거나 열 값을 수정하는 등 데이터 조작에 자주 사용됩니다. 그러나 마이그레이션에서 ORM 모델을 사용하면 마이그레이션이 생성된 후 모델이 변경되면 문제가 발생할 수 있습니다. 이러한 경우 데이터베이스 스키마가 더 이상 현재 모델과 일치하지 않을 수 있으므로 이전 모델 기반 마이그레이션이 실행될 때 중단됩니다.

코드 변경에 관계없이 올바른 실행을 보장하려면 마이그레이션이 정적이어야 하며 모델의 현재 상태와 독립적이어야 합니다. 다음은 데이터 조작에 모델을 사용하지 않는 두 가지 방법입니다.

• 데이터 조작에 원시 SQL 사용:

file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(rev)s_%%(slug)s

• 마이그레이션에서 직접 테이블 정의: 데이터 조작에 SQLAlchemy를 사용하려는 경우 마이그레이션에서 직접 테이블을 수동으로 정의할 수 있습니다. 이는 마이그레이션 실행 시 정적 스키마를 보장하며 모델 변경에 의존하지 않습니다.

file_template = %%(epoch)d_%%(rev)s_%%(slug)s

5. 마이그레이션 테스트를 위한 계단 테스트

Stairway 테스트에는 전체 마이그레이션 체인이 올바르게 작동하는지 확인하기 위해 업그레이드/다운그레이드 마이그레이션을 단계별로 점진적으로 테스트하는 작업이 포함됩니다. 이렇게 하면 각 마이그레이션이 문제 없이 처음부터 새 데이터베이스를 성공적으로 생성하고 다운그레이드할 수 있습니다. CI에 이 테스트를 추가하는 것은 팀에게 매우 중요하며 시간과 좌절감을 줄여줍니다.

테스트를 프로젝트에 통합하는 것은 쉽고 빠르게 수행할 수 있습니다. 이 저장소에서 코드 예제를 찾을 수 있습니다. 또한 도움이 될 수 있는 기타 중요한 마이그레이션 테스트도 포함되어 있습니다.

6. 마이그레이션 서비스

마이그레이션 수행을 위한 별도의 서비스입니다. 이는 마이그레이션을 수행하는 한 가지 방법일 뿐입니다. 로컬에서 개발하거나 개발과 유사한 환경에서 개발할 때 이 방법이 잘 맞습니다. 여기서 관련된 조건부 의존 기능에 대해 상기시켜 드리고 싶습니다. Alembic으로 애플리케이션 이미지를 가져와 별도의 컨테이너에서 실행합니다. 데이터베이스가 요청을 처리할 준비가 된 경우에만 마이그레이션이 시작된다는 조건으로 데이터베이스에 대한 종속성을 추가합니다(service_healthy). 또한 애플리케이션에 조건부 의존(service_completed_successically)을 추가하여 마이그레이션이 성공적으로 완료된 후에만 애플리케이션이 시작되도록 할 수 있습니다.

class Event(BaseModel):
    __table_args__ = {'comment': 'System (service) event'}

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        primary_key=True,
        comment='Event ID - PK',
    )
    service_id: Mapped[int] = mapped_column(
        sa.Integer,
        sa.ForeignKey(
            f'{IntegrationServiceModel.__tablename__}.id',
            ondelete='CASCADE',
        ),
        nullable=False,
        comment='FK to integration service that owns the event',
    )
    name: Mapped[str] = mapped_column(
        sa.String(256), nullable=False, comment='Event name'
    )

dependent_on 조건은 데이터베이스가 완전히 준비된 후에만 마이그레이션이 실행되고 마이그레이션이 완료된 후에 애플리케이션이 시작되도록 보장합니다.

7. 모델용 믹스인

이것은 당연한 사실이지만 간과하지 않는 것이 중요합니다. 믹스인을 사용하는 것은 코드 중복을 피하는 편리한 방법입니다. 믹스인은 자주 사용되는 필드와 메서드를 포함하는 클래스로, 필요한 모든 모델에 통합될 수 있습니다. 예를 들어, 레코드 생성 및 업데이트 시간을 추적하려면 Create_at 및 update_at 필드가 필요한 경우가 많습니다. 기본 키를 표준화하기 위해 UUID 기반 ID를 사용하는 것도 유용할 수 있습니다. 이 모든 것은 믹스인에 캡슐화될 수 있습니다.

from sqlalchemy import MetaData
from sqlalchemy.orm import DeclarativeBase

convention = {
    'all_column_names': lambda constraint, table: '_'.join(
        [column.name for column in constraint.columns.values()]
    ),
    'ix': 'ix__%(table_name)s__%(all_column_names)s',
    'uq': 'uq__%(table_name)s__%(all_column_names)s',
    'ck': 'ck__%(table_name)s__%(constraint_name)s',
    'fk': 'fk__%(table_name)s__%(all_column_names)s__%(referred_table_name)s',
    'pk': 'pk__%(table_name)s',
}

class BaseModel(DeclarativeBase):
    metadata = MetaData(naming_convention=convention)

이러한 믹스인을 추가하면 필요한 모든 모델에 UUID ID와 타임스탬프를 포함할 수 있습니다.

file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(rev)s_%%(slug)s

결론

마이그레이션을 처리하는 것은 어려울 수 있지만 이러한 간단한 방법을 따르면 프로젝트를 체계적으로 정리하고 관리하기 쉽게 유지하는 데 도움이 됩니다. 명명 규칙, 날짜 정렬, 주석 및 테스트를 통해 혼란을 피하고 실수를 방지하는 데 도움이 되었습니다. 이 기사가 도움이 되기를 바랍니다. 댓글로 여러분의 마이그레이션 팁을 자유롭게 공유해 주세요!

위 내용은 Alembic 및 SQLAlchemy 모범 사례의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!