create-migration

name	create-migration
description	Cria e gerencia migrations de banco de dados com Alembic no CappyCloud. Use quando o usuário pedir para criar uma migration, alterar schema, adicionar tabela, adicionar coluna, renomear campo, ou qualquer mudança no banco de dados. NUNCA crie arquivos de migration manualmente — sempre use o comando Alembic.

Migrations com Alembic — CappyCloud

Regra Fundamental

JAMAIS crie ou edite arquivos de migration manualmente. Sempre use alembic revision para gerar o arquivo. O timestamp no nome garante a ordem.

---

Setup inicial (apenas uma vez)

Se services/api/alembic/ não existir:

cd services/api
alembic init alembic

Depois configure alembic.ini e alembic/env.py:

alembic.ini — aponte para o banco:

sqlalchemy.url = postgresql+asyncpg://user:pass@localhost/cappycloud

Em produção, prefira ler da variável de ambiente em env.py em vez de hardcodar aqui.

alembic/env.py — conecte os ORM models:

from app.infrastructure.orm_models import Base
target_metadata = Base.metadata

Para banco async (asyncpg), use run_async_migrations:

from sqlalchemy.ext.asyncio import async_engine_from_config

async def run_async_migrations() -> None:
    connectable = async_engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
    )
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)

Adicione alembic ao requirements.txt:

alembic>=1.13.0

---

Criar uma nova migration

Autogenerate (preferido)

Detecta automaticamente diferenças entre os ORM models e o banco:

cd services/api
alembic revision --autogenerate -m "descricao_curta_do_que_muda"

Exemplo:

alembic revision --autogenerate -m "add_refresh_token_to_users"

Arquivo gerado: alembic/versions/20260415_143022_add_refresh_token_to_users.py

O timestamp YYYYMMDD_HHMMSS é gerado automaticamente e garante a ordem de execução.

Migration vazia (para DDL manual ou dados)

alembic revision -m "seed_default_roles"

Preencha manualmente as funções upgrade() e downgrade() no arquivo gerado.

---

Estrutura do arquivo gerado

"""add_refresh_token_to_users

Revision ID: a1b2c3d4e5f6
Revises: <id_da_anterior>
Create Date: 2026-04-15 14:30:22.123456
"""
from alembic import op
import sqlalchemy as sa

def upgrade() -> None:
    op.add_column("users", sa.Column("refresh_token", sa.String(), nullable=True))

def downgrade() -> None:
    op.drop_column("users", "refresh_token")

Sempre revise o arquivo gerado antes de aplicar — o autogenerate pode não detectar:

• Renomeações de coluna (aparece como drop + add)
• Constraints complexas
• Indexes condicionais

---

Aplicar migrations

# Subir para a versão mais recente
alembic upgrade head

# Subir N versões
alembic upgrade +1

# Ver versão atual
alembic current

# Ver histórico
alembic history --verbose

Reverter migrations

# Voltar uma versão
alembic downgrade -1

# Voltar para revisão específica
alembic downgrade a1b2c3d4e5f6

# Voltar tudo (cuidado em produção!)
alembic downgrade base

---

Checklist antes de cada migration

• ORM model em app/infrastructure/orm_models.py atualizado
• Migration gerada com alembic revision --autogenerate
• Arquivo gerado revisado (upgrade + downgrade corretos)
• alembic upgrade head executado localmente
• Testes passando (pytest)

---

Boas práticas

Faça	Evite
Nome descritivo em snake_case	Nomes genéricos como update_db
Sempre implementar downgrade()	Deixar downgrade() vazio
Uma mudança lógica por migration	Misturar alterações não relacionadas
Commitar migration junto com o model	Commitar model sem migration