migrações-de-banco-de-dados

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

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

Quando Ativar

• Criar ou alterar tabelas no banco de dados
• Adicionar/remover colunas ou índices
• Executar migrações de dados (backfill, transformação)
• Planejar alterações de esquema sem tempo de inatividade
• Configurar 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 (forward-only) em produção — rollbacks usam novas migrações para frente
3. Migrações de esquema e dados são separadas — nunca misture DDL e DML em uma mesma migração
4. Teste migrações com dados do tamanho da produção — uma migração que funciona em 100 linhas pode travar em 10M
5. Migrações são imutáveis após a implantação — nunca edite uma migração que já foi executada em produção

Lista de Verificação de Segurança de Migração

Antes de aplicar qualquer migração:

• A migração possui UP e DOWN (ou está explicitamente marcada como irreversível)
• Sem bloqueio completo de tabelas grandes (use operações concorrentes)
• Novas colunas têm valores padrão ou são anuláveis (nunca adicione NOT NULL sem padrão)
• Índices criados de forma concorrente (não inline com CREATE TABLE em tabelas existentes)
• Backfill 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 para PostgreSQL

Adicionando uma Coluna com Segurança

-- BOM: Coluna anulável, sem bloqueio
ALTER TABLE users ADD COLUMN avatar_url TEXT;

-- BOM: Coluna com padrão (Postgres 11+ é instantâneo, sem reescrita)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;

-- RUIM: NOT NULL sem padrão em tabela existente (requer reescrita completa)
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- Isso bloqueia a tabela e reescreve todas as linhas

Adicionando um Índice Sem Indisponibilidade

-- RUIM: Bloqueia escritas em tabelas grandes
CREATE INDEX idx_users_email ON users (email);

-- BOM: Não bloqueia, permite escritas concorrentes
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

-- Nota: CONCURRENTLY não pode ser executado dentro de um bloco de transação
-- A maioria das ferramentas de migração precisa de tratamento especial para isso

Renomeando uma Coluna (Sem Indisponibilidade)

Nunca renomeie diretamente em produção. Use o padrão expand-contract (expandir e contrair):

-- Passo 1: Adicionar nova coluna (migration 001)
ALTER TABLE users ADD COLUMN display_name TEXT;

-- Passo 2: Backfill de dados (migration 002, migração de dados)
UPDATE users SET display_name = username WHERE display_name IS NULL;

-- Passo 3: Atualizar o código da aplicação para ler/escrever em ambas as colunas
-- Implantar as alterações na aplicação

-- Passo 4: Parar de escrever na coluna antiga, removê-la (migration 003)
ALTER TABLE users DROP COLUMN username;

Removendo uma Coluna com Segurança

-- Passo 1: Remover todas as referências da aplicação à coluna
-- Passo 2: Implantar a aplicação sem a referência à coluna
-- Passo 3: Remover a coluna na próxima migração
ALTER TABLE orders DROP COLUMN legacy_status;

-- Para Django: use SeparateDatabaseAndState para remover do modelo
-- sem gerar DROP COLUMN (depois remova na próxima migração)

Migrações de Dados Grandes

-- RUIM: Atualiza todas as linhas em uma transação (bloqueia a tabela)
UPDATE users SET normalized_email = LOWER(email);

-- BOM: Atualização em lote com progresso
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 'Atualizadas % linhas', rows_updated;
    EXIT WHEN rows_updated = 0;
    COMMIT;
  END LOOP;
END $$;

Prisma (TypeScript/Node.js)

Fluxo de Trabalho

# Criar migração a partir das alterações no esquema
npx prisma migrate dev --name add_user_avatar

# Aplicar migrações pendentes em produção
npx prisma migrate deploy

# Redefinir banco de dados (apenas dev)
nypx prisma migrate reset

# Gerar cliente após alterações no esquema
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 pode expressar (índices concorrentes, backfills de dados):

# Criar migração vazia, depois editar o SQL manualmente
npx prisma migrate dev --create-only --name add_email_index

-- migrations/20240115_add_email_index/migration.sql
-- O Prisma não pode gerar CONCURRENTLY, então escrevemos manualmente
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);

Drizzle (TypeScript/Node.js)

Fluxo de Trabalho

# Gerar migração a partir das alterações no esquema
npx drizzle-kit generate

# Aplicar migrações
npx drizzle-kit migrate

# Enviar esquema diretamente (apenas dev, sem arquivo de migração)
npx drizzle-kit push

Exemplo de Esquema

import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: uuid("id").primaryKey().defaultRandom(),
  email: text("email").notNull().unique(),
  name: text("name"),
  isActive: boolean("is_active").notNull().default(true),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

Kysely (TypeScript/Node.js)

Fluxo de Trabalho (kysely-ctl)

# Inicializar arquivo de configuração (kysely.config.ts)
kysely init

# Criar um novo arquivo de migração
kysely migrate make add_user_avatar

# Aplicar todas as migrações pendentes
kysely migrate latest

# Reverter a última migração
kysely migrate down

# Mostrar status das migrações
kysely migrate list

Arquivo de Migração

// migrations/2024_01_15_001_create_user_profile.ts
import { type Kysely, sql } from 'kysely'

