Introdução ao Troubleshooting de ProxySQL
O ProxySQL é um proxy SQL de alta performance que atua como uma camada intermediária entre suas aplicações e o banco de dados. Ele é essencial para gerenciar conexões, realizar roteamento inteligente, balanceamento de carga e garantir a disponibilidade em ambientes de High Availability. No entanto, quando algo sai errado — seja um erro de conexão, latência inesperada ou falha na replicação — o diagnóstico pode se tornar complexo sem uma abordagem sistemática.
Este guia técnico detalha os passos práticos para identificar e resolver os erros mais comuns no ProxySQL, focando em ambientes Linux (Debian/Ubuntu/CentOS) com bancos de dados MySQL/MariaDB. Embora a lógica seja similar para outros proxies como o PgBouncer, as configurações específicas aqui são voltadas para o ecossistema SQL padrão.
1. Verificando o Estado do Serviço e Logs do Sistema
O primeiro passo em qualquer troubleshooting é confirmar se o serviço está ativo e rodando corretamente. O ProxySQL roda como um daemon em segundo plano, e falhas de inicialização podem ser silenciosas.
Inicie verificando o status do serviço usando o gerenciador de serviços da sua distribuição:
systemctl status proxysqlSe o serviço estiver inativo ou com erro, verifique os logs do sistema para identificar a causa raiz. Em distribuições baseadas em systemd, utilize o journald:
journalctl -u proxysql --no-pager -n 50Além disso, o ProxySQL gera logs próprios localizados geralmente em /var/log/proxysql.log. Este arquivo é crucial para identificar erros de configuração, falhas de conexão com os hosts backend e problemas de autenticação.
tail -f /var/log/proxysql.logProcure por mensagens contendo palavras-chave como ERROR, FATAL ou CRITICAL. Erros frequentes incluem permissão negada ao arquivo de dados, portas já em uso ou falha na leitura do arquivo de configuração inicial.
2. Diagnóstico via Interface MySQL (Admin Socket)
O grande diferencial do ProxySQL é sua interface administrativa exposta via protocolo MySQL na porta 6032. Isso permite que você faça perguntas ao proxy como se fosse um banco de dados, obtendo informações em tempo real sobre o estado das conexões e roteamento.
Conecte-se à interface admin usando o cliente MySQL padrão:
mysql -u admin -p --host 127.0.0.1 --port 6032A senha padrão é admin, a menos que tenha sido alterada na configuração. Uma vez dentro, você terá acesso a várias tabelas virtuais (sysinfo) e de configuração (mysql_servers, mysql_users). A primeira consulta útil é verificar as estatísticas gerais:
SELECT * FROM stats_mysql_connection_pool;Esta tabela mostra o status das conexões estabelecidas entre o ProxySQL e os servidores backend. Fique atento às colunas Status (ONLINE, LOGGED_OFF_HOST) e Type. Se você vir muitos hosts em LOGGED_OFF_HOST, isso indica que o ProxySQL está bloqueando conexões para um servidor backend devido a falhas consecutivas.
3. Troubleshooting de Conexões e Autenticação
Um dos erros mais comuns é a falha na autenticação ou conexão com o banco de dados backend. Isso pode ocorrer por credenciais incorretas no ProxySQL, restrições de host no MySQL/MariaDB ou problemas de rede.
3.1 Verificando Usuários e Senhas
No shell administrativo do ProxySQL, liste os usuários configurados:
SELECT * FROM mysql_users;Verifique se o username e o password_hash correspondem às credenciais no banco de dados real. Lembre-se que o ProxySQL armazena senhas criptografadas em SHA256. Se você atualizou a senha no MySQL, precisa atualizá-la também no ProxySQL ou usar o recurso de mysql_users com hash correto.
3.2 Testando Conectividade Manual
Se a autenticação falha, teste a conectividade de rede diretamente do servidor onde o ProxySQL está instalado:
mysql -u usuario -p -h host_backend -P 3306Se esta conexão falhar, o problema não é no ProxySQL, mas sim na rede, firewall ou configuração do banco de dados backend. Se funcionar, o erro provavelmente está na configuração do mysql_users no ProxySQL.
3.3 Habilitando Logs de Debug
Se o problema persistir, aumente o nível de verbosidade dos logs do ProxySQL para capturar detalhes da negociação de handshake:
SET mysql-log_errors="true";
LOAD MYSQL VARIABLES TO RUNTIME;
SAVE MYSQL VARIABLES TO DISK;Reproduza o erro e analise novamente o arquivo /var/log/proxysql.log. Logs detalhados mostrarão exatamente onde a conexão está sendo rejeitada.
4. Otimização de Queries e Tuning de RAM
Um dos benefícios do ProxySQL é a capacidade de otimizar queries através de regras de roteamento e caching. Problemas de performance muitas vezes estão ligados a queries mal escritas ou falta de índices no banco de dados.
4.1 Monitoramento de Queries Lentas
O ProxySQL possui uma tabela de estatísticas que registra o tempo de execução das queries:
SELECT * FROM stats_mysql_query_digest ORDER BY digest_text LIMIT 10;Esta consulta retorna as queries mais frequentes e suas estatísticas. Observe a coluna sum_time (tempo total) e count_star (número de execuções). Queries com alto tempo médio podem indicar a necessidade de otimização no lado do banco de dados, como a criação de índices adequados.
4.2 Tuning de RAM e Conexões
O ProxySQL é eficiente em uso de memória, mas pode sofrer se configurado incorretamente em VPSs com recursos limitados. O parâmetro mysql-max_connections define o número máximo de conexões simultâneas que o proxy pode gerenciar.
Se você estiver enfrentando erros de "Too many connections", ajuste este valor na configuração do ProxySQL:
SET mysql-max_connections=1000;
LOAD MYSQL VARIABLES TO RUNTIME;Além disso, monitore o uso de memória do processo proxysql. Em ambientes com pouca RAM, considere ajustar o tamanho das conexões em cache ou limitar o número de threads. Use comandos como top ou htop para monitorar o consumo:
ps aux | grep proxysql5. Gerenciamento de Replicação e Failover
O ProxySQL é frequentemente usado em configurações de mestre-escravo (master-slave) para garantir alta disponibilidade. Ele detecta automaticamente o estado dos servidores backend e roteia escritas para o mestre e leituras para os escravos.
5.1 Verificando o Status de Replicação
No shell admin, verifique a lista de servidores e seus estados:
SELECT hostgroup_id, hostname, port, status FROM mysql_servers;O campo status deve indicar ONLINE. Se um servidor escravo estiver desatualizado ou com replicação quebrada, o ProxySQL pode continuar enviando queries para ele, resultando em erros de consistência.
5.2 Configurando Hostgroups
Para garantir que escritas vão apenas para o mestre e leituras para os escravos, verifique a configuração dos hostgroups:
SELECT * FROM mysql_replication_hostgroups;Esta tabela mapeia quais hostgroups são usados para leitura (write_hostgroup) e escrita (read_only_hostgroup). Se houver um desajuste aqui, o roteamento será incorreto. Ajuste conforme necessário:
INSERT INTO mysql_replication_hostgroups (write_hostgroup, read_only_hostgroup, active) VALUES (10, 20, 1);
LOAD MYSQL VARIABLES TO RUNTIME;
SAVE MYSQL VARIABLES TO DISK;Neste exemplo, o hostgroup 10 é para escrita e o 20 para leitura. Recarregue as variáveis para aplicar a mudança em tempo real.
6. Backup Automático da Configuração
A configuração do ProxySQL reside na memória e no disco (um arquivo SQLite). É crucial fazer backups regulares desta configuração para permitir a recuperação rápida em caso de falha ou corrupção de dados.
O ProxySQL salva automaticamente a configuração no disco quando você executa o comando SAVE ... TO DISK. No entanto, é recomendável criar um script de backup externo que copie o arquivo de banco de dados SQLite:
cp /var/lib/proxysql/proxysql.db /backup/proxysql_backup_$(date +%F).dbConfigure um crontab para automatizar esse processo diariamente:
0 2 * * * cp /var/lib/proxysql/proxysql.db /backup/proxysql_backup_$(date +\%F).dbEste backup contém toda a configuração de usuários, roteamento e variáveis globais. Em caso de desastre, você pode restaurar este arquivo para recuperar o estado anterior do proxy.
7. Comparativo Rápido: ProxySQL vs PgBouncer
Embora ambos sejam proxies SQL, eles atendem a diferentes necessidades. O PgBouncer é amplamente utilizado para PostgreSQL, focando em pool de conexões eficiente e baixo overhead. O ProxySQL, por outro lado, oferece funcionalidades mais avançadas como roteamento baseado em conteúdo, cache de queries e monitoramento detalhado.
Se você está migrando de um ambiente com PgBouncer para o ProxySQL (ou usando ambos em stacks heterogêneas), esteja ciente de que a lógica de pooling é diferente. O ProxySQL mantém conexões persistentes ativas, enquanto o PgBouncer pode operar em modo transacional ou session. Ajuste suas aplicações conforme o modelo de conexão escolhido.
8. Boas Práticas e Conclusão
Para manter seu ProxySQL estável e performático, adote as seguintes práticas:
- Monitore constantemente: Use ferramentas como Prometheus e Grafana para visualizar as tabelas de estatísticas do ProxySQL.
- Teste mudanças em staging: Sempre aplique alterações de configuração em um ambiente de teste antes de ir para produção.
- Mantenha o software atualizado: Versões mais recentes do ProxySQL corrigem bugs críticos e melhoram a estabilidade.
- Documente suas regras: Mantenha um registro das regras de roteamento e filtros de queries aplicados.
O troubleshooting no ProxySQL exige uma abordagem em camadas: comece pelo serviço, passe pela interface admin, analise logs e, finalmente, otimize a configuração. Com as ferramentas e comandos apresentados neste guia, você estará preparado para resolver a maioria dos problemas comuns que surgem em ambientes de produção.
Lembre-se: a otimização contínua das queries e o monitoramento proativo são tão importantes quanto a resolução de erros reativos. Invista tempo na análise de stats_mysql_query_digest para identificar gargalos antes que eles afetem seus usuários finais.