Skip to content

Quantas conexões seu Rails precisa? Dimensionando e observando o pool do Active Record em 2026

TL;DR

O tamanho do pool é o teto de trabalho simultâneo no banco, não um chute. Some processos web, filas e o overlap do deploy, e compare com o max_connections do Postgres. No Rails 8.1 o antigo pool: passou a se chamar max_connections. Meça a saturação com checkout_wait.active_record e só então decida se precisa de PgBouncer.

Threads, fibers e workers mudam a conta do pool. Com o novo evento checkout_wait.active_record, dá para medir a saturação sem monkey-patch no ConnectionPool. Este post fecha essa conta, configura o database.yml de um app Rails 8.1 e decide quando o PgBouncer entra.

Publicado em 14 min de leitura

Também disponível em English

Compartilhar

Cada thread, fiber ou worker de um app Rails quer uma conexão com o Postgres. O número que você coloca em max_connections — o antigo pool: — não é um parâmetro de performance que se ajusta no feeling. É o teto de quanto trabalho simultâneo aquele processo pode fazer no banco. Estoure esse teto e o pedido espera. Estoure o checkout_timeout e a espera vira um ActiveRecord::ConnectionTimeoutError no meio do expediente.

Até novembro de 2026, medir isso pedia monkey-patch no ConnectionPool. Na This Week in Rails de 6 de novembro, o Rails passou a emitir o evento checkout_wait.active_record: ele dispara só quando um checkout precisa esperar porque o pool está cheio, traz essa espera como duração e, se der timeout, leva o erro no payload. Este post fecha a conta que quase ninguém faz — a mesma que muda quando você troca Puma por Falcon ou Pitchfork, e quando o Solid Queue entra no mesmo Postgres —, configura o database.yml de um app Rails 8 de verdade e liga essa métrica antes de decidir se o PgBouncer entra na história.

1. A conta que ninguém faz

Um processo Rails tem um pool por banco configurado. Puma em modo clustered, Pitchfork e o processo do Solid Queue são processos diferentes, cada um com o seu próprio pool. Dois workers do Puma com max_connections: 5 não compartilham cinco conexões: são dez. Some as réplicas do Kamal, e some de novo no momento do deploy, quando a release antiga e a nova convivem.

A fórmula é esta:

conexões no Postgres ≈
    (processos web × max_connections do primary)
  + (processos web × max_connections de cache e de cable,
     se forem o mesmo servidor)
  + (processos de fila × max_connections do queue
     + max_connections do primary, porque o job também
     consulta a aplicação)
  × (e durante o deploy, conte a release antiga e a nova)

Um exemplo concreto, de um único VPS, nada exótico:

  • Puma com 2 workers e 5 threads. Cada worker abre o pool primary e, no Solid Trio, os pools de cache e cable. São 2 × (5 + 5 + 5) = 30 conexões.
  • Um processo do Solid Queue com 5 threads. Os workers precisam do banco queue e, para rodar o job, também do primary. São pelo menos mais 10.
  • Total em operação normal: 40 conexões. No deploy com overlap, 80. O padrão do Postgres é max_connections = 100, e algumas delas são reservadas para o superusuário. A margem que parecia confortável cabe numa mão.

A conta muda com o app server, e é por isso que este post continua o comparativo entre Puma, Falcon e Pitchfork.

Puma. Cada thread pode segurar uma conexão. O max_connections do primary deve ser pelo menos RAILS_MAX_THREADS. O database.yml gerado já faz essa amarração; o erro clássico é subir as threads do Puma e esquecer o teto do pool.

Falcon. Os pedidos rodam como fibers no mesmo thread. Com config.active_support.isolation_level = :fiber — e essa linha precisa existir, senão todas as fibers compartilham o mesmo lease e o mesmo query cache —, cada fiber pode ter a sua conexão. Desde o Rails 7.2, um find comum devolve a conexão no fim da query, então o pool não precisa ter o tamanho do máximo de fibers simultâneas. O que estoura o pool é o checkout permanente: ActiveRecord::Base.connection segura a conexão até o fim do pedido. Em um app com fibers, isso é:

