Flask-SQLAlchemyでのマイグレーション

Flask-SQLAlchemy での DB のマイグレーション

SQLAlchemy は、Python でポピュラーに使用されている ORM ライブラリの 1 つです。
ORM（Object-Relational Mapping）とは、SQL 文を直接記述するのではなく、オブジェクトを扱うようにデータベースを扱うことができる機能のことです。つまり、オブジェクト志向言語のオブジェクトを、そうでないもの（PostgreSQL のような Relational Database）に変換するためのモジュールになります。

SQLAlchemy は、SQLite、Postgresql、MySQL、Oracle などさまざまな SQL エンジンに対応しています。

Flask に SQLAlchemy の機能を追加したライブラリが Flask SQLAlchemy で、Flask を用いて API として DB の情報を扱うことができます。

Flask-Migrate は、Alembic というマイグレーションツールを使って、SQL Alchemy によるデータベースマイグレーションを扱うための Extension です。通常イメージするデータベース間の「移行」ではなく、Python 上のモデルから、実際のデータベースへの「変換」を行うモジュールとなります。このモジュールを使うと、モデル設計 → 実際のデータベース構成の変換が自動で実行され、さらに履歴も管理することができます。

マイグレーション

下準備

以下の app.py ファイルを用意して、データベースのマイグレーションを行ってみます。 sqlite データベースに、User というテーブルを作ります。


#!app.py

from flask import Flask
import os
from datetime import datetime
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

# 実行されるファイル(test_flask-migrate.py)の置き場所をbasedirに保存
basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
# データベースファイルは実行ファイルと同じ場所にapp.dbという名前で作成
app.config['SQLALCHEMY_DATABASE_URI'] ='sqlite:///' + os.path.join(basedir, 'app.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)
# migrateインスタンスを定義
migrate = Migrate(app, db)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(64), index=True, unique=True)
    email = db.Column(db.String(120), index=True, unique=True)
    password_hash = db.Column(db.String(128))

    # この関数は、インタープリタ(コンソール)からこのクラス(からできたインスタンス)を読んだ際に、どのように表示されるかを定義している。ここではusernameを表示させている。
    def __repr__(self):
        return '<User {}>'.format(self.username)

マイグレーションレポジトリの作成

Flask-Migrate は、flask db xx という flask のサブコマンドで操作します。
マイグレーションのリポジトリの作成のために、まずは、ターミナルから、flask db init を実行します。

このコマンドを実行することで、ルートディレクトリに migration というフォルダが作成されます。


$ flask db init
  Creating directory /home/xxxx/flask_db_test/migrations ...  done
  Creating directory /home/xxxx/flask_db_test/migrations/versions ...  done
  Generating /home/xxxx/flask_db_test/migrations/script.py.mako ...  done
  Generating /home/xxxx/flask_db_test/migrations/env.py ...  done
  Generating /home/xxxx/flask_db_test/migrations/alembic.ini ...  done
  Generating /home/xxxx/flask_db_test/migrations/README ...  done
  Please edit configuration/connection/logging settings in '/home/home/xxxx/flask_db_test/migrations/alembic.ini' before proceeding.

マイグレーションの実施

次に、flask db migrate を実行し、マイグレーション用のスクリプトを生成します。マイグレーションには automatic と manual の 2 種類があり、automatic の場合、Python 上でモデルに定義された形と、実際の DB のスキーマを Alembic が比較して、必要な差分を埋めるスクリプトを生成します。今回の場合、元のデータベースが存在しないので、データベース自体と User テーブルを生成するスクリプトが作成されます。


$ flask db migrate
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.autogenerate.compare] Detected added table 'user'
INFO  [alembic.autogenerate.compare] Detected added index 'ix_user_email' on '['email']'
INFO  [alembic.autogenerate.compare] Detected added index 'ix_user_username' on '['username']'
INFO  [alembic.autogenerate.compare] Detected removed table 'User'
  Generating /home/dejima/hakky/pig-eye-api-old/flask_db_test/migrations/versions/befa50e57033_.py ...  done

この時点で、migration\versionsフォルダに、befa50e57033_.py というファイルが作成されます。これが実際の SQL 操作を実行するスクリプトです。ファイル名はバージョンを表しており、バージョン管理されていることが分かります。また、-m というオプションで、git のコミットのように、バージョンに対してコメントを付けることができます。

スクリプトの中は以下のように記載されており、「この変更をどのように実施するか（Upgrade）」と「どのように切り戻すか」（Downgrade）の 2 つが用意されています。


# befa50e57033_.py

