Uma dúvida frequente dos DBAs é, “em que pé está a minha operação?”
Essa é uma dúvida frequente, pois o MySQL não nos deixa explícito o progresso de uma alteração.
Abaixo vou registrar três formas de verificar esse progresso para facilitar o dia a dia.
- Performance_schema (Nativo a partir do MySQL 5.7.6)
- Acompanhar arquivo IBD temporário gerado pelo MySQL (Nativo MySQL)
- Pt-Online-Schema-change (Utilitário da ferramenta Percona Toolkit)
- Performance_schema (Nativo a partir do MySQL 5.7.6):
A primeira forma é através do performance_schema, onde o primeiro passo é ter ele ativo no ambiente (Caso esteja off, necessita do restart do MySQL, pois a mudança não é dinâmica).
Após ativar/confirmar que o performance_schema está ativo, você precisa ativar os instrumentos de Stage do Alter, para que cada etapa da operação seja verificada.
Os stages são divididos em:
| Instrumento | O que é |
|---|---|
alter table (read PK and internal sort) |
Lê a tabela pela chave primária e já começa a ordenar os dados dos índices |
alter table (merge sort) |
Junta os blocos ordenados de cada índice |
alter table (insert) |
Grava os dados ordenados na nova estrutura |
alter table (log apply index) |
Aplica as alterações feitas na tabela durante o ALTER (criação de índice) |
alter table (log apply table) |
O mesmo, mas quando a tabela inteira é reconstruída |
alter table (flush) |
Descarrega as páginas para o disco |
alter table (end) |
Finalização |
Nem toda operação vai passar por todas as fases, depende muito do comando que você utilizar.
- Para ativar, você precisa realizar um update na performance_schema.setup_instruments:
| UPDATE PERFORMANCE_SCHEMA.SETUP_INSTRUMENTS SET ENABLED = ‘YES’, TIMED = ‘YES’ WHERE NAME LIKE ‘stage/innodb/alter%’; |
- O próximo passo é habilitar os consumers de stage:
| UPDATE PERFORMANCE_SCHEMA.SETUP_CONSUMERS SET ENABLED = ‘YES’ WHERE NAME LIKE ‘events_stages_%’; |
Lembrando que esses updates valem até o restart do MySQL.
- Caso queira que fique fixo para sempre, pode adicionar ao My.cnf:
|
performance-schema-instrument=’stage/innodb/alter%=ON’ performance-schema-consumer-events-stages-current=ON performance-schema-consumer-events-stages-history=ON |
- Após soltar o comando de alteração, podemos acompanhar com a seguinte query:
| SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED, ROUND(100 * WORK_COMPLETED / WORK_ESTIMATED, 2) AS percentual FROM performance_schema.events_stages_current WHERE EVENT_NAME LIKE ‘stage/innodb/alter%’; |
EVENT_NAME: fase em que a operação está
WORK_COMPLETED: unidades de trabalho já concluídas
WORK_ESTIMATED: total estimado de unidades
percentual: progresso calculado
- Abaixo um exemplo desse método:
Após a execução do comando de alter, podemos executar a consulta para acompanhar, tendo o seguinte resultado:
| +——————————————————+—————-+—————-+————+ | EVENT_NAME | WORK_COMPLETED | WORK_ESTIMATED | percentual | +——————————————————+—————-+—————-+————+ | stage/innodb/alter table (read PK and internal sort) | 111080 | 870066 | 12.77 | +——————————————————+—————-+—————-+————+ |
| +——————————————————+—————-+—————-+————+ | EVENT_NAME | WORK_COMPLETED | WORK_ESTIMATED | percentual | +——————————————————+—————-+—————-+————+ | stage/innodb/alter table (read PK and internal sort) | 543864 | 870066 | 62.51 | +——————————————————+—————-+—————-+————+ |
| +——————————————————+—————-+—————-+————+ | EVENT_NAME | WORK_COMPLETED | WORK_ESTIMATED | percentual | +——————————————————+—————-+—————-+————+ | stage/innodb/alter table (read PK and internal sort) | 870066| 870066| 100.00 | +——————————————————+—————-+—————-+————+ |
- Por fim, temos um resumo das operações:
| +——————————————————+—————-+—————-+————+ | EVENT_NAME | WORK_COMPLETED | WORK_ESTIMATED | percentual | +——————————————————+—————-+—————-+————+ | stage/innodb/alter table (read PK and internal sort) | 870066 | 870066| 100.00 | | stage/innodb/alter table (insert) | 1957046 | 1957046 | 100.00 | +——————————————————+—————-+—————-+————+ |
- Para verificar o resumo das operações, usamos a seguinte query:
| SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED, ROUND(100 * WORK_COMPLETED / WORK_ESTIMATED, 2) AS percentual FROM performance_schema.events_stages_history WHERE EVENT_NAME LIKE ‘stage/innodb/alter%’; |
- Acompanhar arquivo IBD temporário gerado pelo MySQL (Nativo MySQL):
Nesse caso, não temos uma precisão tão grande quanto o passo anterior, pois é baseado em estimativas, porém, caso não consiga utilizar o passo anterior, é uma maneira que “quebra um galho” e tem um bom uso no dia a dia.
Quando uma execução que exige alterar a tabela entra no ambiente, o MySQL por padrão cria um novo arquivo temporário no datadir, que basicamente “recria” a tabela por debaixo dos panos.
Os arquivos criados seguem o seguinte padrão -> #sql-*.ibd
*Obs: esse método só funciona para alterações que reconstroem a tabela. Um add index simples, por exemplo, cria o índice dentro do próprio arquivo da tabela e não gera o arquivo temporário.*
Levando isso em consideração, podemos usar o seguinte raciocínio:
Se a tabela vai ser recriada, o tamanho do arquivo temporário tende a ficar igual (ou um pouco maior/menor) do que a tabela original, e é aí que está a charada.
Vamos supor que a tabela que está sendo modificada tenha 100GB, o arquivo temporário que irá aparecer no datadir, vai crescer até aproximadamente esse tamanho:
10GB -> 10% alterado
20GB -> 20% alterado
Assim em diante…
Ou seja, quanto mais perto do tamanho real da tabela, mais próximo a alteração está de finalizar.
Dessa forma você pode verificar com um ls -ltrsh no unix, ou até mesmo criar um shellscript em que você passa o tamanho real da tabela e o script compara ele com o tamanho do arquivo, gerando uma % para sua alteração.
Algumas alterações podem não seguir essa regra e o arquivo temporário ficar menor/maior, como por exemplo num drop de coluna ou adição de um campo grande na tabela.
Abaixo um exemplo desse método:
| +—————+————+———+———+ | database_name | TABLE_NAME | size_mb | size_gb | +—————+————+———+———+ | teste_carga | TESTE | 3530.61 | 3.45 | +—————+————+———+———+ |
Podemos notar que a tabela tem 3.45GB.
Logo após soltar o comando de alter table, podemos identificar o arquivo temporário no datadir, dentro da pasta do database (nesse caso teste_carga)
| 112K -rw-r—–. 1 mysql mysql 112K Oct 5 16:15 carga_log.ibd 3.5G -rw-r—–. 1 mysql mysql 3.5G Oct 24 19:34 TESTE.ibd 85M -rw-r—–. 1 mysql mysql 84M Oct 24 19:48 #sql-d7e_47.ibd |
Aqui podemos ver que o arquivo foi gerado, agora é verificar o tamanho do arquivo, conforme se aproxima do tamanho real da tabela, mais próximo o comando está de finalizar.
A estimativa é que o arquivo fique próximo dos 3.45GB. Assim que o comando finaliza, o arquivo temporário passa a ser a nova tabela e o arquivo antigo é removido.
- Pt-Online-Schema-change (Percona Toolkit / Minimiza o lock na tabela):
Nesse caso, o utilitário mostra a porcentagem da alteração e, ao mesmo tempo, não deixa a tabela ficar bloqueada durante a cópia dos dados.
Funciona da seguinte forma:
O pt-online-schema-change cria uma cópia vazia da tabela e faz a alteração diretamente nesse clone. Enquanto isso, na tabela original são criadas 3 triggers (uma de insert, uma de update e uma de delete), responsáveis por replicar para o clone todas as escritas feitas durante o processo. Depois, os dados são copiados em lotes da tabela original para a nova.
Dessa forma, a tabela continua disponível durante a alteração, fazendo com que uma mudança em uma tabela grande, que geraria uma longa indisponibilidade, fique mais “acessível” em horário comercial ou em tabelas com grande volume de acessos no dia a dia. Existem apenas bloqueios de metadados bem curtos, no momento da criação das triggers e da troca das tabelas.
*Obs: A tabela precisa ter chave primária ou índice único.*
O primeiro passo é fazer a instalação do Percona Toolkit no ambiente para que possa ter acesso ao utilitário:
- Página de download oficial: https://www.percona.com/downloads/percona-toolkit/
- Guia de instalação: https://docs.percona.com/percona-toolkit/installation.html
Após a instalação, temos diversas possibilidades de execução do utilitário, porém nesse caso vamos utilizar a maneira mais comum, que é a seguinte:
- Primeiro comando para validar a alteração:
|
pt-online-schema-change –alter “ADD COLUMN status TINYINT NOT NULL DEFAULT 0” D=teste_carga,t=TESTE –user=root –ask-pass –chunk-size=1000 –max-load Threads_running=50 –critical-load Threads_running=100 –progress time,30 –dry-run |
- Segundo comando que realmente faz a alteração:
| pt-online-schema-change –alter “ADD COLUMN status TINYINT NOT NULL DEFAULT 0” D=teste_carga,t=TESTE –user=root –ask-pass –chunk-size=1000 –max-load Threads_running=50 –critical-load Threads_running=100 –progress time,30 –execute |
- –alter é onde informamos ao utilitário qual o comando que desejamos executar.
- D é qual o banco, seguido do T que é a tabela da alteração.
- –user é para informar qual o usuário que vai realizar a alteração (Utilizar um usuário com permissão de alteração e create na tabela/database).
- –ask-pass pede a senha após o comando ser enviado no prompt, fazendo com que a senha não fique exposta na linha de comando.
- –chunk-size funciona como um batch, onde caso seja informado por exemplo 1000, a cópia das linhas vai ser feita de 1000 em 1000, evita sobrecarregar o servidor.
- –max-load Threads_running evita sobrecarga do servidor, checa a cada lote as threads running, se passar do valor informado ele vai pausar a cópia até que a carga abaixe.
- –critical-load Threads_running caso as threads running passem do valor informado, a ferramenta aborta a operação na hora, remove as triggers e a tabela nova, mantendo a tabela original intacta.
- –progress time mostra o andamento da alteração a cada X segundos que foi informado, mostrando o percentual concluído e o tempo estimado para finalizar.
- –dry-run apenas cria a tabela nova e aplica o alter para validar, sem copiar dados.
- –execute confirma que a alteração deve ser executada de fato.
Segue documentação do utilitário, onde está presente todas as possíveis opções para executá-lo:
https://docs.percona.com/percona-toolkit/pt-online-schema-change.html
Abaixo segue um exemplo de utilização:
|
–dry-run: Enter MySQL password: |
Aqui conseguimos notar que a ferramenta criou a tabela nova e aplicou a alteração com sucesso, validando o comando sem mexer na tabela original.
Agora vamos para a execução real:
|
–execute No slaves found. See –recursion-method if host HRSVMDX191-RH-MYSQL has slaves. |
Aqui temos 3 informações importantes.
A nova tabela foi criada, alterada e junto a isso, as triggers foram criadas na tabela original, para que todas as operações de escritas fossem replicadas para a nova (assim a tabela original não fica bloqueada).
Após essa informação, já conseguimos ver o progresso da cópia de linhas para a nova tabela:
|
2026-10-24T20:19:02 Copying approximately 2706984 rows… 2026-10-24T20:46:48 Copied rows OK. |
Assim que a cópia finaliza, o utilitário faz o analyze da nova tabela, a troca de nomes e o drop da tabela antiga e das triggers:
| 2026-10-24T20:46:48 Analyzing new table… 2026-10-24T20:46:51 Swapping tables… 2026-10-24T20:46:53 Swapped original and new tables OK. 2026-10-24T20:46:53 Dropping old table… 2026-10-24T20:46:55 Dropped old table teste_carga._TESTE_old OK.2026-10-24T20:46:55 Dropping triggers… 2026-10-24T20:46:55 Dropped triggers OK. Successfully altered teste_carga.TESTE. |
Assim, temos todo o acompanhamento da alteração e a tabela original disponível durante todo o processo. Vale notar que a operação levou cerca de 27 minutos: por copiar em lotes e controlar a carga, o pt-online-schema-change costuma ser mais lento que um alter nativo, mas em troca não gera indisponibilidade.
O MySQL não mostra o progresso de uma alteração por padrão, mas isso não significa que precisamos ficar no escuro. O Performance Schema é a opção mais precisa e já vem pronta no ambiente, bastando habilitar os instrumentos. O acompanhamento do arquivo temporário é uma alternativa simples para quando não dá para usar o método anterior. E o pt-online-schema-change, além de mostrar o progresso, permite alterar tabelas grandes sem gerar indisponibilidade.
Com essas três opções, fica bem mais fácil responder ao “falta muito?” e planejar alterações com segurança no dia a dia.





