> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrações de Esquema no MySQL

> Como executar migrações de esquema no MySQL com segurança: comportamento do ALTER TABLE, DDL online, migrações de tabelas grandes e como usar pt-online-schema-change ou gh-ost.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

As mudanças de esquema em um banco de dados MySQL em produção vão de triviais (adicionar uma coluna anulável a uma tabela pequena) a perigosas (modificar uma coluna em uma tabela de 500 GB que processa 50 mil gravações por segundo). A diferença está em se o MySQL bloqueia a tabela e por quanto tempo.

## Como o ALTER TABLE Funciona

O `ALTER TABLE` do MySQL tem dois modos, dependendo da operação e da versão:

**DDL com reconstrução** (o comportamento antigo): o MySQL cria uma nova tabela com o novo esquema, copia todas as linhas, troca as tabelas e descarta a original. A tabela fica bloqueada para gravações durante toda a operação — de minutos a horas em tabelas grandes.

**DDL online**: muitas operações podem ser executadas sem bloquear leituras ou gravações. O MySQL faz a mudança no lugar ou reconstrói a tabela em segundo plano enquanto permite DML concorrente. Para descobrir o que uma operação específica vai fazer, adicione as cláusulas `ALGORITHM` e `LOCK` explicitamente — o MySQL rejeita a instrução se não conseguir atender às restrições solicitadas:

```sql theme={null}
-- Fail fast if the operation would require any locking
ALTER TABLE orders ADD COLUMN notes TEXT, LOCK=NONE;
```

## Modos de Bloqueio do DDL Online

As cláusulas `ALGORITHM` e `LOCK` controlam como o MySQL executa a mudança:

| ALGORITHM | Comportamento |
| :- | :- |
| `INSTANT` | Altera apenas metadados — sem reconstrução da tabela, sem leitura de linhas. Disponível no MySQL 8.0 para algumas operações. |
| `INPLACE` | Modifica a tabela no lugar com bloqueio mínimo. As linhas podem não ser reconstruídas. |
| `COPY` | Cria uma nova tabela e copia todas as linhas. O mais lento; obrigatório para algumas operações. |

| LOCK | Comportamento |
| :- | :- |
| `NONE` | Sem bloqueio — leituras e gravações continuam normalmente durante a mudança |
| `SHARED` | Bloqueio de leitura — leituras continuam, gravações ficam bloqueadas |
| `EXCLUSIVE` | Bloqueio total — leituras e gravações ficam bloqueadas |

```sql theme={null}
-- Request a specific algorithm; fails if MySQL can't do it that way
ALTER TABLE orders
    ADD COLUMN notes TEXT,
    ALGORITHM=INSTANT;

-- Fail if the operation would require a write lock
ALTER TABLE orders
    ADD COLUMN notes TEXT,
    LOCK=NONE;
```

## O Que É Rápido e O Que É Lento

As operações que usam `ALGORITHM=INSTANT` (MySQL 8.0) são quase instantâneas, independentemente do tamanho da tabela:

* Adicionar uma coluna, em qualquer posição (MySQL 8.0.29+)
* Adicionar/remover uma coluna gerada virtual
* Alterar o valor padrão de uma coluna

As operações que exigem `ALGORITHM=COPY` bloqueiam gravações durante toda a execução:

* Alterar o tipo de dados de uma coluna
* Converter conjuntos de caracteres
* (Adicionar um índice full-text *não* é uma delas — ele é executado como `INPLACE`, mas sempre precisa de pelo menos `LOCK=SHARED`, então as leituras continuam e as gravações ficam bloqueadas; `LOCK=NONE` é rejeitado com ERROR 1846)

A maioria das adições de índice usa `ALGORITHM=INPLACE, LOCK=NONE` — a reconstrução da tabela acontece em segundo plano e o DML continua. Adicionar um índice em uma tabela de 100 GB leva tempo, mas não bloqueia sua aplicação.

## Migrações de Tabelas Grandes em Produção

Para operações que exigem `ALGORITHM=COPY` em tabelas grandes demais para serem bloqueadas, use uma ferramenta externa:

### pt-online-schema-change (Percona Toolkit)

```bash theme={null}
pt-online-schema-change \
  --alter "ADD COLUMN notes TEXT" \
  --execute \
  D=mydb,t=orders
```

