Em que pé está o meu ALTER TABLE? Três formas de acompanhar o progresso no MySQL

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.

  1. Performance_schema (Nativo a partir do MySQL 5.7.6)
  2. Acompanhar arquivo IBD temporário gerado pelo MySQL (Nativo MySQL)
  3. 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:

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:
Operation, tries, wait:
analyze_table, 10, 1
copy_rows, 10, 0.25
create_triggers, 10, 1
drop_triggers, 10, 1
swap_tables, 10, 1
update_foreign_keys, 10, 1
Starting a dry run. teste_carga.TESTE will not be altered. Specify –execute instead of –dry-run to alter the table.
Creating new table…
Created new table teste_carga._TESTE_new OK.
Altering new table…
Altered teste_carga._TESTE_new OK.
Not creating triggers because this is a dry run.
Not copying rows because this is a dry run.
Not swapping tables because this is a dry run.
Not dropping old table because this is a dry run.
Not dropping triggers because this is a dry run.
2026-10-24T20:15:01 Dropping new table…
2026-10-24T20:15:01 Dropped new table OK.
Dry run complete. teste_carga.TESTE was not altered.

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.
Not checking slave lag because no slaves were found and –check-slave-lag was not specified.
Operation, tries, wait:
analyze_table, 10, 1
copy_rows, 10, 0.25
create_triggers, 10, 1
drop_triggers, 10, 1
swap_tables, 10, 1
update_foreign_keys, 10, 1
Altering teste_carga.TESTE…
Creating new table…
Created new table teste_carga._TESTE_new OK.
Altering new table…
Altered teste_carga._TESTE_new OK.
2026-10-24T20:19:02 Creating triggers…
2026-10-24T20:19:02 Created triggers OK.

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…
Copying teste_carga.TESTE: 6% 06:59 remain
Copying teste_carga.TESTE: 12% 07:09 remain
(…)
Copying teste_carga.TESTE: 93% 01:34 remain
Copying teste_carga.TESTE: 94% 01:16 remain
Copying teste_carga.TESTE: 95% 01:00 remain
Copying teste_carga.TESTE: 96% 00:46 remain
Copying teste_carga.TESTE: 98% 00:26 remain
Copying teste_carga.TESTE: 99% 00:11 remain

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.

COMPARTILHE:
Picture of Leonardo Ramos

Leonardo Ramos

DBA MySQL & Sybase At Horus Solutions
Picture of Leonardo Ramos

Leonardo Ramos

DBA MySQL & Sybase At Horus Solutions

PARTICIPE

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *