# Ajuste do my.cnf partindo da RAM real do servidor

O orçamento de memória vem antes do editor de texto. Com fórmula, as variáveis que mudam em runtime, as que exigem reinício e o roteiro de reversão para quando o serviço não sobe.

> antes de mudar qualquer linha do my.cnf, calcule o teto: memória global (dominada por innodb_buffer_pool_size) mais os buffers por thread multiplicados por max_connections, dentro da RAM que sobra depois do Apache, do PHP-FPM e do sistema. Só então ajuste, meça e mantenha a reversão pronta.

João Rizzon · 2026-10-28 · Servidores

---

## Calcule o teto antes de editar qualquer variável

A ordem importa. Quem abre o `my.cnf` e aumenta `innodb_buffer_pool_size` porque leu em um fórum costuma descobrir o erro pelo OOM killer, não pelo benchmark. O ponto de partida é a RAM física da máquina menos o que não é MySQL.

Comece medindo o que existe:

```bash
free -m
ps -o rss= -C httpd | awk '{s+=$1} END {print s/1024" MB apache"}'
mysql -e "SHOW GLOBAL VARIABLES LIKE 'innodb_buffer_pool%';"
mysql -e "SHOW GLOBAL STATUS LIKE 'Max_used_connections';"
```

A soma de RSS acima superestima: cada filho do Apache e cada worker do PHP-FPM contabiliza de novo as páginas compartilhadas (binário, libs, copy-on-write do fork). Usar esse número como reserva do stack web encolhe indevidamente o orçamento do MySQL. Para chegar perto do consumo real, prefira PSS, que rateia a página compartilhada entre quem a mapeia:

```bash
smem -t -P 'httpd|php-fpm' -k | tail -1
awk '/^Pss:/ {s+=$2} END {print s/1024" MB"}' /proc/*/smaps_rollup
```

`smaps_rollup` existe no kernel 4.14 em diante e lê todos os processos de uma vez (rode como root). Na falta das duas opções, use a diferença de `free -m` entre o servidor web parado e sob carga de pico: é grosseiro, mas não conta a mesma página duas vezes.

O consumo máximo teórico do MySQL/MariaDB é, de forma simplificada:

**memória global + (buffers por thread × max_connections)**

A parte global é dominada por `innodb_buffer_pool_size`, mais `innodb_log_buffer_size`, `key_buffer_size` (MyISAM, ainda relevante se há tabelas antigas) e os dicionários internos. A parte por thread é alocada sob demanda, mas o pior caso é real: `sort_buffer_size`, `read_buffer_size`, `read_rnd_buffer_size`, `join_buffer_size` e `tmp_table_size`/`max_heap_table_size` podem ser alocados por conexão, e `tmp_table_size` por tabela temporária em memória dentro de uma mesma consulta.

Não confie em `Max_used_connections` como teto: ele diz o pico observado, não o pico possível. O teto é `max_connections`.

## Um orçamento de memória em planilha, antes do editor

Exemplo fictício, para ilustrar o cálculo em um servidor de 8 GB que roda Apache, PHP-FPM e cPanel na mesma máquina:

| Item | Valor | Subtotal |
|---|---|---||
| RAM física | 8192 MB |  |
| SO, cPanel, cron, backup | reservar 1024 MB | 7168 MB livres |
| Apache + PHP-FPM (pico observado) | 2500 MB | 4668 MB livres |
| Margem de segurança (10%) | 819 MB | 3849 MB para o MySQL |
| `innodb_buffer_pool_size` | 2560 MB | 1289 MB restantes |
| `innodb_log_buffer_size` | 16 MB |  |
| Buffers por thread (soma ≈ 6 MB) × `max_connections` 150 | 900 MB | ~373 MB de folga |

Os valores da tabela são hipotéticos e servem só para mostrar a conta. O número que você precisa levantar é o da sua máquina, com `free -m` em horário de pico e o PSS (não o RSS somado) do seu stack web.

Duas regras práticas que caem desse orçamento:

- Se o banco divide a máquina com o servidor web, o antigo conselho de dar 70% a 80% da RAM ao buffer pool não se aplica. Esse número presume servidor dedicado a banco.
- Se o dataset InnoDB inteiro é menor que a RAM disponível, não adianta dar mais que o dataset ao buffer pool. Meça:

```sql
SELECT ROUND(SUM(data_length+index_length)/1024/1024) AS mb
FROM information_schema.tables WHERE engine='InnoDB';
```

## Onde editar no cPanel sem perder o arquivo