O `pt-osc` cria uma tabela sombra, copia as linhas em lotes, usa triggers para replicar as gravações em andamento e então troca as tabelas. Sem tempo de inatividade da aplicação.

### gh-ost (GitHub)

```bash theme={null}
gh-ost \
  --user=root --host=localhost \
  --database=mydb --table=orders \
  --alter="ADD COLUMN notes TEXT" \
  --execute
```

O `gh-ost` usa o log binário em vez de triggers, o que é mais confiável sob alta carga de gravação. É a ferramenta preferida para tabelas de alto tráfego.

Ambas as ferramentas exigem que a tabela tenha uma chave primária.

## Ferramentas de Migração e Controle de Versão

Acompanhe as mudanças de esquema em arquivos de migração sob controle de versão. Ferramentas comuns:

| Ferramenta | Linguagem | Estilo |
| :- | :- | :- |
| Flyway | Java/qualquer | Baseado em SQL; arquivos versionados |
| Liquibase | Java/qualquer | XML/YAML/SQL; change sets |
| golang-migrate | Go | Baseado em SQL; arquivos numerados |
| Alembic | Python | Python ou SQL; gera automaticamente a partir dos modelos |

Cada ferramenta mantém uma tabela de migrações no banco de dados para registrar quais migrações já foram executadas, então reexecuções são seguras.

## Perguntas Frequentes

#### Posso adicionar uma coluna sem bloquear a tabela?

Adicionar uma coluna anulável, em qualquer posição, usa `ALGORITHM=INSTANT` e termina em milissegundos, independentemente do tamanho da tabela (MySQL 8.0.29+). Se a operação não usar `ALGORITHM=INSTANT`, use `ALGORITHM=INPLACE, LOCK=NONE`, ou pt-osc ou gh-ost.

#### Como verifico se um ALTER TABLE vai bloquear minha tabela?

Adicione `ALGORITHM=INPLACE, LOCK=NONE` à instrução. O MySQL a executa sem bloqueio se puder, ou retorna um erro se não puder — de qualquer forma, você obtém uma resposta definitiva sem adivinhar:

```sql theme={null}
-- If this succeeds, the index add won't lock the table
ALTER TABLE orders ADD INDEX idx_customer (customer_id), ALGORITHM=INPLACE, LOCK=NONE;
```

Teste primeiro em uma cópia da tabela quando estiver em dúvida sobre tabelas grandes em produção.

#### Devo executar migrações dentro de uma transação?

As instruções DDL (`ALTER TABLE`, `CREATE INDEX`, `DROP TABLE`) causam um commit implícito no MySQL — elas não podem ser revertidas. Executá-las dentro de um bloco `BEGIN`/`COMMIT` não protege você. Planeje sua estratégia de rollback no nível da aplicação (dual-write, feature flags) em vez de depender do rollback de transação.

## Solução de Problemas

| Problema | Solução |
| :- | :- |
| `ALTER TABLE` bloqueando o tráfego de produção | Use `ALGORITHM=INSTANT` se disponível, ou pt-osc/gh-ost para tabelas grandes |
| `ERROR 1846: ALGORITHM=INSTANT is not supported` | A operação exige a reconstrução da tabela — use `ALGORITHM=INPLACE` ou uma ferramenta online |
| pt-osc falhando com erros de trigger | A tabela já tem triggers — use o gh-ost (baseado no log binário, sem triggers) |
| Migração executada duas vezes | A tabela de rastreamento da ferramenta de migração está fora de sincronia — verifique a tabela de versão do esquema |
| ALTER de longa duração segurando um bloqueio | Encerre-o com `KILL <query_id>` e use uma ferramenta online no lugar |

## Veja também

* [Estratégias de Backup do MySQL](https://villagesql.com/docs/pt-BR/guides/backup-strategies.md) — sempre faça backup antes de uma migração
* [Transações no MySQL](https://villagesql.com/docs/pt-BR/guides/transactions.md) — quais operações de migração são transacionais no MySQL
* [Particionamento de Tabelas no MySQL](https://villagesql.com/docs/pt-BR/guides/table-partitioning.md) — mudanças de particionamento também são migrações de esquema
* [Usando MySQL com ORMs: Django, Rails e Prisma](https://villagesql.com/docs/pt-BR/guides/mysql-with-orms.md) — aplicando com segurança o DDL gerado por ORMs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.