Padrões de Migração de Banco de Dados

Alterações seguras e reversíveis de esquema de banco de dados para sistemas de produção.

Quando Ativar

• Criando ou alterando tabelas de banco de dados
• Adicionando/removendo colunas ou índices
• Executando migrações de dados (preenchimento, transformação)
• Planejando alterações de esquema com zero tempo de inatividade
• Configurando ferramentas de migração para um novo projeto

Princípios Fundamentais

1. Toda alteração é uma migração — nunca altere bancos de dados de produção manualmente
2. Migrações são apenas para frente em produção — rollbacks usam novas migrações para frente
3. Migrações de esquema e de dados são separadas — nunca misture DDL e DML em uma única migração
4. Teste migrações contra dados em tamanho de produção — uma migração que funciona em 100 linhas pode travar em 10M
5. Migrações são imutáveis após serem implantadas — nunca edite uma migração que já foi executada em produção

Checklist de Segurança de Migração

Antes de aplicar qualquer migração:

• Migração tem tanto UP quanto DOWN (ou é explicitamente marcada como irreversível)
• Sem travamentos completos de tabela em tabelas grandes (use operações concorrentes)
• Novas colunas têm padrões ou são anuláveis (nunca adicione NOT NULL sem padrão)
• Índices criados concorrentemente (não em linha com CREATE TABLE para tabelas existentes)
• Preenchimento de dados é uma migração separada da alteração de esquema
• Testado contra uma cópia dos dados de produção
• Plano de rollback documentado

Padrões PostgreSQL

Adicionando uma Coluna com Segurança

-- GOOD: Nullable column, no lock
ALTER TABLE users ADD COLUMN avatar_url TEXT;

-- GOOD: Column with default (Postgres 11+ is instant, no rewrite)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;

-- BAD: NOT NULL without default on existing table (requires full rewrite)
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- This locks the table and rewrites every row

Adicionando um Índice Sem Tempo de Inatividade

-- BAD: Blocks writes on large tables
CREATE INDEX idx_users_email ON users (email);

-- GOOD: Non-blocking, allows concurrent writes
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

-- Note: CONCURRENTLY cannot run inside a transaction block
-- Most migration tools need special handling for this

Renomeando uma Coluna (Zero Tempo de Inatividade)

Nunca renomeie diretamente em produção. Use o padrão expandir-contração:

-- Step 1: Add new column (migration 001)
ALTER TABLE users ADD COLUMN display_name TEXT;

-- Step 2: Backfill data (migration 002, data migration)
UPDATE users SET display_name = username WHERE display_name IS NULL;

-- Step 3: Update application code to read/write both columns
-- Deploy application changes

-- Step 4: Stop writing to old column, drop it (migration 003)
ALTER TABLE users DROP COLUMN username;

Removendo uma Coluna com Segurança

-- Step 1: Remove all application references to the column
-- Step 2: Deploy application without the column reference
-- Step 3: Drop column in next migration
ALTER TABLE orders DROP COLUMN legacy_status;

-- For Django: use SeparateDatabaseAndState to remove from model
-- without generating DROP COLUMN (then drop in next migration)

Migrações de Dados em Larga Escala

-- BAD: Updates all rows in one transaction (locks table)
UPDATE users SET normalized_email = LOWER(email);

-- GOOD: Batch update with progress
DO $$
DECLARE
  batch_size INT := 10000;
  rows_updated INT;
BEGIN
  LOOP
    UPDATE users
    SET normalized_email = LOWER(email)
    WHERE id IN (
      SELECT id FROM users
      WHERE normalized_email IS NULL
      LIMIT batch_size
      FOR UPDATE SKIP LOCKED
    );
    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    RAISE NOTICE 'Updated % rows', rows_updated;
    EXIT WHEN rows_updated = 0;
    COMMIT;
  END LOOP;
END $$;

Prisma (TypeScript/Node.js)

Fluxo de Trabalho

# Create migration from schema changes
npx prisma migrate dev --name add_user_avatar

# Apply pending migrations in production
npx prisma migrate deploy

# Reset database (dev only)
npx prisma migrate reset

# Generate client after schema changes
npx prisma generate

Exemplo de Esquema

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  avatarUrl String?  @map("avatar_url")
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
  orders    Order[]

  @@map("users")
  @@index([email])
}

Migração SQL Personalizada

Para operações que o Prisma não consegue expressar (índices concorrentes, preenchimento de dados):

…