# config/application.rb, em um app que roda no Falcon
config.active_support.isolation_level = :fiber
config.active_record.permanent_connection_checkout = :disallowed

O :disallowed transforma o checkout permanente em erro já no desenvolvimento, que é exatamente o que você quer encontrar antes do horário de pico.

Pitchfork. Cada worker é um processo que atende um pedido de cada vez, no estilo do Unicorn. Um max_connections: 1 ou 2 por worker basta. O perigo está no produto: 32 workers em 3 réplicas já são dezenas de conexões, mesmo com pool mínimo.

Action Cable. Se o cable roda no mesmo Puma, o pool cable entra na conta de cada worker. Se roda em processo separado, entra como mais uma linha na soma.

O teto de verdade não é o do Rails, é o do Postgres: SHOW max_connections. Em uma instância pequena de RDS, esse número costuma ser baixo, calculado em função da memória. Tudo o que passa disso é recusado com FATAL: too many connections, que é um erro diferente do timeout do pool e, em geral, pior: afeta até o rails console e o processo que você mandaria investigar o problema.

2. Configurando o database.yml de verdade

No Rails 8.1, o tamanho do pool passou a se chamar max_connections. O pool: ainda funciona, mas está depreciado, e o aviso do framework aponta remoção no 8.2. Os dois juntos, com valores diferentes, impedem o boot com um RuntimeError. Se você adicionar min_connections e deixar o pool: antigo, o boot também recusa: na hora de adotar as opções novas, troque o nome da chave no mesmo commit.

# config/database.yml
default: &default
  adapter: postgresql
  encoding: unicode
  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  checkout_timeout: 5
  idle_timeout: 300
  # NAT Gateways da AWS encerram conexões ociosas em 350s.
  # O padrão de keepalive é 600, então em AWS isso precisa baixar.
  keepalive: 300
  # Recicla conexões antigas no próximo checkin, com jitter
  # para não aposentá-las todas de uma vez.
  max_age: <%= 1.hour.to_i %>

production:
  primary: &primary_production
    <<: *default
    host: <%= ENV.fetch("DB_HOST") %>
    database: rubyinsights_production
    username: rubyinsights
    password: <%= ENV["DATABASE_PASSWORD"] %>
  cache:
    <<: *primary_production
    database: rubyinsights_production_cache
    migrations_paths: db/cache_migrate
    max_connections: <%= ENV.fetch("CACHE_MAX_CONNECTIONS") { 5 } %>
  queue:
    <<: *primary_production
    database: rubyinsights_production_queue
    migrations_paths: db/queue_migrate
    max_connections: <%= ENV.fetch("JOB_CONCURRENCY") { 5 } %>
  cable:
    <<: *primary_production
    database: rubyinsights_production_cable
    migrations_paths: db/cable_migrate
    max_connections: <%= ENV.fetch("CABLE_MAX_CONNECTIONS") { 5 } %>

O que cada chave faz, na prática:

  • max_connections é o teto daquele pool, naquele processo. Padrão 5. Pode ser nil ou -1 para ilimitado, o que quase nunca é o que você quer em produção.
  • min_connections é o piso que o pool tenta manter aberto (padrão 0). Serve para evitar o custo de abrir conexão no primeiro pedido depois de um período ocioso.
  • checkout_timeout é quanto uma thread ou fiber espera por uma conexão livre antes de levantar ActiveRecord::ConnectionTimeoutError. Padrão 5 segundos. Aumentar esse número não cria conexões: só deixa o pedido pendurado por mais tempo.
  • idle_timeout é quanto uma conexão ociosa vive no pool antes do reaper desconectá-la. Padrão 300 segundos. 0 a mantém para sempre.
  • keepalive manda um sinal periódico em conexões ociosas para o servidor — e para qualquer NAT no caminho — não as encerrar. Padrão 600 segundos, alto demais atrás de um NAT Gateway da AWS, cujo idle timeout é 350.
  • max_age aposenta a conexão no próximo checkin, depois daquela idade. Padrão infinito. Útil para reciclar conexões quando há um load balancer ou uma troca de DNS pela frente. O pool_jitter (padrão 0.2) espalha essas aposentadorias para elas não coincidirem.
  • reaping_frequency é de quanto em quanto tempo o reaper roda, chamando reap e flush. Se você baixar o idle_timeout, o reaper precisa ser pelo menos tão frequente quanto ele.

