Database Migration Guide¶

AccelMCP uses Flask-Migrate (Alembic) for database migration management.

Migration files are located in the db/migrations/ directory.

Directory Structure¶

db/
├── migrate.py              # Migration management script
└── migrations/             # Alembic directory
    ├── alembic.ini          # Alembic configuration
    ├── env.py               # Migration environment settings
    ├── script.py.mako       # Migration template
    └── versions/            # Migration files

Setup¶

Initial Setup¶

Install dependencies

pip install -r requirements.txt

Apply migrations
```
python db/migrate.py upgrade
```

Migration Commands¶

Create a new migration¶

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

Apply migrations (upgrade)¶

python db/migrate.py upgrade

Roll back migrations (downgrade)¶

python db/migrate.py downgrade

Check current revision¶

python db/migrate.py current

Show migration history¶

python db/migrate.py history

Using with Docker¶

Initial startup¶

docker compose up -d

python db/migrate.py upgrade is automatically executed when the container starts.

Create a new migration (in local environment)¶

# After modifying models locally
python db/migrate.py migrate "Add new field"

# Review the migration file
git add db/migrations/versions/
git commit -m "Add migration: Add new field"

# Restart the container to apply the migration
docker compose restart web

Roll back a migration¶

docker compose exec web python db/migrate.py downgrade

Adding Service Templates¶

Service templates are managed in BUILTIN_TEMPLATES within app/utils/template_loader.py.

Steps to add a new template¶

Edit app/utils/template_loader.py

Add a new template to the BUILTIN_TEMPLATES list:

BUILTIN_TEMPLATES = [
    # ... existing 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'
            }
        ]
    }
]

Create a migration

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

Edit the migration file (if needed)

Add data loading logic to the generated migration file:

from app.utils.template_loader import load_service_templates

def upgrade():
    # Load templates
    load_service_templates()

def downgrade():
    # Rollback logic
    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'
    """)

Apply the migration

python db/migrate.py upgrade

Troubleshooting¶

Resetting the database¶

docker compose down -v  # Delete volumes
docker compose up -d    # Restart and apply migrations

When migration history is corrupted¶

# Connect to the database directly
docker compose exec db mysql -u mcpuser -p mcpdb

# Check the alembic_version table
SELECT * FROM alembic_version;

# Reset if necessary
DELETE FROM alembic_version;

Migration file conflicts¶

# Merge migrations
python db/migrate.py merge heads -m "Merge migrations"

Best Practices¶

Always create a migration after changing a model
After modifying app/models/models.py, run python db/migrate.py migrate
Review migration files
Check the auto-generated migration file
Adjust manually as needed
Migrations in production
Always take a backup first
Test on a staging environment
Plan for potential downtime
Team development
Manage migration files in Git
Include them in pull requests
After merging, everyone must run upgrade