Database Migration Commands

The Database migration commands provide an easy way to manage your database schema changes using Alembic.

Basic Usage

fastapi-admin db makemigrations -m "initial migration"
fastapi-admin db migrate

This will create and apply migrations to your database based on your SQLModel models.

Available Commands

Command	Description
makemigrations	Create new database migrations
migrate	Apply pending database migrations
shell	Open a shell in the API container
env_check	Check for missing environment variables

Command Details

Makemigrations

Creates new database migration files based on detected changes in your SQLModel models.

fastapi-admin db makemigrations -m "message"

Options:

Option	Short	Description
--message	-m	Message describing the migration (default: "init")

This command will:

1. Detect changes in your SQLModel models
2. Generate migration files in the migrations/versions directory
3. Each migration file contains upgrade and downgrade functions

Migrate

Applies all pending database migrations to bring your database schema up to date.

fastapi-admin db migrate

This command will:

1. Run all pending migrations in sequence
2. Apply schema changes to your database
3. Update the Alembic version table to track applied migrations

Shell

Opens a shell in the API Docker container for direct access to the environment.

fastapi-admin db shell

This shell allows you to:

1. Run Python code with access to your models and environment
2. Execute direct Alembic commands for advanced operations
3. Access the database directly

Example shell usage:

# Once in the shell
alembic current      # Show current migration version
alembic history      # Show migration history
alembic downgrade -1 # Downgrade one version

How It Works

The migration commands work through the following process:

1. Model Detection:
2. Migrations scan the models defined in app/core/main_models.py

3. All imported SQLModel classes are detected for changes

4. Migration Storage:

5. Migration files are stored in migrations/versions/

6. Each migration is tracked with a unique revision ID

7. Docker Integration:

8. Commands run through Docker Compose to ensure consistent environments
9. Uses the API container defined in your docker-compose.yml

Common Issues

• Model Not Found: Ensure models are imported in app/core/main_models.py
• Migration Conflicts: If multiple developers create migrations, merge them carefully
• Failed Migrations: Use the shell to downgrade to a previous version
• Empty Migrations: No changes detected in models since last migration
• Database Connection Issues: Check database URL in settings or environment variables

Troubleshooting

If you encounter issues with migration commands:

1. Migration Creation Failed:
2. Ensure all models are properly imported in main_models.py
3. Check for syntax errors in your model definitions

4. Verify database connection settings

5. Migration Application Failed:

6. Check the migration files for complex operations that might fail
7. Look at database logs for specific SQL errors

8. Try running specific migrations directly in the shell

9. No Changes Detected:

10. Confirm your model changes are in the right files

11. Make sure changes are significant (adding fields, changing types, etc.)

12. Advanced Fixes:

13. Use the shell to run specific Alembic commands
14. Check Alembic's current version with alembic current
15. Execute SQL directly if needed for complex situations
16. Use fastapi-admin shell to access the container's environment

Best Practices

1. Meaningful Messages: Use descriptive -m messages for each migration
2. Regular Migrations: Create small, focused migrations rather than large changes
3. Test Migrations: Always test migrations in development before production
4. Version Control: Commit migration files to your version control system
5. Database Backups: Always backup your database before applying migrations in production

For more information on Alembic and SQLModel, refer to their official documentation.