Os quatro bancos do Solid Trio — primary, cache, queue, cable — são quatro pools. Mesmo quando são quatro databases no mesmo Postgres, cada um conta contra o max_connections do servidor. Tratar "pool 5" como "cinco conexões no total" é o engano que fecha a margem do exemplo da seção 1.

3. Medindo a saturação

O evento checkout_wait.active_record não dispara em todo checkout. Só quando o pool está cheio e alguém precisa esperar. A duração do evento é essa espera, em milissegundos. O payload traz o próprio pool em :connection_pool e o teto de espera em :checkout_timeout. Se a espera estoura o teto, o payload inclui :exception com o ActiveRecord::ConnectionTimeoutError.

Isso é o suficiente para um initializer que alimenta o seu APM e um alerta:

# config/initializers/connection_pool_metrics.rb
ActiveSupport::Notifications.subscribe("checkout_wait.active_record") do |event|
  pool = event.payload[:connection_pool]
  pool_name = pool.db_config.name.to_s
  tags = ["pool:#{pool_name}"]

  StatsD.distribution("active_record.checkout_wait", event.duration, tags: tags)

  if event.payload[:exception]
    StatsD.increment("active_record.checkout_timeout", tags: tags)
    Rails.logger.warn(
      "[connection_pool] checkout timed out after #{event.duration.round(1)}ms " \
      "(checkout_timeout=#{event.payload[:checkout_timeout]}s, pool=#{pool_name})"
    )
  end
end

StatsD.distribution é o estilo Datadog; no OpenTelemetry o equivalente é um histogram no meter, com o atributo db.pool.name. O que importa é separar os pools: um wait no queue é um problema de concorrência de jobs, um wait no primary é um problema de pedidos web, e misturar os dois no mesmo gráfico esconde os dois.

Dois alertas bastam para começar:

  1. Qualquer incremento de active_record.checkout_timeout em uma janela de 5 minutos. Isso já é pedido falhando, não é degradação.
  2. p95 de active_record.checkout_wait acima de 100 ms por 10 minutos. O pool ainda entrega conexões, mas está saturado: o próximo pico vira timeout.

Esperas curtas e ocasionais são normais. Uma fila constante de waits é o pool dizendo que está pequeno, ou que alguém está segurando conexão além da hora — o diagnóstico da seção 6 separa os dois casos.

4. PgBouncer ou não?

O pool do Active Record vive dentro de um processo. Ele não ajuda quando o problema é a soma de muitos processos contra um teto baixo no RDS. Aí entra o PgBouncer: os processos Rails abrem muitas conexões cliente contra o Bouncer, e o Bouncer mantém um conjunto menor de conexões servidor contra o Postgres.

Há três modos, e só dois entram na conversa:

  • Session. Uma conexão servidor fica com o cliente enquanto a sessão Rails existir. Todas as funcionalidades do Postgres funcionam, inclusive locks de sessão e PREPARE. O ganho de multiplexação é pequeno, porque a conexão só volta ao pool quando o cliente desconecta.
  • Transaction. A conexão servidor é devolvida no fim de cada transação. É o modo que realmente reduz conexões no Postgres. Também é o modo que quebra estado de sessão.
  • Statement. Como o transaction, mas proíbe transações de mais de um statement. Não use com o Rails.

O que quebra no modo transaction é específico, e vale uma lista curta:

  • Advisory locks de sessão (pg_advisory_lock) não sobrevivem, porque a próxima transação pode cair em outra conexão servidor. Locks de linha, inclusive o FOR UPDATE SKIP LOCKED que o Solid Queue usa para reivindicar jobs, funcionam normalmente.
  • PREPARE e DEALLOCATE em SQL não funcionam. Prepared statements no protocolo, que é o que o adapter pg do Rails usa, funcionam no PgBouncer 1.21 ou superior com max_prepared_statements diferente de zero — e nas versões recentes isso já vem ligado, com padrão 200.
  • LISTEN/NOTIFY de sessão, cursors WITH HOLD e tabelas temporárias que sobrevivem à transação também não. Se a sua aplicação depende de algum desses, o modo session é a escolha, ou o PgBouncer não é a ferramenta certa.

