【FastAPI＋MySQL】alembicでマイグレーションファイルを自動生成して実行する

はじめに

alembicはSQLAlchemyの著者によって作成されたデータベースマイグレーションツールです。PythonのWebフレームワークであるFastAPIがDBのマイグレーションの仕組みを持っていないため、DBのマイグレーションをするためにalembicを使います。
alembicはマイグレーションファイルを自分で書く方法のほかに、テーブル定義の変更を自動で読み取ってマイグレーションファイルを自動生成することができます。とても便利な機能なのですが、実際にやってみようとしたところ苦戦したので、備忘録として残しておきます。

環境

• MySQL 5.7
• Python 3.9.13
  • alembic 1.8.1
  • fastapi 0.79.0
  • PyMySQL 1.0.2
  • SQLAlchemy 1.4.39
  • uvicorn 0.18.2

ディレクトリ構成

alembicに関係があるところだけ抜粋しています。

app
├── db
│   ├── versions
│   ├── alembic.ini
│   ├── env.py
│   └── script.py.mako
├── models
│   ├── foo.py
│   ├── bar.py
├── database.py
└── main.py

手順

準備

modelsディレクトリにsqlalchemyによるテーブル定義を記載しておきます。

foo.py

from sqlalchemy import Integer
from database import Base


class Foo(Base):
    __tablename__ = "foos"

    id = Column(Integer, primary_key=True)

bar.py

from sqlalchemy import Integer
from database import Base


class Bar(Base):
    __tablename__ = "bars"

    id = Column(Integer, primary_key=True)

sqlalchemyの接続設定も記載しておきます。
DATABASE,USER,PASSWORD,HOST,PORT,DB_NAMEは環境に応じて書き換えておきます。

database.py

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE = "mysql+pymysql"
USER = "root"
PASSWORD = "root-password"
HOST = "host"
PORT = "3306"
DB_NAME = "test"

DATABASE_URL = "{}://{}:{}@{}:{}/{}".format(
    DATABASE, USER, PASSWORD, HOST, PORT, DB_NAME
)

Engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=Engine)

Base = declarative_base()

パッケージインストール

alembicをインストールします。今回はMySQLのドライバーにPyMySQLを使うため、同時にインストールしておきます。

$ pip install alembic PyMySQL

alembicセットアップ

dbディレクトリに移動してセットアップを実行します。alembic.ini、env.pyなどが生成されます。

$ cd db
$ alembic init .

alembic.ini修正

sqlalchemy.urlを環境に応じて書き換えます。sqlalchemy.urlをコメントアウトしてenv.pyで定義している記事も見かけたのですが、今回はやっていません。

sqlalchemy.url = mysql+pymysql://root:root-password@host:port/database

sqlalchemy.urlの全体はこちら。

alembic.ini

# A generic, single database configuration.

[alembic]
# path to migration scripts
script_location = .

# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
# Uncomment the line below if you want the files to be prepended with date and time
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
# for all available tokens
# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s

# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory.
prepend_sys_path = .

# timezone to use when rendering the date within the migration file
# as well as the filename.
# If specified, requires the python-dateutil library that can be
# installed by adding `alembic[tz]` to the pip requirements
# string value is passed to dateutil.tz.gettz()
# leave blank for localtime
# timezone =

# max length of characters to apply to the
# "slug" field
# truncate_slug_length = 40

# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false

# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false

# version location specification; This defaults
# to ./versions.  When using multiple version
# directories, initial revisions must be specified with --version-path.
# The path separator used here should be the separator specified by "version_path_separator" below.
# version_locations = %(here)s/bar:%(here)s/bat:./versions

# version path separator; As mentioned above, this is the character used to split
# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
# Valid values for version_path_separator are:
#
# version_path_separator = :
# version_path_separator = ;
# version_path_separator = space
version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.

# the output encoding used when revision files
# are written from script.py.mako
# output_encoding = utf-8

# 修正
sqlalchemy.url = mysql+pymysql://root:root-password@host:port/database


[post_write_hooks]
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts.  See the documentation for further
# detail and examples

# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -l 79 REVISION_SCRIPT_FILENAME

# Logging configuration
[loggers]
keys = root,sqlalchemy,alembic

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = WARN
handlers = console
qualname =

[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine

[logger_alembic]
level = INFO
handlers =
qualname = alembic

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S

env.py修正

まず、Base = declarative_base()が記載されているdatabaseパッケージをimportして、target_metadataに代入しておきます。

import database
target_metadata = database.Base.metadata

次に、Baseを継承して記載したmodelsディレクトリ以下のテーブル定義をimportします。

import models.foo
import models.bar

使わないのですが、importする必要があるので注意が必要です。詳細は下記のstackoverflowを確認頂きたいのですが、alembicがテーブル定義の変更を読み取れるようにするために、importしておく必要があるみたいです。

https://stackoverflow.com/questions/48053955/alembic-migrations-on-multiple-models

flake8でunusedの警告が出てしまうので、無視する設定を追加しておきます。

import models.foo  # noqa: F401
import models.bar  # noqa: F401

env.pyの全体はこちらです。
run_migrations_online()が通常のマイグレーション実行時に使われる関数で、run_migrations_offline()は--sqlオプションをつけたときに使われる関数です。

env.py

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool

from alembic import context

# 修正
import models.foo  # noqa: F401
import models.bar  # noqa: F401
import database

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
# 修正
target_metadata = database.Base.metadata
# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(connection=connection, target_metadata=target_metadata)

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

マイグレーションファイル生成

--autogenerateオプションをつけて実行することで、alembicがテーブル定義の変更を読み取って、マイグレーションファイルが生成されます。なお、alembicが読み取れない変更もあるため、注意が必要です。詳細は公式ドキュメントでご確認下さい。

alembic revision --autogenerate

マイグレーション実行

マイグレーションの実行方法はマイグレーションファイルを自分で書いたときと同じです。

alembic upgrade head