Mastodon ‘Database Connection Timeout’ em Instância Auto-Hospedada: Correção

Ao auto-hospedar uma instância do Mastodon, o serviço depende de um banco de dados PostgreSQL para armazenar postagens, contas e dados da timeline. Um erro “Database Connection Timeout” significa que os processos web ou de streaming do Mastodon não conseguem acessar o banco de dados dentro do limite de tempo configurado. Isso geralmente ocorre devido a esgotamento de recursos, pools de conexão mal configurados ou latência de rede entre o servidor de aplicação e o servidor de banco de dados. Este artigo explica as causas raiz desse erro de timeout e fornece correções passo a passo para restaurar a operação normal.

Por que o Mastodon Relata um Database Connection Timeout

O aplicativo Mastodon usa o framework Ruby on Rails com o ORM ActiveRecord para se comunicar com o PostgreSQL. Quando uma requisição web ou job em segundo plano tenta abrir uma conexão com o banco de dados, o sistema aguarda por um slot do pool ou handshake TCP. Se nenhum slot ficar disponível dentro da janela de timeout — padrão de 5 segundos — o Rails lança um ActiveRecord::ConnectionTimeoutError. Esse erro aparece nos logs como “could not obtain a database connection within 5.000 seconds” ou similar.

Causas Raiz Comuns

Três fatores causam a maioria dos timeouts:

• Esgotamento do pool de conexões: Cada processo do Mastodon — servidor web Puma, workers Sidekiq e streaming API — pega conexões de um pool local. Se o tamanho do pool for muito pequeno e todos os slots estiverem em uso, novas requisições entram em fila e eventualmente excedem o timeout.
• Limite de conexões do PostgreSQL atingido: O próprio banco de dados tem um limite máximo (padrão 100 conexões). Se o Mastodon mais outros clientes excederem esse limite, o PostgreSQL recusa novas conexões.
• Gargalos de rede ou recursos: Alto uso de CPU ou memória no servidor de banco de dados, ou um link de rede lento entre o contêiner do Mastodon e o host do banco de dados, pode atrasar o handshake além do timeout.

Passos para Corrigir o Database Connection Timeout

Estes passos assumem que você tem acesso SSH ao seu servidor Mastodon e pode editar o arquivo de configuração de ambiente — tipicamente .env.production no diretório do Mastodon. Você também precisa de acesso sudo para reiniciar serviços e modificar configurações do PostgreSQL.

1. Verifique o limite atual de conexões do PostgreSQL
   Execute sudo -u postgres psql -c "SHOW max_connections;" no servidor de banco de dados. O padrão é 100. Se sua instância atende mais de algumas dezenas de usuários ativos, aumente esse valor.
2. Aumente max_connections no postgresql.conf
   Edite /etc/postgresql//main/postgresql.conf. Encontre a linha max_connections = 100 e aumente para 200 ou mais. Por exemplo, max_connections = 300. Reinicie o PostgreSQL com sudo systemctl restart postgresql.
3. Verifique a configuração DB_POOL do Mastodon
   Abra .env.production no diretório home do Mastodon. Procure por DB_POOL. Se ausente, adicione DB_POOL=25. Esse valor não deve exceder max_connections dividido pelo número total de processos Mastodon. Para um único Puma e um processo Sidekiq, 25 é seguro.
4. Reinicie os serviços do Mastodon
   Execute systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming para carregar a nova configuração de pool. Se usar Docker Compose, execute docker-compose restart.
5. Monitore o uso de conexões
   Use sudo -u postgres psql -c "SELECT count() FROM pg_stat_activity;" para ver conexões ativas. Compare com o limite max_connections. Se a contagem permanecer próxima ao limite, você precisa de um pool maior ou mais recursos de banco de dados.
6. Reduza a concorrência do Sidekiq se necessário
   Em .env.production, verifique SIDEKIQ_CONCURRENCY. O padrão é 10. Cada worker concorrente usa uma conexão de banco de dados. Se você tem muitos processos Sidekiq, reduza a concorrência para 5 e teste.
7. Adicione um pooler de conexão de banco de dados como PgBouncer
   Se sua instância crescer além de 500 usuários, instale o PgBouncer. Ele atua como um proxy leve que reutiliza conexões de banco de dados. Configure o PgBouncer com um pool de tamanho 50 e defina DB_POOL do Mastodon como 5. Isso evita picos de conexão.

Se o Mastodon Ainda Tiver Problemas Após a Correção Principal

Timeout Persiste Após Aumentar max_connections e DB_POOL

Se o erro continuar, o servidor de banco de dados pode estar sobrecarregado. Verifique o uso de CPU e memória com htop ou top. Se o PostgreSQL estiver usando 100% de CPU, considere atualizar o hardware do servidor ou mover o banco de dados para uma máquina dedicada. Verifique também se o servidor Mastodon consegue alcançar o host do banco de dados na porta 5432 sem perda de pacotes. Execute ping -c 10 [ip-do-banco] e procure por pacotes perdidos.

Timeout de Conexão Afeta Apenas Jobs em Segundo Plano do Sidekiq

Os workers Sidekiq lidam com tarefas como entregar toots e processar mídia. Se eles excederem o timeout mas a interface web funcionar, o processo Sidekiq pode ter um REDIS_URL ou configuração de banco de dados separada. Certifique-se de que .env.production contenha o mesmo DATABASE_URL tanto para o Puma quanto para o Sidekiq. Verifique também se o Redis não está sobrecarregado — um Redis lento pode fazer o Sidekiq manter conexões de banco de dados por mais tempo que o esperado.

Erro Aparece Após Adicionar um Novo Serviço Mastodon

Se você adicionou recentemente um segundo processo Puma ou uma fila extra do Sidekiq, o número total de conexões de banco de dados pode exceder max_connections. Multiplique o número de processos pelos seus valores de DB_POOL. Por exemplo, dois processos Puma com DB_POOL=25 cada usam até 50 conexões. Adicione Sidekiq com concorrência 10 e você chega a 60. Certifique-se de que max_connections do PostgreSQL seja pelo menos 20% acima desse total.

Comparação: DB_POOL do Mastodon vs max_connections do PostgreSQL

Item	DB_POOL (Mastodon)	max_connections (PostgreSQL)
Descrição	Número máximo de conexões de banco de dados por processo Mastodon	Total máximo de conexões permitidas pelo servidor de banco de dados
Valor padrão	5 ou 10 dependendo da versão do Mastodon	100
Onde configurar	Arquivo .env.production	postgresql.conf
Efeito de valor muito baixo	Erros de timeout de conexão sob carga	Novas conexões rejeitadas após o limite ser atingido
Efeito de valor muito alto	Desperdiça memória; pode exceder o limite do PostgreSQL	Consome RAM; pode degradar o desempenho
Recomendado para instância pequena	10	100
Recomendado para instância média	25	200

Agora você pode diagnosticar e resolver erros “Database Connection Timeout” em sua instância Mastodon auto-hospedada ajustando as configurações max_connections e DB_POOL. Comece verificando o limite atual do PostgreSQL com pg_isready e o comando SHOW max_connections. Após aplicar as correções, monitore a contagem de conexões com pg_stat_activity para confirmar que o timeout não ocorre mais. Para estabilidade a longo prazo em instâncias maiores, considere implantar o PgBouncer para agrupar conexões de forma eficiente e evitar timeouts futuros.