Na prática, um app Rails 8 com Solid Queue, Solid Cache e Solid Cable no mesmo Postgres se dá bem com o modo transaction, prepared statements de protocolo e o default_pool_size do Bouncer dimensionado para o teto que o RDS realmente aguenta. O max_connections do Rails pode até ficar mais folgado: ele passa a limitar conexões contra o Bouncer, não contra o Postgres.

O Rails aponta para o PgBouncer no database.yml (port: 6432, em geral). O Bouncer é que aponta para o Postgres, com um default_pool_size por database. Duas regras operacionais: não coloque o Bouncer na frente de uma conexão que precisa de sessão, e não compartilhe o mesmo default_pool_size entre um banco de fila ocupado e o primary se eles tiverem padrões de carga diferentes — o PgBouncer também tem pools por database, use-os.

5. Tabela de decisão por cenário

Os números abaixo são ponto de partida, não lei. O que manda é o checkout_wait depois de um dia de tráfego real.

Cenáriomax_connections por processoPgBouncerO que monitorar
Puma monolítico, um processo, 5 threads5, igual a RAILS_MAX_THREADSNão, a menos que o teto do Postgres já esteja apertadocheckout_wait no primary; pg_stat_activity
Falcon com fibersComece em 5–15, não no máximo de fibers; isolation_level = :fiber e checkout permanente :disallowedSó se muitos workers empurrarem o totalDuração de checkout_wait e conexões presas até o fim do pedido
Pitchfork, muitos workers1 ou 2 por workerSim, quando workers × réplicas se aproximam do tetoTotal de conexões no Postgres no pico e no deploy
Kamal com várias réplicasO mesmo por processo, multiplicado pelas réplicas, com folga para o overlap do deploySim, quando essa soma se aproxima do teto do RDSConexões totais contra max_connections do servidor
Solid Queue no mesmo PostgresPool do queue igual à concorrência dos workers, mais o primary que os jobs também usamModo transaction serve: Solid Queue usa FOR UPDATE SKIP LOCKEDcheckout_wait no queue e no primary, separados
RDS com teto baixoPools pequenos e explícitos em cada database do Solid TrioSim, modo transactionMétrica de conexões do RDS e qualquer checkout_timeout

Se a tabela puxa para o PgBouncer e você ainda não mediu um checkout_wait, meça primeiro. Um Bouncer colocado no escuro troca um problema que você não vê por dois.

6. Checklist de produção

O sintoma clássico aparece nos logs da aplicação:

ActiveRecord::ConnectionTimeoutError:
  could not obtain a connection from the pool within 5.000 seconds

Cinco segundos é o checkout_timeout padrão. O Postgres pode estar ocioso nesse exato momento: o timeout é do pool daquele processo, não do servidor. Antes de subir max_connections no escuro, percorra esta lista.

1. Confirme quem está esperando. O alerta de checkout_timeout e o p95 de checkout_wait, quebrados por pool, dizem se o problema é o web, a fila, o cache ou o cable.

2. Olhe o que o Postgres vê.

SELECT datname, usename, state, wait_event_type, wait_event,
       LEFT(query, 80) AS query, state_change, backend_start
  FROM pg_stat_activity
 WHERE backend_type = 'client backend'
 ORDER BY state, state_change;

O que você procura: quantas linhas existem contra SHOW max_connections, e quantas estão em idle in transaction. Uma transação aberta segura a conexão no Rails e a conexão no Postgres. A causa mais comum é trabalho lento dentro da transação: uma chamada HTTP a um terceiro, um upload, um job do Solid Queue que abre a transação no começo e só faz o commit depois de falar com um serviço externo.

3. Procure conexões presas no app. ActiveRecord::Base.connection (o checkout permanente) em um job ou em uma fiber; um Thread.new que toma uma conexão e não devolve. O permanent_connection_checkout = :disallowed da seção 1 também ajuda aqui, mesmo no Puma.

