Difyデータベースマイグレーション実践ガイド：Flask-Migrate運用とカラム変更事例

はじめに

Difyプロジェクトにおけるデータベース変更管理にはFlask-Migrateが標準で採用されています。本記事では、基本的なマイグレーション手順から具体的なテーブル修正事例まで、実際の運用フローを解説します。

---

基本コマンド一覧

# 変更検出＆マイグレーションスクリプト生成  
flask db migrate -m "alter_user_table"  

# 変更をデータベースに適用  
flask db upgrade  

# 現在のマイグレーション状態確認  
flask db current  

---

標準作業フロー

1. モデル定義の修正

models.py ファイルでデータベーススキーマを変更

# 例: カラム長の変更  
provider_name = db.Column(db.String(255), nullable=False)  # VARCHAR(255)に拡張  

2. マイグレーションスクリプト生成

flask db migrate -m "extend_provider_name_to_255_chars"  

→ migrations/versions 配下に新しいスクリプトが生成

3. スクリプト内容の確認

生成されたファイルで自動生成されたALTER文をチェック

# 生成されるコード例  
def upgrade():  
    with op.batch_alter_table('dataset_collection_bindings', schema=None) as batch_op:
        batch_op.alter_column('provider_name',
               existing_type=sa.VARCHAR(length=40),
               type_=sa.String(length=255),
               existing_nullable=False) 

4. 変更の適用

flask db upgrade  

5. 変更のバージョン管理

git add migrations/versions/[生成されたファイル名]  
git commit -m "db: extend provider_name column length"  

---

本番環境での適用

デプロイ時にコミット済みの変更を反映:

flask db upgrade  

---

重要ポイント

✅ 必須チェック項目

1. 自動生成スクリプトのSQL文は必ず目視確認
2. 開発/ステージング環境でテスト後に本番適用
3. 複数環境で作業する場合はmigrationsフォルダの同期を厳守

---

まとめ

Flask-Migrateを活用することで：

• データベース変更のバージョン管理が可能
• チームメンバー間のスキーマ不一致を防止
• ロールバック時の安全な復旧手順を提供

「モデル修正 → スクリプト生成 → テスト環境適用 → 本番反映」のフローを厳守し、データベース構造変更の安全性を確保しましょう。