VitePress

Appearance

Migrations ​

O banco é gerenciado via Prisma Migrate. As migrations ficam em backend/prisma/migrations/.

Fluxo de desenvolvimento ​

1. Alterar o schema ​

Editar backend/prisma/schema.prisma.

2. Criar a migration ​

bash
cd backend
npx prisma migrate dev --name descricao_da_mudanca

Esse comando:

  1. Gera o arquivo SQL em prisma/migrations/YYYYMMDDHHMMSS_descricao/migration.sql
  2. Aplica a migration no banco de desenvolvimento
  3. Regenera o Prisma Client

3. Aplicar em produção ​

As migrations são aplicadas automaticamente pelo entrypoint do container backend ao iniciar:

dockerfile
# Dockerfile do backend
CMD ["sh", "-c", "npx prisma migrate deploy && node dist/main.js"]

prisma migrate deploy aplica todas as migrations pendentes. É idempotente — não reaplica migrations já executadas.

Convenções de nomeamento ​

add_campo_na_tabela       — novo campo
remove_campo_da_tabela    — remoção de campo
create_tabela             — nova tabela
rename_campo              — renomear campo
add_index_tabela_campo    — novo índice
alter_tipo_campo          — mudança de tipo

Migrations de alto risco ​

Adicionar coluna NOT NULL em tabela grande ​

sql
-- NÃO fazer assim (bloqueia tabela):
ALTER TABLE "Customer" ADD COLUMN "newField" TEXT NOT NULL;

-- Fazer em 3 passos:
-- 1. Adicionar nullable
ALTER TABLE "Customer" ADD COLUMN "newField" TEXT;
-- 2. Backfill
UPDATE "Customer" SET "newField" = 'default_value' WHERE "newField" IS NULL;
-- 3. Adicionar constraint (em janela de manutenção)
ALTER TABLE "Customer" ALTER COLUMN "newField" SET NOT NULL;

Renomear coluna ​

sql
-- Prisma NÃO detecta rename automaticamente — interpreta como drop+add.
-- Para renomear sem perder dados, editar a migration gerada manualmente:
ALTER TABLE "Customer" RENAME COLUMN "oldName" TO "newName";
-- Remover o DROP COLUMN e ADD COLUMN que o Prisma gerou.

Verificar status das migrations ​

bash
# Quais migrations foram aplicadas
npx prisma migrate status

# Via psql direto
SELECT migration_name, started_at, finished_at
FROM "_prisma_migrations"
ORDER BY started_at DESC
LIMIT 20;

Rollback ​

Prisma Migrate não tem rollback automático. Para desfazer uma migration em produção:

  1. Escrever migration de rollback manual (inverso da migration aplicada)
  2. Testar em ambiente local
  3. Aplicar via npx prisma migrate deploy

Para drops acidentais: restaurar do backup do PostgreSQL (ver Rollback).

Backup antes de migrations de risco ​

bash
# Fazer dump antes de migration destrutiva
docker exec crm-galdix-postgres-1 \
  pg_dump -U $POSTGRES_USER $POSTGRES_DB \
  > backup_$(date +%Y%m%d_%H%M%S).sql

Estrutura dos arquivos de migration ​

backend/prisma/migrations/
├── 20250101000000_init/
│   └── migration.sql
├── 20250215143022_add_whatsapp_pricing/
│   └── migration.sql
├── 20250301120000_add_post_sale_survey/
│   └── migration.sql
└── migration_lock.toml   # versão do provider — não editar manualmente