# Copiar um MySQL grande entre servidores sem gerar .sql

Procedimento fechado de migração por fluxo direto via SSH, com as flags que garantem consistência em InnoDB e o critério de validação que prova que o destino chegou íntegro.

> use um pipeline único, `mysqldump --single-transaction --quick | pv | ssh destino "mysql BANCO"`, que elimina o arquivo .sql intermediário e o limite de upload do phpMyAdmin. Depois valide com 3 comparações: contagem de tabelas, COUNT(*) por tabela e objetos de schema.

João Rizzon · 2026-11-09 · Servidores

---

## O caso em que o dump não cabe em lugar nenhum

O roteiro clássico é gerar o `.sql`, baixar, subir e importar. Ele quebra em dois pontos previsíveis quando o banco é grande: o arquivo intermediário precisa de espaço livre no disco da conta de origem (e de novo no destino), e o upload pelo navegador depende de `upload_max_filesize`, `post_max_size`, `max_execution_time` e do timeout do proxy HTTP na frente do phpMyAdmin.

O fluxo direto resolve os dois de uma vez. O `mysqldump` escreve em stdout, o `ssh` transporta, o cliente `mysql` consome em stdin do outro lado. Nenhum arquivo é criado. A documentação do cPanel chama isso de **mysqldump stream** e descreve exatamente esse encadeamento como forma de transferir bancos entre servidores ([The mysqldump Stream](https://docs.cpanel.net/knowledge-base/sql/the-mysqldump-stream/)).

Um aviso antes do comando: a Napoleon não mediu tempo nem taxa de transferência para este artigo. Os tamanhos e durações que aparecem abaixo são exemplos de saída, não resultado de laboratório nosso. O que está documentado são as flags e o comportamento delas.

## Os cinco pré-requisitos que fazem o procedimento falhar quando faltam

Antes de abrir o terminal, confirme cada item. A maior parte dos fracassos desse procedimento é pré-requisito faltando, não o pipe em si.

- Acesso SSH no servidor de origem (ou no de destino, dependendo da direção do pipe). Em hospedagem compartilhada, o acesso SSH normalmente precisa ser liberado e a chave pública cadastrada.
- Usuário MySQL com `SELECT`, `LOCK TABLES`, `SHOW VIEW`, `TRIGGER`, `PROCESS` e `EVENT` na origem, conforme o que o dump incluir.
- Banco de destino **já criado**, com usuário associado e privilégios completos sobre ele. O `mysql` cliente não cria o schema sozinho quando você passa o nome do banco na linha de comando.
- Versões de servidor compatíveis. Dump de MySQL 8 restaurado em MariaDB 10.x costuma tropeçar em `utf8mb4_0900_ai_ci`, que não existe do outro lado.
- `pv` instalado onde o pipe começa. Se não houver, o comando funciona igual, só sem barra de progresso.

Verifique a collation antes de começar, porque descobrir no meio da restauração é caro:

```bash
mysql -u USUARIO -p -e "SELECT @@version, @@character_set_server, @@collation_server;"
```

## O comando, flag por flag

O formato base documentado pelo cPanel encadeia dump, transporte e importação em uma linha:

```bash
mysqldump --single-transaction --quick --routines --triggers --events \
  -u USUARIO_ORIGEM -p BANCO_ORIGEM \
  | pv \
  | ssh -C usuario@destino.exemplo.com \
      "mysql -u USUARIO_DESTINO -pSENHA BANCO_DESTINO"
```

Cada flag está aí por um motivo:

| Flag | O que faz | Por que importa em banco grande |
|---|---|---||
| `--single-transaction` | Abre uma transação com snapshot consistente antes de ler | Consistência em InnoDB sem travar escrita. Não protege tabelas MyISAM |
| `--quick` | Lê linha a linha em vez de carregar a tabela inteira na memória | Evita estourar RAM em tabelas com milhões de linhas |
| `--routines` | Inclui stored procedures e functions | Elas não vêm por padrão e o site quebra depois |
| `--triggers` | Inclui triggers (padrão em versões atuais) | Explícito é melhor que implícito aqui |
| `--events` | Inclui eventos agendados | Idem, não vêm por padrão |
| `ssh -C` | Compressão no transporte | Dump SQL é texto, comprime bem |
| `pv` | Mostra bytes transferidos e taxa | Diferencia "lento" de "travado" |

A saída do `pv` aparece no terminal mais ou menos assim (exemplo ilustrativo, não medição):

```
 4,21GiB 0:11:38 [6,18MiB/s] [                 <=>                 ]
```

### Por que passar a senha na linha de comando é um risco e o que usar no lugar

Passar `-pSENHA` dentro das aspas do `ssh` expõe a senha no histórico e na lista de processos do servidor remoto. Prefira um `~/.my.cnf` no destino, com permissão `600`:

```ini
[client]
user=USUARIO_DESTINO
password=SENHA
```

E então o comando remoto vira só `mysql BANCO_DESTINO`.

### Como um ALTER TABLE na origem quebra o snapshot do dump

`--single-transaction` dá consistência de leitura, mas um `ALTER TABLE` rodando na origem durante o dump pode quebrar o snapshot. Se houver migração ou cron de manutenção, suspenda antes.

## Quando o InnoDB não é a única engine

`--single-transaction` só vale para engines transacionais. Se o banco tem MyISAM, o snapshot não cobre essas tabelas e você pode terminar com um dump internamente inconsistente (pedido feito na tabela A, itens do pedido ausentes na tabela B).

Confira antes:

```bash
mysql -u USUARIO -p -e \
  "SELECT ENGINE, COUNT(*) FROM information_schema.TABLES \
   WHERE TABLE_SCHEMA='BANCO_ORIGEM' GROUP BY ENGINE;"
```

Se aparecer MyISAM, duas saídas: converter para InnoDB antes da migração, ou usar `--lock-tables` e aceitar janela de escrita bloqueada. Não existe terceira via boa.

## O que fazer quando o pipe cai aos 80 por cento

O fluxo direto tem uma fragilidade que o arquivo intermediário não tem: se a conexão SSH cai aos 80%, não existe nada para retomar. Você recomeça do zero.

Três mitigações, por ordem de esforço:

- **Rodar dentro de `screen` ou `tmux`** no servidor onde o comando começa. Desconexão do seu notebook deixa de matar o processo.
- **Keepalive no SSH**, para que NAT e firewall não derrubem a sessão em transferências longas:

```bash
ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=10 -C usuario@destino.exemplo.com "..."
```

- **Dividir por tabela** quando o banco tem poucas tabelas gigantes. Dump das tabelas pequenas em um comando e cada tabela grande em um comando próprio, com `mysqldump BANCO tabela1 tabela2`. Perde a consistência global entre os comandos, então só faz sentido com o site em manutenção.

Uma quarta opção, se o destino tem disco sobrando e a origem não: streaming para arquivo no destino, com `gzip` no meio. Deixa de ser importação direta, mas preserva a tentativa parcial.

```bash
mysqldump --single-transaction --quick -u USUARIO -p BANCO \
  | gzip -1 \
  | ssh usuario@destino.exemplo.com "cat > /home/usuario/backup.sql.gz"
```

## Validação objetiva no destino

Terminou sem erro não é sinônimo de migrou certo. Compare três coisas, nessa ordem, rodando a mesma consulta nos dois servidores.

### Comparar o número de tabelas nos dois lados

```sql
SELECT COUNT(*) AS tabelas
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = 'BANCO';
```

Divergência aqui quase sempre é privilégio faltando na origem (views que o usuário não podia ler) ou erro abortado no meio.

### Contar linhas de verdade, sem confiar em TABLE_ROWS

`information_schema.TABLES.TABLE_ROWS` é estimativa em InnoDB. Para validação, use `COUNT(*)` de verdade. Gere o script de contagem em vez de digitar tabela por tabela:

```bash
mysql -u USUARIO -p -N -B -e \
  "SELECT CONCAT('SELECT \"', TABLE_NAME, '\" AS t, COUNT(*) AS n FROM \`', TABLE_NAME, '\`;') \
   FROM information_schema.TABLES \
   WHERE TABLE_SCHEMA='BANCO' AND TABLE_TYPE='BASE TABLE';" BANCO > contagens.sql
```

Rode `mysql -u USUARIO -p -N -B BANCO < contagens.sql > origem.txt` na origem e o equivalente no destino, depois `diff origem.txt destino.txt`. Saída vazia é o resultado que você quer.

### Views, procedures e triggers que o dump esquece

Views, procedures, functions, triggers e events merecem conferência separada:

```sql
SELECT ROUTINE_TYPE, COUNT(*) FROM information_schema.ROUTINES
  WHERE ROUTINE_SCHEMA='BANCO' GROUP BY ROUTINE_TYPE;
SELECT COUNT(*) FROM information_schema.TRIGGERS WHERE TRIGGER_SCHEMA='BANCO';
SELECT COUNT(*) FROM information_schema.EVENTS WHERE EVENT_SCHEMA='BANCO';
```

**Usuários e privilégios não vão no dump de um banco.** Recriar o usuário do aplicativo no destino é passo manual.

## Sete mensagens de erro e o que cada uma significa

| Mensagem | Causa provável | Correção |
|---|---|---||
| `Unknown database 'X'` | Banco de destino não existe | Criar o banco antes, pelo painel ou `CREATE DATABASE` |
| `Unknown collation: 'utf8mb4_0900_ai_ci'` | Origem MySQL 8, destino MariaDB | Converter a collation na origem (`ALTER DATABASE ... COLLATE utf8mb4_unicode_ci` e `ALTER TABLE ... CONVERT TO`) ou sanitizar o dump no pipe: `sed 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g; s/CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci/CHARACTER SET utf8mb4/g'`. Não conte com `--compatible`: depreciada no MySQL 8.0.26 e removida no 8.4 |
| `MySQL server has gone away` | Pacote maior que `max_allowed_packet` no destino | Aumentar `max_allowed_packet` no destino, ou dump com `--max-allowed-packet` menor |
| `Access denied ... PROCESS privilege` | Usuário sem privilégio para tablespaces | `--no-tablespaces` no `mysqldump` |
| `Got packet bigger than 'max_allowed_packet'` | Mesma causa, lado do cliente | Passar `--max-allowed-packet=256M` ao cliente `mysql` |
| Pipe encerra sem erro e sem dados | `mysqldump` falhou e o `ssh` recebeu stdin vazio | Testar o dump isolado primeiro, redirecionando para `head` |

Teste o começo do dump antes de disparar o pipe inteiro. Vinte segundos aqui evitam uma hora perdida:

```bash
mysqldump --single-transaction --quick -u USUARIO -p BANCO | head -c 2000
```

## Por que dá para repetir a migração, e o risco que sobra depois do cutover

O procedimento não altera a origem. Ela continua intacta e servindo o site até você trocar a string de conexão. É essa propriedade que torna o fluxo direto seguro de repetir: se a validação acusar divergência, apague o banco de destino, recrie vazio e rode de novo.

A janela de risco vai do início do dump até o cutover: nesse intervalo a origem ainda recebe escritas que o destino não tem, e o `diff` das contagens só prova integridade no instante em que o dump começou. Depois do cutover a direção se inverte, e o risco passa a ser escrita residual chegando na origem: string de conexão antiga em cache de aplicação ou de pool, cron que carregou o `.env` velho, worker de fila que não foi reiniciado. Por isso vale fazer a migração com o site em manutenção, ou repetir o dump da última tabela volátil imediatamente antes de virar o DNS. Depois da troca, deixe a origem em modo somente leitura (`SET GLOBAL read_only = ON`, ou revogando o `INSERT`/`UPDATE`/`DELETE` do usuário do aplicativo) por alguns dias: qualquer escrita que ainda aponte para lá vira erro visível no log em vez de dado perdido em silêncio. Guarde o `diff` das contagens do momento do cutover, ele é a prova de que o destino chegou íntegro.

