Alembic Integration
Framefox provides theAlembicManager class to simplify migration operations:
framefox/core/orm/migration/alembic_manager.py:22
Initial Setup
TheAlembicManager automatically sets up the necessary directories and configuration:
migrations/- Main migrations directorymigrations/versions/- Individual migration filesmigrations/script.py.mako- Template for new migrations
framefox/core/orm/migration/alembic_manager.py:42framefox/core/orm/migration/alembic_manager.py:54
Creating Migrations
Auto-generate Migrations
The recommended way is to auto-generate migrations based on model changes:framefox/core/orm/migration/alembic_manager.py:95
Manual Migrations
Create an empty migration file for manual changes:Migration Workflow
- Make model changes in your entity classes:
- Generate migration:
- Review the generated file in
migrations/versions/:
Running Migrations
Upgrade to Latest
Apply all pending migrations:framefox/core/orm/migration/alembic_manager.py:109
Upgrade to Specific Revision
Apply migrations up to a specific version:Downgrade (Rollback)
Revert migrations to a previous state:framefox/core/orm/migration/alembic_manager.py:133
Migration Management
Check Migration Status
Get the current migration version from the database:List Migrations
Get all existing migration files:framefox/core/orm/migration/alembic_manager.py:145
View Migration Content
Read the content of a specific migration:framefox/core/orm/migration/alembic_manager.py:151
Check for Changes
Determine if a migration contains actual changes:framefox/core/orm/migration/alembic_manager.py:159
Delete Migration
Remove a migration file:framefox/core/orm/migration/alembic_manager.py:163
Database URL Configuration
TheAlembicManager reads database configuration from your settings:
framefox/core/orm/migration/alembic_manager.py:79
Database URL Examples
Advanced Operations
Initialize Alembic Version Table
Create thealembic_version table manually:
framefox/core/orm/migration/alembic_manager.py:171
Clear Version History
Reset the migration tracking table:framefox/core/orm/migration/alembic_manager.py:243
Clean Up Migrations
Remove all migration files (preserves templates):framefox/core/orm/migration/alembic_manager.py:210
Complete Reset
Clear both migration files and database version table:framefox/core/orm/migration/alembic_manager.py:276
Common Migration Scenarios
Add a Column
Remove a Column
Rename a Column
Add an Index
Add a Foreign Key
Create a Table
Best Practices
- Always review auto-generated migrations: Check for correctness before applying
- Write descriptive migration messages: Use clear names like “Add user email verification”
- Test migrations in development first: Never run untested migrations in production
- Implement downgrade functions: Always provide a way to rollback changes
- Keep migrations small: One logical change per migration
- Backup before migrating: Always backup production databases before migrations
- Version control migrations: Commit migration files to your repository
- Don’t modify applied migrations: Create new migrations for changes
CLI Integration
Create a management command for migrations:Next Steps
Entities
Define your database models
Repositories
Work with data access layers