Em servidor com WHM, a interface **Edit SQL Configuration** (WHM » SQL Services) edita o `/etc/my.cnf` direto, conforme a [documentação oficial do cPanel](https://docs.cpanel.net/whm/sql-services/edit-sql-configuration/). É conveniente, mas a interface não substitui o backup.

Antes de qualquer alteração, pela linha de comando:

```bash
cp -a /etc/my.cnf /root/my.cnf.$(date +%F-%H%M)
ls -l /root/my.cnf.*
```

Um detalhe que custa caro: altere **uma variável ou um grupo coeso por vez**, reinicie, observe. Se você mudar sete coisas e o serviço cair, você não sabe qual foi, e a bissecção manual em produção é pior que o problema original.

## As variáveis que importam, e o porquê de cada uma

Nem toda mudança exige parar o serviço. `innodb_buffer_pool_size` é dinâmica no MySQL 5.7+ e no MariaDB 10.2+ (o resize acontece em background, em múltiplos de `innodb_buffer_pool_chunk_size × innodb_buffer_pool_instances`; acompanhe `Innodb_buffer_pool_resize_status`). `max_connections`, `wait_timeout`, `interactive_timeout`, `tmp_table_size` e `max_heap_table_size` também são `SET GLOBAL`. Vale lembrar que `wait_timeout` e `interactive_timeout` só valem para conexões abertas depois do `SET GLOBAL`: as sessões vivas mantêm o valor herdado na conexão.

```sql
SET GLOBAL innodb_buffer_pool_size = 2684354560;
SHOW GLOBAL STATUS LIKE 'Innodb_buffer_pool_resize_status';
```

Reinício é necessário só para as estáticas: `innodb_buffer_pool_instances`, `innodb_log_file_size` (em versões recentes do MySQL tornou-se dinâmica; confirme no manual da versão instalada antes de assumir. No MariaDB trate como estática, o redimensionamento exige parada do serviço), `skip_name_resolve`, `innodb_page_size`. O fluxo que reduz risco é: testar em runtime, confirmar a melhora, só então escrever no `my.cnf` para persistir, porque `SET GLOBAL` não sobrevive ao restart.

### innodb_buffer_pool_size define quanto do banco cabe na RAM

É a cache de páginas de dados e índices do InnoDB. Toda leitura que não está nela vira I/O de disco. É a única variável com impacto de ordem de grandeza na maioria dos servidores de hospedagem. Defina como o resultado do orçamento acima, não como percentual decorado.

### innodb_buffer_pool_instances só ajuda com pool grande

Divide o pool em instâncias para reduzir contenção de mutex sob concorrência. Só faz sentido com pool grande: cada instância deve ficar com pelo menos 1 GB. Com um pool de 2 GB, duas instâncias; com 512 MB, deixe em 1. Em versões recentes do MySQL o valor é ajustado automaticamente quando o pool é pequeno.

### max_connections multiplica o seu pior caso de memória

É o multiplicador do seu pior caso de memória. Subir para 500 porque apareceu `Too many connections` normalmente troca um erro visível por um swap invisível. Dimensione pelo número de workers PHP que podem abrir conexão simultânea, somado a cron e backup, com folga. Se o estouro vem de conexões ociosas, o problema são os timeouts, não o limite.

### wait_timeout e interactive_timeout devolvem slots presos por conexão ociosa

`wait_timeout` fecha conexões não interativas ociosas; `interactive_timeout` vale para clientes que setaram a flag interativa (o cliente `mysql` do terminal, por exemplo). Scripts PHP que esquecem de fechar a conexão ficam segurando thread e buffers até o timeout. Reduzir de 28800 segundos (8 horas, o padrão histórico) para algo na casa dos 120 a 300 segundos devolve slots e memória. Cuidado com dois efeitos colaterais: conexões persistentes (`mysqli` com `p:`) passam a ser derrubadas no meio do ciclo, e jobs longos de importação precisam setar o valor por sessão.

### tmp_table_size e max_heap_table_size decidem se a tabela temporária vai para disco

Devem ser iguais: a tabela temporária em memória é limitada pelo menor dos dois. Quando estoura, vai para disco. Acompanhe `Created_tmp_disk_tables` contra `Created_tmp_tables`. Subir esses valores sem corrigir a consulta que faz `GROUP BY` sem índice só move o custo de disco para RAM, multiplicado por conexão.

## Medir a mesma consulta antes e depois

Sem medição, tuning é superstição. O protocolo mínimo, com a consulta que o slow query log já apontou:

### Capture a linha de base da consulta

```sql
SET profiling = 1;
SELECT /* consulta pesada real */ ...;
SHOW PROFILES;
SHOW PROFILE FOR QUERY 1;
```

`SHOW PROFILE` está depreciado no MySQL moderno em favor do Performance Schema, mas continua útil e disponível em muitas versões em produção. A alternativa portável é cronometrar com o próprio cliente e repetir a execução várias vezes.

### Registre a razão entre leituras lógicas e leituras de disco

```sql
SHOW GLOBAL STATUS LIKE 'Innodb_buffer_pool_read%';
```

Dois contadores importam. `Innodb_buffer_pool_read_requests` é o total de leituras lógicas de página. `Innodb_buffer_pool_reads` é a fração que precisou ir ao disco porque a página não estava no pool. A razão entre os dois é o indicador que você acompanha ao mexer no pool. São contadores acumulados desde o start: anote o valor antes e depois da janela, trabalhe com a diferença, nunca com o absoluto.

### Repita a medição com o pool já aquecido

Se aplicou por `SET GLOBAL`, o pool continua quente, mas um resize para cima entrega páginas vazias: espere `Innodb_buffer_pool_resize_status` ficar ocioso e rode a carga por alguns minutos antes de comparar. Se precisou reiniciar por causa de uma variável estática, o pool está frio e o aquecimento domina a medição. Em qualquer dos casos compare: tempo da consulta, diferença de `Innodb_buffer_pool_reads` no intervalo, e `free -m` em pico.

Se a consulta não melhorou e os `reads` continuam altos com um pool maior que o dataset, o gargalo não é memória. É plano de execução. Volte ao `EXPLAIN`.

## Caminho de reversão quando o serviço não sobe

Tenha isto pronto em outra aba antes de reiniciar.

### Leia o error log antes de chutar a causa

```bash
systemctl status mysql -l
tail -n 50 /var/lib/mysql/$(hostname).err
grep -i -E 'error|cannot|unknown variable' /var/log/mysqld.log | tail -20
```

O caminho do log varia conforme `log_error` no `my.cnf` e a distribuição. Os erros típicos: `unknown variable` (variável removida na versão instalada, ou escrita na seção errada), `Cannot allocate memory` (buffer pool maior que a RAM livre) e `InnoDB: mmap(...) failed`.

### Restaure o arquivo anterior a partir do backup com timestamp

```bash
cp -a /root/my.cnf.2026-09-30-1412 /etc/my.cnf
systemctl start mysql
```

É por isso que o backup com timestamp vem antes da edição. Restaurar leva segundos; reconstruir a configuração de memória com o site fora leva o tempo que você não tem.

### Valide a sintaxe sem subir o serviço

```bash
# MySQL 8.0.16 ou superior
mysqld --validate-config --user=mysql

# MariaDB (padrão do cPanel) e MySQL antigo
mysqld --help --verbose --user=mysql >/dev/null
my_print_defaults --mysqld
```

`--validate-config` foi introduzida no MySQL 8.0.16 e não existe no MariaDB: no stack padrão do WHM/cPanel, que entrega MariaDB, a flag retorna `unknown option`. O fallback é `mysqld --help --verbose`, que também falha ao encontrar diretiva inválida, e `my_print_defaults --mysqld`, que mostra exatamente qual valor o servidor vai ler depois de resolver `my.cnf`, `!includedir` e os arquivos da distribuição.

### --skip-grant-tables recupera acesso perdido, não corrige erro de memória

Subir com `--skip-grant-tables` serve para recuperar acesso perdido, não para corrigir erro de configuração de memória. Ele desabilita a verificação de privilégios: qualquer um que alcance a porta entra como root. Se precisar mesmo, pare o serviço, suba com `--skip-grant-tables --skip-networking`, resolva, pare de novo e suba normal. Nunca deixe nesse estado por mais do que a operação exige.

## O que não resolver com my.cnf

Antes de aumentar o buffer pool, confirme que o problema é cache miss e não consulta ruim. Um `SELECT` com `ORDER BY` em coluna sem índice continua lendo a tabela inteira com qualquer tamanho de pool: você só troca I/O de disco por CPU e memória. Um índice correto costuma reduzir mais tempo de resposta que qualquer ajuste de configuração, e não custa RAM por conexão.

A sequência que funciona é: slow query log aponta a consulta, `EXPLAIN` aponta a varredura, o índice resolve o caso específico, e só então o `my.cnf` ajusta o comportamento agregado sob concorrência. Inverter essa ordem gasta RAM para esconder um problema que volta na próxima campanha de tráfego.

