English | 日本語

Database Migration Guide¶

AccelMCP は Flask-Migrate (Alembic)を使用してデータベースマイグレーションを管理しています。

マイグレーションファイルはdb/migrations/ディレクトリに配置されます。

ディレクトリ構成¶

db/
├── migrate.py              # マイグレーション管理スクリプト
└── migrations/             # Alembicポイント
    ├── alembic.ini          # Alembic設定
    ├── env.py               # マイグレーション環境設定
    ├── script.py.mako       # マイグレーションテンプレート
    └── versions/            # マイグレーションファイル

セットアップ¶

初回セットアップ¶

依存関係のインストール

pip install -r requirements.txt

マイグレーションの適用
```
python db/migrate.py upgrade
```

マイグレーションコマンド¶

新しいマイグレーションを作成¶

python db/migrate.py migrate "Description of changes"

マイグレーションを適用（アップグレード）¶

python db/migrate.py upgrade

マイグレーションをロールバック（ダウングレード）¶

python db/migrate.py downgrade

現在のリビジョンを確認¶

python db/migrate.py current

マイグレーション履歴を表示¶

python db/migrate.py history

Docker での使用¶

初回起動¶

docker compose up -d

コンテナ起動時に自動的にpython db/migrate.py upgradeが実行されます。

新しいマイグレーションを作成（ローカル環境で）¶

# ローカルでモデルを変更後
python db/migrate.py migrate "Add new field"

# マイグレーションファイルを確認
git add db/migrations/versions/
git commit -m "Add migration: Add new field"

# コンテナを再起動してマイグレーション適用
docker compose restart web

マイグレーションのロールバック¶

docker compose exec web python db/migrate.py downgrade

サービステンプレートの追加¶

サービステンプレートはapp/utils/template_loader.pyのBUILTIN_TEMPLATESで管理されます。

新しいテンプレートの追加手順¶

app/utils/template_loader.pyを編集

BUILTIN_TEMPLATESリストに新しいテンプレートを追加：

BUILTIN_TEMPLATES = [
    # ... 既存のテンプレート ...
    {
        'name': 'MS Office API',
        'service_type': 'api',
        'description': 'Microsoft Office API for document management',
        'icon': '📄',
        'category': 'Productivity',
        'capabilities': [
            {
                'name': 'list_documents',
                'capability_type': 'tool',
                'url': 'https://graph.microsoft.com/v1.0/me/drive/root/children',
                'headers': {'Authorization': 'Bearer YOUR_MS_TOKEN'},
                'body_params': {},
                'description': 'List all documents'
            }
        ]
    }
]

マイグレーションを作成

python db/migrate.py migrate "Add MS Office template"

マイグレーションファイルを編集（必要に応じて）

生成されたマイグレーションファイルにデータロード処理を追加：

from app.utils.template_loader import load_service_templates

def upgrade():
    # テンプレートをロード
    load_service_templates()

def downgrade():
    # ロールバック処理
    op.execute("""
        DELETE FROM mcp_capability_templates
        WHERE service_template_id IN (
            SELECT id FROM mcp_service_templates
            WHERE name = 'MS Office API'
        )
    """)
    op.execute("""
        DELETE FROM mcp_service_templates
        WHERE name = 'MS Office API'
    """)

マイグレーションを適用

python db/migrate.py upgrade

トラブルシューティング¶

データベースをリセットしたい¶

docker compose down -v  # ボリュームを削除
docker compose up -d    # 再起動してマイグレーション適用

マイグレーション履歴が壊れた場合¶

# データベースに直接接続
docker compose exec db mysql -u mcpuser -p mcpdb

# alembic_versionテーブルを確認
SELECT * FROM alembic_version;

# 必要に応じてリセット
DELETE FROM alembic_version;

マイグレーションファイルの競合¶

# マイグレーションを統合
python db/migrate.py merge heads -m "Merge migrations"

ベストプラクティス¶

モデル変更後は必ずマイグレーションを作成
app/models/models.pyを変更したらpython db/migrate.py migrateを実行
マイグレーションファイルをレビュー
自動生成されたマイグレーションファイルを確認
必要に応じて手動で調整
本番環境でのマイグレーション
必ずバックアップを取得
ステージング環境でテスト
ダウンタイムを考慮
チーム開発
マイグレーションファイルは Git で管理
プルリクエストに含める
マージ後は全員が upgrade を実行