Framefox provides a comprehensive set of database commands for managing your database schema and migrations using Alembic.
Available Commands Core Commands
create Create the database
create-migration Generate a new migration file
upgrade Apply pending migrations
downgrade Revert migrations
status Check migration status
Utility Commands
diagram Generate database diagram
clear-migration Clear migration files
clear-metadata Clear metadata cache
Common Workflows Initial Database Setup # 1. Create the database framefox database:create # 2. Create initial migration framefox database:create-migration # 3. Apply migrations framefox database:upgrade # 4. Check status framefox database:status
Adding New Entity # 1. Create entity framefox create:entity product # 2. Generate migration framefox database:create-migration # 3. Apply migration framefox database:upgrade
Modifying Existing Entity # 1. Update entity code # Edit src/entity/user.py # 2. Create migration framefox database:create-migration # 3. Review generated migration # Check migrations/versions/*.py # 4. Apply migration framefox database:upgrade
database:create Creates the database if it doesn’t exist.
Output: ✓ Database created successfully
database:create-migration Generates a new migration file by comparing your entities to the current database schema.
framefox database:create-migration
Features:
Auto-detects schema changes
Generates timestamped migration files
Creates Alembic version table if needed
Validates changes before creating file
Output: Migration file '20240115_143025_migration.py' created successfully. You can now run the 'framefox database upgrade' command to apply the updates.
Example Migration File: """20240115_143025_migration Revision ID: 1a2b3c4d5e6f Revises: Create Date: 2024-01-15 14:30:25.123456 """ from alembic import op import sqlalchemy as sa # revision identifiers revision = '1a2b3c4d5e6f' down_revision = None branch_labels = None depends_on = None def upgrade (): op.create_table( 'user' , sa.Column( 'id' , sa.Integer(), autoincrement = True , nullable = False ), sa.Column( 'username' , sa.String( length = 100 ), nullable = False ), sa.Column( 'email' , sa.String( length = 255 ), nullable = False ), sa.Column( 'created_at' , sa.DateTime(), nullable = False ), sa.PrimaryKeyConstraint( 'id' ), sa.UniqueConstraint( 'username' ), sa.UniqueConstraint( 'email' ) ) def downgrade (): op.drop_table( 'user' )
database:upgrade Applies all pending migrations to the database.
framefox database:upgrade
Output: Applying migrations... Migrations applied successfully. You can use framefox database downgrade to undo the migrations if necessary.
When No Changes: The database is already up to date, no migrations to apply.
database:downgrade Reverts the last migration(s) applied to the database.
# Revert last migration framefox database:downgrade # Revert last 3 migrations framefox database:downgrade --steps 3 # Revert all migrations framefox database:downgrade --steps 0
Arguments: Number of migrations to revert. Use 0 to revert all.
Output: Reverting 1 migration... Successfully reverted 1 migration.
database:status Displays the current status of your database and migrations.
Output: Database Status ┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓ ┃ Component ┃ Status ┃ Details ┃ ┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩ │ Database │ Exists │ framefox │ │ Connection │ Established│ OK │ │ Type │ SQLITE │ localhost:0 │ └────────────┴────────────┴────────────────────┘ Migration Status ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ ┃ Version ┃ Description ┃ Status ┃ ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │ 1a2b3c4d5e6f │ 20240115_143025 │ CURRENT │ └──────────────┴───────────────────────┴─────────┘ ✓ The database is up to date
database:drop Drops the database.
This permanently deletes all data. Use with caution!
database:diagram Generates a visual diagram of your database schema.
framefox database:diagram
Creates an ERD (Entity Relationship Diagram) showing tables, columns, and relationships.
database:clear-migration Clears all migration files.
framefox database:clear-migration
This removes migration history. Only use when starting fresh.
Clears the database metadata cache.
framefox database:clear-metadata
Useful when encountering metadata-related issues.
database:copy Copies a database to another location.
Configuration Database settings are in config/orm.yaml and .env:
# config/orm.yaml database : url : ${DATABASE_URL} echo : false pool_size : 5
# .env DATABASE_URL=sqlite:///./framefox.db # or DATABASE_URL=postgresql://user:pass@localhost/dbname # or DATABASE_URL=mysql://user:pass@localhost/dbname
Migration Best Practices
Review Migrations - Always check generated migration files before applyingTest Migrations - Test on development database firstBackup Data - Backup production data before migratingVersion Control - Commit migrations to gitSequential Application - Apply migrations in orderDon’t Edit - Don’t edit applied migrationsUse Downgrade - Implement downgrade functions Troubleshooting No Changes Detected If create-migration says “No changes detected”:
Ensure entities are imported in migrations/env.py
Verify entity changes are saved
Check that Base metadata is configured correctly
Migration Conflicts If you have conflicting migrations:
# Check status framefox database:status # Revert problematic migration framefox database:downgrade # Clear and recreate framefox database:clear-migration framefox database:create-migration
Connection Errors Verify database URL:
framefox debug:config | grep DATABASE_URL
Supported Databases Framefox supports:
SQLite - Default, file-basedPostgreSQL - Production-readyMySQL/MariaDB - Production-ready
Next Steps
Create Entity Generate database entities
ORM Guide Learn about the ORM