4. Confira a conta do deploy. Se os timeouts só aparecem durante o kamal deploy, você não tem um pool pequeno: tem overlap sem folga no teto do Postgres. PgBouncer, ou uma janela de max_connections do servidor que comporte duas releases, resolve; aumentar o pool de cada processo piora.

5. Não suba o checkout_timeout como correção. Isso só atrasa o erro. Se o pool está saturado, o pedido já está lento. A correção é devolver conexões mais cedo, ou aumentar o pool depois de refazer a soma da seção 1 contra o teto do servidor.

6. Deixe o statement_timeout do Postgres separado. Ele cancela uma query lenta. O checkout_timeout cancela a espera por uma conexão. São alavancas diferentes, e um não substitui o outro.

Quando a conta fecha, um GET comum num app bem dimensionado nem chega a emitir checkout_wait. O evento existe para o dia em que isso muda — um worker a mais, uma réplica nova, um job que passou a segurar transação — e você vê a saturação antes do primeiro 500.

Comece pela soma, passe o database.yml para max_connections, ligue o subscriber e viva uma semana com os dois alertas. Só então mexa no tamanho do pool ou coloque um PgBouncer na frente. Um pool que você não mede é um bug que você ainda não encontrou.

Fontes

  1. This Week in Rails: November 6, 2026 rubyonrails.org
  2. Rails Guides: Active Support Instrumentation guides.rubyonrails.org
  3. Rails Guides: Configuring Rails Applications — database pooling guides.rubyonrails.org
  4. ActiveRecord::ConnectionAdapters::ConnectionPool (Rails 8.1) api.rubyonrails.org
  5. Rails Guides: Multiple Databases with Active Record guides.rubyonrails.org
  6. rails/solid_queue github.com
  7. PgBouncer: Features www.pgbouncer.org
  8. PostgreSQL: Connection and Authentication www.postgresql.org
  9. AWS: NAT gateway troubleshooting (idle timeout) docs.aws.amazon.com

Perguntas frequentes

pool: ou max_connections: no Rails 8.1?

Use max_connections. O pool: ainda funciona, mas está depreciado no 8.1 e o aviso do framework aponta remoção no 8.2. Não configure os dois com valores diferentes, e não misture o pool: antigo com min_connections: os dois casos impedem o boot.

Preciso de um pool do tamanho do número de fibers no Falcon?

Não. Desde o Rails 7.2 um find comum devolve a conexão no fim da query. Configure isolation_level = :fiber e permanent_connection_checkout = :disallowed, comece com um pool de 5 a 15 e deixe o checkout_wait dizer se falta conexão. O que estoura o pool é o checkout permanente, não o número de fibers.

Por que tenho ConnectionTimeoutError se o Postgres ainda tem conexão livre?

O timeout é do pool daquele processo, não do servidor. Causas comuns: outro pool do Solid Trio comendo a conta, overlap de deploy, uma transação segura a conexão (idle in transaction) ou um checkout permanente. Olhe o checkout_wait quebrado por pool e o pg_stat_activity antes de subir o teto.

PgBouncer no modo transaction quebra o Solid Queue?

Não. O Solid Queue reivindica jobs com FOR UPDATE SKIP LOCKED, que é lock de linha e funciona no modo transaction. O que quebra nesse modo são advisory locks de sessão, PREPARE em SQL, LISTEN e tabelas temporárias que sobrevivem à transação. Prepared statements de protocolo funcionam no PgBouncer 1.21 ou superior.

O evento checkout_wait dispara em todo checkout?

Não. Ele só é emitido quando o pool está cheio e o checkout precisa esperar. A duração é essa espera, em milissegundos. Se estourar o checkout_timeout, o payload traz o ActiveRecord::ConnectionTimeoutError em :exception. Pedidos que pegam uma conexão livre não geram evento.

Como dimensionar com várias réplicas no Kamal?

Multiplique o consumo de um processo pelo número de réplicas e reserve folga para o overlap do deploy, quando duas releases convivem. Se essa soma se aproxima do teto do RDS, entre com PgBouncer em modo transaction; aumentar o pool de cada processo nessa hora só aperta o servidor.

Comentários

Faça login com GitHub para comentar.

Ainda não há comentários.