"""empty message

Revision ID: befaxxxx33
Revises:
Create Date: xxxx-xx-xx xx:xx:xxxxx

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = 'befa******'
down_revision = None
branch_labels = None
depends_on = None


def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('user',
    sa.Column('id', sa.Integer(), nullable=False),
    sa.Column('username', sa.String(length=64), nullable=True),
    sa.Column('email', sa.String(length=120), nullable=True),
    sa.Column('password_hash', sa.String(length=128), nullable=True),
    sa.PrimaryKeyConstraint('id')
    )
    op.create_index(op.f('ix_user_email'), 'user', ['email'], unique=True)
    op.create_index(op.f('ix_user_username'), 'user', ['username'], unique=True)
    op.drop_table('User')
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('User',
    sa.Column('id', sa.TEXT(), nullable=True),
    sa.Column('username', sa.TEXT(), nullable=True),
    sa.Column('email', sa.TEXT(), nullable=True),
    sa.Column('password_hash', sa.TEXT(), nullable=True)
    )
    op.drop_index(op.f('ix_user_username'), table_name='user')
    op.drop_index(op.f('ix_user_email'), table_name='user')
    op.drop_table('user')
    # ### end Alembic commands ###

履歴は以下のように、flask db history コマンドで確認できます。


$ flask db history
<base> -> befa50e57033 (head), empty message

マイグレーションの実行

最後に、flask db upgrade コマンドを実行して、upgrade の内容(Userテーブル作成)を実行します。


$ flask db upgrade
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> befa50e57033, empty message

データベースにテーブルができているか、確認してみます。


$ python
>>> from app import db
>>> db.get_tables_for_bind()
[Table('user', MetaData(), Column('id', Integer(), table=<user>, primary_key=True, nullable=False), Column('username', String(length=64), table=<user>), Column('email', String(length=120), table=<user>), Column('password_hash', String(length=128), table=<user>), schema=None)]

app.py ファイルで定義した class User(db.Model) モデルでテーブルができていることが確認できます。

マイグレーションの運用

実際の運用では、DB の内容を削除しないで、モデルの変更をしたいときがあります。いくつかのユースケースでその手順お示します。

全く新しいデータベースを作るとき

migrations フォルダを削除します。
データベースを作り直します。
マイグレーションを実行します。


$ flask db init
$ flask db migrate
$ flask db upgrade

データベースのカラムを追加するとき

モデルの修正をします。
マイグレーションを実行し、データベースを更新します。


$ flask db migrate
$ flask db upgrade

データベースのカラム名を変更するとき（制約や外部参照あり）

モデルの変更の基本は、モデルファイルを編集 → flask db migrate 実行の順でマイグレーションができますが、外部参照や NOT NULL 制約等がある場合のカラム名変更には、工夫が必要です。

カラム名変更の場合、マイグレーションで行っていることは、実際にはカラム名の変更ではなく、カラムの新設と削除です。

例えば、カラム名 author_id → user_id の変更時は、まずカラム user_id を作成し、カラム author_id を削除しています。

したがって、すでにレコードが存在する場合、author_id は外部参照しているため、そもそも削除できません。また、同様に NOT NULL 制約があるカラムも同様に削除できません。

そこで、以下の手順でカラム名の変更をします。

まず、空 revision ファイルを生成します。


$ flask db revision

以下のような revision ファイルが生成されます。


"""empty message

Revision ID: **********
Revises: cd987xxxxxx
Create Date: xxxx-xx-xx xx:xx:xxxxx

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = '3f50a23df63f'
down_revision = 'cd987b7bd79f'
branch_labels = None
depends_on = None


def upgrade():
    pass


def downgrade():
    pass

この空 revision ファイルを編集してカラム名の変更を行うようにします。


def upgrade():
- pass
+ op.alter_column('user', column_name='author_id', existing_type=sa.Integer, new_column_name='user_id')

def downgrade():
- pass
+ op.alter_column('user', column_name='user_id', existing_type=sa.Integer, new_column_name='author_id')

マイグレーションを実行します。


$ flask db upgrade

モデルを変更します。
もう一度、空 revision ファイルを生成して、index 名を変更します。


$ flask db revision

以下のように、SQL 文にて index 名を変更します。


def upgrade():
-    pass
+    op.execute("ALTER TABLE User RENAME INDEX author_id to user_id")


def downgrade():
-    pass
+    op.execute("ALTER TABLE User RENAME INDEX user_id to author_id")

最後にもう一度マイグレーションをします。


$ flask db upgrade

データベースのカラム名を変更するとき（制約や外部参照なし）

基本的に、前出のカラム名変更の手順と同じです。
ただし、最後の index の変更は不要です。

参考

備考

Hakky ではエンジニアを募集中です！まずは話してみたいなどでも構いませんので、ぜひお気軽に採用ページからお問い合わせくださいませ。