autoworkflow 3.1.5 → 3.6.0

package/.claude/skills/alembic.md

@@ -0,0 +1,504 @@
+# Alembic Skill
+
+## Initial Setup
+\`\`\`bash
+# Initialize Alembic in project
+alembic init alembic
+
+# Or for async SQLAlchemy
+alembic init -t async alembic
+\`\`\`
+
+## Project Structure
+\`\`\`
+project/
+├── alembic/
+│   ├── versions/           # Migration files
+│   ├── env.py              # Migration environment
+│   ├── script.py.mako      # Migration template
+│   └── README
+├── alembic.ini             # Alembic config
+└── app/
+    └── models.py           # SQLAlchemy models
+\`\`\`
+
+## alembic.ini Configuration
+\`\`\`ini
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+version_path_separator = os
+
+# Use environment variable for database URL (don't commit credentials!)
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+[post_write_hooks]
+hooks = black
+black.type = console_scripts
+black.entrypoint = black
+black.options = -q
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+\`\`\`
+
+## env.py - Standard Configuration
+\`\`\`python
+# alembic/env.py
+import os
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config, pool
+from alembic import context
+
+# Import your models' Base
+from app.models import Base
+
+config = context.config
+
+# Override sqlalchemy.url from environment variable
+config.set_main_option(
+    "sqlalchemy.url",
+    os.environ.get("DATABASE_URL", "postgresql://localhost/mydb")
+)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode (SQL script generation)."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode (direct database connection)."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
+\`\`\`
+
+## env.py - Async Configuration
+\`\`\`python
+# alembic/env.py (async version)
+import asyncio
+import os
+from logging.config import fileConfig
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+from alembic import context
+
+from app.models import Base
+
+config = context.config
+config.set_main_option(
+    "sqlalchemy.url",
+    os.environ.get("DATABASE_URL", "postgresql+asyncpg://localhost/mydb")
+)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
+\`\`\`
+
+## Common Migration Commands
+\`\`\`bash
+# Create auto-generated migration
+alembic revision --autogenerate -m "Add users table"
+
+# Create empty migration (for data migrations)
+alembic revision -m "Populate default categories"
+
+# Apply all pending migrations
+alembic upgrade head
+
+# Apply specific number of migrations
+alembic upgrade +2
+
+# Rollback one migration
+alembic downgrade -1
+
+# Rollback to specific revision
+alembic downgrade abc123
+
+# Rollback all migrations
+alembic downgrade base
+
+# Show current revision
+alembic current
+
+# Show migration history
+alembic history --verbose
+
+# Show pending migrations
+alembic history -r current:head
+
+# Generate SQL instead of applying
+alembic upgrade head --sql > migration.sql
+\`\`\`
+
+## Schema Migration Example
+\`\`\`python
+"""Add users table
+
+Revision ID: abc123
+Revises:
+Create Date: 2024-01-15 10:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'abc123'
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'users',
+        sa.Column('id', sa.Integer(), primary_key=True),
+        sa.Column('email', sa.String(255), nullable=False, unique=True),
+        sa.Column('password_hash', sa.String(255), nullable=False),
+        sa.Column('is_active', sa.Boolean(), server_default='true'),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_users_email', 'users', ['email'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_users_email', table_name='users')
+    op.drop_table('users')
+\`\`\`
+
+## Data Migration Example
+\`\`\`python
+"""Populate default categories
+
+Revision ID: def456
+Revises: abc123
+Create Date: 2024-01-16 10:00:00.000000
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'def456'
+down_revision: str = 'abc123'
+
+# Define table for data operations
+categories = sa.table(
+    'categories',
+    sa.column('id', sa.Integer),
+    sa.column('name', sa.String),
+    sa.column('slug', sa.String),
+)
+
+
+def upgrade() -> None:
+    # Bulk insert default data
+    op.bulk_insert(
+        categories,
+        [
+            {'id': 1, 'name': 'Technology', 'slug': 'technology'},
+            {'id': 2, 'name': 'Business', 'slug': 'business'},
+            {'id': 3, 'name': 'Science', 'slug': 'science'},
+        ]
+    )
+
+
+def downgrade() -> None:
+    op.execute(categories.delete().where(categories.c.id.in_([1, 2, 3])))
+\`\`\`
+
+## Complex Data Migration with Queries
+\`\`\`python
+"""Migrate user roles to new format
+
+Revision ID: ghi789
+Revises: def456
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.orm import Session
+
+revision: str = 'ghi789'
+down_revision: str = 'def456'
+
+# Old and new tables
+old_user_roles = sa.table(
+    'user_roles',
+    sa.column('user_id', sa.Integer),
+    sa.column('role', sa.String),
+)
+
+new_roles = sa.table(
+    'roles',
+    sa.column('id', sa.Integer),
+    sa.column('name', sa.String),
+)
+
+user_role_assignments = sa.table(
+    'user_role_assignments',
+    sa.column('user_id', sa.Integer),
+    sa.column('role_id', sa.Integer),
+)
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    session = Session(bind=bind)
+
+    # Create new roles table
+    op.create_table(
+        'roles',
+        sa.Column('id', sa.Integer(), primary_key=True),
+        sa.Column('name', sa.String(50), unique=True),
+    )
+
+    # Create junction table
+    op.create_table(
+        'user_role_assignments',
+        sa.Column('user_id', sa.Integer(), sa.ForeignKey('users.id')),
+        sa.Column('role_id', sa.Integer(), sa.ForeignKey('roles.id')),
+    )
+
+    # Migrate data
+    unique_roles = session.execute(
+        sa.select(old_user_roles.c.role).distinct()
+    ).fetchall()
+
+    role_mapping = {}
+    for i, (role_name,) in enumerate(unique_roles, 1):
+        session.execute(new_roles.insert().values(id=i, name=role_name))
+        role_mapping[role_name] = i
+
+    # Migrate assignments
+    old_assignments = session.execute(sa.select(old_user_roles)).fetchall()
+    for user_id, role_name in old_assignments:
+        session.execute(
+            user_role_assignments.insert().values(
+                user_id=user_id,
+                role_id=role_mapping[role_name]
+            )
+        )
+
+    # Drop old column
+    op.drop_table('user_roles')
+
+
+def downgrade() -> None:
+    # Reverse migration logic
+    pass
+\`\`\`
+
+## Batch Operations (SQLite Compatible)
+\`\`\`python
+"""Add new columns with batch mode for SQLite
+
+Revision ID: jkl012
+Revises: ghi789
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'jkl012'
+down_revision: str = 'ghi789'
+
+
+def upgrade() -> None:
+    # SQLite doesn't support ALTER TABLE well, use batch mode
+    with op.batch_alter_table('users') as batch_op:
+        batch_op.add_column(sa.Column('phone', sa.String(20)))
+        batch_op.add_column(sa.Column('verified', sa.Boolean(), server_default='false'))
+        batch_op.alter_column('email', nullable=False)
+        batch_op.create_index('ix_users_phone', ['phone'])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('users') as batch_op:
+        batch_op.drop_index('ix_users_phone')
+        batch_op.drop_column('verified')
+        batch_op.drop_column('phone')
+\`\`\`
+
+## Testing Migrations
+\`\`\`python
+# tests/test_migrations.py
+import pytest
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import create_engine, inspect
+
+@pytest.fixture
+def alembic_config():
+    config = Config("alembic.ini")
+    config.set_main_option("sqlalchemy.url", "sqlite:///:memory:")
+    return config
+
+@pytest.fixture
+def engine():
+    return create_engine("sqlite:///:memory:")
+
+
+def test_migrations_upgrade_downgrade(alembic_config, engine):
+    """Test that all migrations can be applied and rolled back."""
+    # Run all upgrades
+    with engine.begin() as connection:
+        alembic_config.attributes['connection'] = connection
+        command.upgrade(alembic_config, "head")
+
+        # Verify final state
+        inspector = inspect(engine)
+        tables = inspector.get_table_names()
+        assert 'users' in tables
+        assert 'alembic_version' in tables
+
+        # Run all downgrades
+        command.downgrade(alembic_config, "base")
+
+        # Verify clean state
+        inspector = inspect(engine)
+        tables = inspector.get_table_names()
+        assert 'users' not in tables
+
+
+def test_migration_data_integrity(alembic_config, engine):
+    """Test data migrations preserve integrity."""
+    with engine.begin() as connection:
+        alembic_config.attributes['connection'] = connection
+
+        # Apply migrations up to data migration
+        command.upgrade(alembic_config, "def456")
+
+        # Verify data was inserted
+        result = connection.execute(sa.text("SELECT COUNT(*) FROM categories"))
+        assert result.scalar() == 3
+\`\`\`
+
+## Multi-Database Support
+\`\`\`python
+# alembic/env.py with multiple databases
+from alembic import context
+import os
+
+def get_url_for_db(db_name: str) -> str:
+    urls = {
+        'primary': os.environ.get('PRIMARY_DB_URL'),
+        'analytics': os.environ.get('ANALYTICS_DB_URL'),
+    }
+    return urls.get(db_name)
+
+
+def run_migrations_online() -> None:
+    db_name = context.get_x_argument(as_dictionary=True).get('db', 'primary')
+    url = get_url_for_db(db_name)
+
+    # Use appropriate metadata based on database
+    if db_name == 'analytics':
+        from app.models.analytics import Base as AnalyticsBase
+        target_metadata = AnalyticsBase.metadata
+    else:
+        from app.models import Base
+        target_metadata = Base.metadata
+
+    # ... rest of configuration
+\`\`\`
+
+\`\`\`bash
+# Run migrations for specific database
+alembic -x db=primary upgrade head
+alembic -x db=analytics upgrade head
+\`\`\`
+
+## ✅ DO
+- Always review auto-generated migrations before applying
+- Use environment variables for database URLs (never commit credentials)
+- Write both \`upgrade()\` and \`downgrade()\` functions
+- Use \`batch_alter_table\` for SQLite compatibility
+- Test migrations in CI before deploying
+- Use descriptive migration messages
+- Create separate migrations for schema and data changes
+- Back up database before running migrations in production
+
+## ❌ DON'T
+- Don't edit migrations that have already been applied in production
+- Don't use \`autogenerate\` for data migrations
+- Don't commit database credentials in alembic.ini
+- Don't skip downgrade implementations (needed for rollbacks)
+- Don't run untested migrations directly in production