// IMPORTANTE: Sempre use Kysely<any>, não sua interface DB tipada.
// Migrações são congeladas no tempo e não devem depender dos tipos atuais do esquema.
export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('user_profile')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('avatar_url', 'text')
    .addColumn('created_at', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull()
    )
    .execute()

  await db.schema
    .createIndex('idx_user_profile_avatar')
    .on('user_profile')
    .column('avatar_url')
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('user_profile').execute()
}

Migrador Programático

import { Migrator, FileMigrationProvider } from 'kysely'
import { promises as fs } from 'fs'
import * as path from 'path'
// ESM apenas — CJS pode usar __dirname diretamente
import { fileURLToPath } from 'url'
const migrationFolder = path.join(
  path.dirname(fileURLToPath(import.meta.url)),
  './migrations',
)

// `db` é sua instância Kysely<any> do banco de dados
const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    path,
    migrationFolder,
  }),
  // ATENÇÃO: Ative apenas em desenvolvimento. Desativa a validação
  // de ordenação por timestamp, o que pode causar desvio de esquema entre ambientes.
  // allowUnorderedMigrations: true,
})

const { error, results } = await migrator.migrateToLatest()

results?.forEach((it) => {
  if (it.status === 'Success') {
    console.log(`migration "${it.migrationName}" executed successfully`)
  } else if (it.status === 'Error') {
    console.error(`failed to execute migration "${it.migrationName}"`)
  }
})

if (error) {
  console.error('migration failed', error)
  process.exit(1)
}

Django (Python)

Fluxo de Trabalho

# Gerar migração a partir das alterações no modelo
python manage.py makemigrations

# Aplicar migrações
python manage.py migrate

# Mostrar status das migrações
python manage.py showmigrations

# Gerar migração vazia para SQL personalizado
python manage.py makemigrations --empty app_name -n description

Migração de Dados

from django.db import migrations

def backfill_display_names(apps, schema_editor):
    User = apps.get_model("accounts", "User")
    batch_size = 5000
    users = User.objects.filter(display_name="")
    while users.exists():
        batch = list(users[:batch_size])
        for user in batch:
            user.display_name = user.username
        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)

def reverse_backfill(apps, schema_editor):
    pass  # Migração de dados, não precisa de reversão

class Migration(migrations.Migration):
    dependencies = [("accounts", "0015_add_display_name")]

    operations = [
        migrations.RunPython(backfill_display_names, reverse_backfill),
    ]

SeparateDatabaseAndState

Remover uma coluna do modelo Django sem removê-la do banco de dados imediatamente:

class Migration(migrations.Migration):
    operations = [
        migrations.SeparateDatabaseAndState(
            state_operations=[
                migrations.RemoveField(model_name="user", name="legacy_field"),
            ],
            database_operations=[],  # Não toque no BD ainda
        ),
    ]

golang-migrate (Go)

Fluxo de Trabalho

# Criar par de migração
migrate create -ext sql -dir migrations -seq add_user_avatar

# Aplicar todas as migrações pendentes
migrate -path migrations -database "$DATABASE_URL" up

# Reverter a última migração
migrate -path migrations -database "$DATABASE_URL" down 1

# Forçar versão (corrigir estado sujo)
migrate -path migrations -database "$DATABASE_URL" force VERSION

Arquivos de Migração

-- migrations/000003_add_user_avatar.up.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;

-- migrations/000003_add_user_avatar.down.sql
DROP INDEX IF EXISTS idx_users_avatar;
ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;

Estratégia de Migração Sem Indisponibilidade

Para alterações críticas em produção, siga o padrão expand-contract (expandir e contrair):

Fase 1: EXPANDIR
  - Adicionar nova coluna/tabela (anulável ou com padrão)
  - Implantar: app escreve em AMBAS antiga e nova
  - Fazer backfill dos dados existentes

Fase 2: MIGRAR
  - Implantar: app lê da NOVA, escreve em AMBAS
  - Verificar consistência dos dados

Fase 3: CONTRAIR
  - Implantar: app usa apenas a NOVA
  - Remover coluna/tabela antiga em migração separada

Exemplo de Linha do Tempo

Dia 1: Migração adiciona coluna new_status (anulável)
Dia 1: Implantar app v2 — escreve tanto em status quanto em new_status
Dia 2: Executar migração de backfill para linhas existentes
Dia 3: Implantar app v3 — lê apenas de new_status
Dia 7: Migração remove coluna antiga status

Anti-Padrões

Anti-Padrão	Por Que Falha	Abordagem Melhor
SQL manual em produção	Sem trilha de auditoria, não repetível	Sempre usar arquivos de migração
Editar migrações implantadas	Causa desvio entre ambientes	Criar nova migração
NOT NULL sem padrão	Bloqueia tabela, reescreve todas as linhas	Adicionar anulável, fazer backfill, depois adicionar restrição
Índice inline em tabela grande	Bloqueia escritas durante a criação	CREATE INDEX CONCURRENTLY
Esquema + dados em uma migração	Difícil de reverter, transações longas	Migrações separadas
Remover coluna antes de remover código	Erros de aplicação por coluna ausente	Remover código primeiro, remover coluna na próxima implantação