Como aumentar o timeout do MySQL no HestiaCP

O gerenciamento de banco de dados é um dos pilares críticos para a sustentação de qualquer painel de controle de hospedagem. No HestiaCP, o daemon do MySQL/MariaDB atua como o backplane central de dados, servindo tanto as tabelas internas do painel quanto as aplicações web dos clientes (como WordPress, frameworks PHP e APIs). Com o crescimento do volume de acessos e complexidade das transações, os limites e timeouts padrões configurados no banco de dados podem tornar-se gargalos operacionais.

No entanto, a modificação das variáveis do sistema deve ser feita com sólida compreensão teórica de seus valores padrão, sob o risco de degradar a estabilidade do servidor.

1. Motivos técnicos para ajustar os timeouts do MySQL#

A decisão de ajustar os tempos limite (timeouts) e a análise de consultas lentas no MySQL dentro de um servidor de produção HestiaCP baseia-se em fatores críticos de infraestrutura:

A. O erro de conceito comum sobre o wait_timeout#

O valor padrão do parâmetro wait_timeout no MySQL/MariaDB é de 28800 segundos (8 horas). Muitos administradores configuram erroneamente essa variável para valores baixos (como 30 segundos) acreditando estar aumentando a tolerância de execução.

• Redução de Timeout (wait_timeout = 600): Reduzir para 10 minutos (600 segundos) é útil em servidores com pouca memória RAM para forçar o fechamento de conexões inativas (idle), liberando threads do pool.
• Aumento de Timeout (wait_timeout = 86400): Aumentar para 24 horas (86400 segundos) é necessário apenas em cenários onde scripts em segundo plano realizam processamento de dados extremamente demorado e precisam manter conexões inativas abertas sem serem encerradas.

Configurar valores excessivamente baixos (como 30 segundos) fará com que conexões inativas de aplicações PHP persistentes ou pools de conexão sejam abortadas prematuramente, gerando os erros clássicos: PDOException: SQLSTATE[HY000] [2002] Connection refused ou MySQL server has gone away.

B. Esclarecimento sobre renovação de SSL (let's encrypt)#

Existe o mito de que a renovação de certificados SSL via Let's Encrypt (desafios HTTP-01 ou DNS-01) realiza transações demoradas no banco de dados. Na realidade, as queries disparadas pelo HestiaCP para atualizar metadados de domínio levam milissegundos. No entanto, o problema é indireto: se os limites de thread do MySQL forem atingidos e conexões inativas ficarem presas travando o pool de conexões (ou se o daemon cair por erro de configuração), os scripts do HestiaCP não conseguirão se conectar ao banco de dados interno e as rotinas automáticas de renovação falharão silenciosamente.

C. Melhor controle de queries lentas#

A variável long_query_time define o limite (em segundos) a partir do qual uma consulta SQL é registrada no arquivo slow-query.log. O padrão do MySQL é 10 segundos. Alterar para 30 segundos reduz o volume de logs em servidores muito carregados, mas para fins de otimização refinada, valores menores (como 1 a 2 segundos) são ideais para capturar gargalos antes que escalem.

2. Passo a passo para alteração dos parâmetros#

A configuração deve ser feita acessando o servidor Linux via SSH com privilégios de usuário root.

Passo 0: Pré-requisitos e backups obrigatórios#

Antes de modificar as configurações globais, crie cópias de segurança do arquivo de configuração ativo e analise se existem consultas ativas (desconsiderando conexões inativas ou em estado Sleep) que impeçam a reinicialização segura do banco:

# Backup do arquivo de configuração ativo (ajuste o caminho se necessário)
sudo cp /etc/mysql/mariadb.conf.d/50-server.cnf /etc/mysql/mariadb.conf.d/50-server.cnf.backup.$(date +%Y%m%d-%H%M%S)

# Verificar transações e conexões ativas no banco (ignorando Sleep)
sudo mysql -e "SELECT * FROM information_schema.processlist WHERE command != 'Sleep';"

Se houver queries complexas de escrita em execução, aguarde a finalização para evitar corrupção de tabelas ao reiniciar.

Passo 1: Localização do arquivo#

• HestiaCP (Debian/Ubuntu): Embora o arquivo my.cnf seja o ponto de entrada global do sistema, em instalações padrão do MariaDB via apt ele frequentemente contém apenas diretivas de inclusão (!includedir). A configuração real das variáveis do servidor deve ser editada no arquivo 50-server.cnf (sob a pasta mariadb.conf.d) dentro do bloco [mysqld].
• Sistemas RHEL/CentOS/Rocky Linux: my.cnf

Passo 2: Edição dos parâmetros coordenados#

Abra o arquivo de configuração ativo em seu editor de texto (por exemplo, no Debian/Ubuntu):

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Localize a seção [mysqld] e configure as variáveis de forma coordenada para garantir o comportamento desejado.

Configuração recomendada para AUMENTAR timeouts (Ambientes com scripts longos de importação):

[mysqld]
# Timeout para conexões não interativas (padrão: 28800 = 8h)
wait_timeout=86400

# Timeout para conexões interativas via CLI (padrão: 28800)
interactive_timeout=86400

# Limite para classificar queries como lentas (padrão: 10s)
long_query_time=10

# Timeout para obtenção de locks do InnoDB (evita travamento de transações)
innodb_lock_wait_timeout=120

# Limite de tempo de tentativa de conexão inicial
connect_timeout=10

Configuração recomendada para REDUZIR timeouts (Melhor uso de memória RAM em produção):

[mysqld]
# Timeout de 10 minutos (libera conexões órfãs ou mortas rapidamente)
wait_timeout=600
interactive_timeout=600
long_query_time=5
innodb_lock_wait_timeout=50

Salve e feche o arquivo (Ctrl+O, Enter, Ctrl+X).

Passo 3: Validação de sintaxe#

Nunca reinicie o serviço do banco de dados sem validar as alterações de sintaxe previamente. Erros de digitação farão com que o daemon falhe em iniciar:

# Validar arquivo de configuração (MySQL 8.0+)
sudo mysqld --validate-config

# Testar o parser de leitura padrão
sudo mysqladmin --print-defaults

Certifique-se de que não há erros de sintaxe impressos no console.

Passo 4: Reiniciando o serviço#

Se a validação retornar sucesso, reinicie o daemon de banco de dados:

sudo systemctl restart mysql

Passo 5: Verificação dos valores aplicados#

Confirme que os novos parâmetros foram devidamente carregados na memória do banco rodando queries de ambiente:

sudo mysql -e "SHOW VARIABLES LIKE 'wait_timeout';"
sudo mysql -e "SHOW VARIABLES LIKE 'interactive_timeout';"
sudo mysql -e "SHOW VARIABLES LIKE 'long_query_time';"

3. Roteiro de rollback de emergência#

Se o serviço do MySQL falhar ao reiniciar ou se suas aplicações começarem a perder conexões devido a um timeout inadequado:

1. Acesse o servidor e restaure o arquivo de backup criado anteriormente (ajustando o caminho conforme o arquivo ativo do seu sistema):

   # Para Debian/Ubuntu (instalação padrão do HestiaCP)
   sudo cp /etc/mysql/mariadb.conf.d/50-server.cnf.backup.* /etc/mysql/mariadb.conf.d/50-server.cnf

1. Valide as configurações restauradas:

   sudo mysqld --validate-config

1. Reinicie o banco de dados:

   sudo systemctl restart mysql

1. Verifique se o daemon está operando normalmente e escutando na porta padrão:

   sudo systemctl status mysql
   sudo ss -tulpn | grep -E 'mysql|mysqld'

4. Automação de configuração via CLI#

Para automatizar a configuração em lote, utilize expressões regulares seguras (que toleram espaçamentos variados ao redor do caractere =) para alterar as linhas existentes ou adicionar os parâmetros caso não existam no arquivo ativo (como o 50-server.cnf no Debian/Ubuntu):

# Definir o arquivo ativo do sistema (Debian/Ubuntu usa 50-server.cnf)
CONFIG_FILE="/etc/mysql/mariadb.conf.d/50-server.cnf"

# Substituição segura tolerando espaços
if grep -q "^\s*wait_timeout\s*=" "$CONFIG_FILE"; then
    sudo sed -i 's/^\(\s*wait_timeout\s*=\s*\).*/\186400/' "$CONFIG_FILE"
else
    echo "wait_timeout=86400" | sudo tee -a "$CONFIG_FILE"
fi

if grep -q "^\s*long_query_time\s*=" "$CONFIG_FILE"; then
    sudo sed -i 's/^\(\s*long_query_time\s*=\s*\).*/\110/' "$CONFIG_FILE"
else
    echo "long_query_time=10" | sudo tee -a "$CONFIG_FILE"
fi

Explicação operacional do sed:#

• s/^\(\swait_timeout\s=\s\)./\186400/: Localiza a linha contendo wait_timeout (tolerando espaços em branco no início e ao redor do =) e substitui o restante da linha pelo valor 86400, preservando a indentação e os espaçamentos originais capturados no primeiro grupo retroreferenciado \1.

5. Script completo de ajuste seguro#

Abaixo está o script completo para alteração e validação automatizada dos timeouts do MySQL, contendo tratamento de erros e rollback embutido:

#!/bin/bash
# increase_mysql_timeout.sh - Otimização segura de timeouts do MySQL
# ⚠️ Deve ser executado com privilégios de root (sudo)

set -e

NEW_WAIT_TIMEOUT=86400
NEW_LONG_QUERY_TIME=10

# Cores para terminal
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

log() { echo -e "${GREEN}[INFO]${NC} $1"; }
warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

# 1. Verificar permissões
[[ $EUID -ne 0 ]] && error "Execute este script como root (sudo)"

# 2. Detectar arquivo de configuração ativo no HestiaCP / OS
if [ -f /etc/mysql/mariadb.conf.d/50-server.cnf ]; then
    CONFIG_FILE="/etc/mysql/mariadb.conf.d/50-server.cnf"
elif [ -f /etc/mysql/my.cnf ]; then
    CONFIG_FILE="/etc/mysql/my.cnf"
else
    CONFIG_FILE="/etc/my.cnf"
fi

BACKUP="${CONFIG_FILE}.backup.$(date +%Y%m%d-%H%M%S)"

# 3. Criar backup
log "Efetuando backup da configuração ativa de ${CONFIG_FILE}..."
cp "$CONFIG_FILE" "$BACKUP"

# 4. Analisar concorrência atual
ACTIVE_QUERIES=$(mysql -e "SELECT COUNT(*) FROM information_schema.processlist WHERE command != 'Sleep'" -N)
if [[ $ACTIVE_QUERIES -gt 2 ]]; then
    warn "Detectadas ${ACTIVE_QUERIES} queries ativas em execução. Considere aguardar para reiniciar."
fi

# 5. Modificar ou adicionar wait_timeout (tolerando espaços)
log "Aplicando wait_timeout=${NEW_WAIT_TIMEOUT}..."
if grep -q "^\s*wait_timeout\s*=" "$CONFIG_FILE"; then
    sed -i "s/^\(\s*wait_timeout\s*=\s*\).*/\1${NEW_WAIT_TIMEOUT}/" "$CONFIG_FILE"
else
    echo "wait_timeout=${NEW_WAIT_TIMEOUT}" >> "$CONFIG_FILE"
fi

# 6. Modificar ou adicionar long_query_time (tolerando espaços)
log "Aplicando long_query_time=${NEW_LONG_QUERY_TIME}..."
if grep -q "^\s*long_query_time\s*=" "$CONFIG_FILE"; then
    sed -i "s/^\(\s*long_query_time\s*=\s*\).*/\1${NEW_LONG_QUERY_TIME}/" "$CONFIG_FILE"
else
    echo "long_query_time=${NEW_LONG_QUERY_TIME}" >> "$CONFIG_FILE"
fi

# 7. Validar a nova configuração
log "Validando integridade sintática do arquivo de configuração..."
if mysqld --validate-config 2>/dev/null; then
    log "Configuração validada com sucesso."
else
    warn "Erro de sintaxe detectado. Iniciando rollback automático..."
    cp "$BACKUP" "$CONFIG_FILE"
    error "Falha de validação. A configuração original foi restaurada."
fi

# 8. Reiniciar o serviço do MySQL
log "Reiniciando o serviço do banco de dados..."
systemctl restart mysql

# 9. Validar carregamento na memória
if systemctl is-active --quiet mysql; then
    log "✅ MySQL reiniciado e ativo!"
    log "Valores em memória pós-ajuste:"
    mysql -e "SHOW VARIABLES LIKE 'wait_timeout';"
    mysql -e "SHOW VARIABLES LIKE 'long_query_time';"
else
    warn "Falha ao iniciar o MySQL. Efetuando rollback automático de emergência..."
    cp "$BACKUP" "$CONFIG_FILE"
    systemctl restart mysql
    error "MySQL falhou ao iniciar. Backup restaurado com sucesso."
fi

Veja também

Infraestrutura Guia Definitivo de Troubleshooting de Let's Encrypt e SSL no DirectAdmin (CLI, CAA e Subdomínio WWW)

Infraestrutura Desincronização de handshake do MySQL em ambientes multi-tenant: cPanel, CloudLinux e CageFS

Infraestrutura Melhores painéis de controle Linux em 2026: cPanel vs DirectAdmin vs CyberPanel

Este post está licenciado sob CC BY-NC.