Pular para o conteúdo

Noções de segurança

Supabase "max client connections reached", explicado

Supabase "max client connections reached": o pooler não tem lugar para mais um cliente. A porta da sua string de conexão define o limite.

Vlad Tkachenko14 min de leitura
Um balcão comprido com uma pessoa em cada banqueta, saindo do quadro, e uma fila na porta cuja primeira pessoa foi recusada.

Em resumo

  • "max client connections reached" no Supabase vem do Supavisor, o pooler que fica entre o seu app e o banco de dados dele. Ele já tem tantos clientes quanto aceita: 200 no plano gratuito em modo transação, porta 6543.
  • Em modo sessão, porta 5432 no endereço do pooler, o limite é o tamanho do pool, 15 por padrão, e cada cliente fica com a sua conexão ao banco até se desconectar. Um app serverless nessa string é recusado no seu décimo sexto cliente.
  • Passe o código serverless para a porta 6543, crie o cliente do banco uma única vez com um pool de 1 e feche as ferramentas que você deixou conectadas. Um pool maior não aumenta o limite de clientes e ainda toma conexões de que o Auth precisa.

O seu app funciona bem há semanas. Aí alguma coisa traz movimento, um lançamento ou um post que foi compartilhado, e as páginas que leem do seu banco de dados começam a mostrar um erro enquanto a página inicial ainda carrega. Nos logs de funções da sua hospedagem há uma linha:

(EMAXCONN) max client connections reached, limit: 200

Ou, num app que se conecta em modo sessão, esta:

(EMAXCONNSESSION) max clients reached in session mode - max clients are limited to pool_size: 15

Você encontra isso num app com servidor próprio: um app Next.js feito com v0, Cursor ou Claude Code que lê o banco pelo Prisma ou pelo Drizzle, um app do Replit com um servidor Express, uma Edge Function que abre a sua própria conexão ao Postgres. Uma página que só chama supabase.from(…) passa pela Data API, que tem conexões próprias.

O conselho que você encontra primeiro para "max client connections reached" no Supabase, inclusive no fim do próprio artigo de ajuda do Supabase sobre a versão do Postgres desse erro, é passar para um tamanho de computação maior. Para um app com muito movimento, às vezes é o certo. No plano gratuito a solução pode ser um número de porta. Antes de pagar qualquer coisa, veja qual das duas mensagens você recebeu e qual porta a sua string de conexão usa. Os dois limites são definidos por coisas diferentes, e só um deles sobe com o preço.

O que significa "max client connections reached" no Supabase?

O Supavisor, o pooler de conexões que fica entre o seu app e o seu banco de dados do Supabase, já tem tantos clientes conectados quanto aceita, e recusou o próximo.

Um cliente, aqui, é uma conexão aberta a partir do seu código: um cliente de banco de dados numa cópia do seu servidor que está rodando. A mensagem é do próprio Supavisor, do arquivo max_connections_error.ex no código-fonte dele, e chega ao seu app como um erro do Postgres com a gravidade FATAL e o código XX000. As bibliotecas exibem essa embalagem de jeitos diferentes, mas as palavras são as de cima.

Imagine o seu banco de dados como uma cozinha com um balcão e um número fixo de banquetas. Cada banqueta é uma conexão ao Postgres, o banco de dados do seu projeto Supabase, e um pedido de dados precisa de uma banqueta enquanto o pedido durar. O Supavisor é o recepcionista na porta. Ele decide quem senta onde, e mantém uma área de espera para quem já entrou e ainda não está comendo. A mensagem quer dizer que a lista do recepcionista está cheia.

Qual limite você atingiu?

As palavras do erro dizem, e a porta no fim da sua string de conexão também.

O que você vêQuem enviouO que é contadoNo plano gratuito
(EMAXCONN) max client connections reached, limit: …Supavisor em modo transação, porta 6543clientes conectados ao pooler ao mesmo tempo200
(EMAXCONNSESSION) max clients reached in session mode …Supavisor em modo sessão, porta 5432 no host do poolerclientes, com teto no tamanho do pool15
remaining connection slots are reserved for roles with the SUPERUSER attributeo próprio Postgresconexões ao banco60
sorry, too many clients alreadyo próprio Postgrestodas as conexões, inclusive as reservadas60

Os números vêm da tabela do guia de computação do Supabase, para o Nano, o tamanho em que roda o plano gratuito. O Micro, o menor tamanho pago, tem os mesmos três. As duas mensagens do Postgres vêm do código-fonte do Postgres e trazem o código 53300; o Postgres 15 escreve a primeira como remaining connection slots are reserved for non-replication superuser connections.

Na cozinha, as duas últimas linhas são as próprias banquetas acabando. As duas primeiras são o recepcionista, que não deixa mais ninguém passar pela porta.

A sua string de conexão diz por qual porta você entrou. Ela fica nas variáveis de ambiente do seu servidor, muitas vezes como DATABASE_URL, e o guia de conexão do Supabase mostra cada tipo:

  • …@db.[PROJECT-REF].supabase.co:5432/postgres é uma conexão direta, que passa pelo recepcionista e vai direto a uma banqueta.
  • …@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgres é o pooler em modo sessão.
  • …@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgres é o pooler em modo transação.

Por que um app Supabase fica sem conexões?

Porque alguma coisa abre conexões mais rápido do que as devolve, e as funções serverless, pela própria descrição do Supabase, abrem muitas conexões de vida curta.

Uma função na Vercel, na Netlify ou nas Edge Functions do Supabase roda em tantas cópias quanto o tráfego pede, e cada cópia ativa guarda o seu próprio cliente de banco de dados. O guia de conexão do Supabase faz a conta para o Postgres.js, uma das bibliotecas de Postgres mais comuns: por padrão ele abre até 10 conexões por cópia, e segundo o guia algumas dezenas de instâncias bastam para esgotar o pool.

O modo sessão enche primeiro. O recepcionista te dá uma banqueta e você fica com ela até ir embora, comendo ou não. O FAQ do Supabase sobre o Supavisor diz isso com todas as letras: depois que o pooler atribui uma conexão direta a um cliente, ela fica com esse cliente até ele abrir mão dela por conta própria. Então o recepcionista só consegue deixar entrar tantas pessoas quanto banquetas tem para aquela string de conexão, e é por isso que a mensagem do modo sessão cita o tamanho do pool. O código do Supavisor verifica exatamente isso: em modo sessão, um cliente novo é recusado assim que os já conectados chegam ao tamanho do pool. Quinze banquetas, e o décimo sexto cliente fica do lado de fora, por mais quietos que estejam os quinze primeiros.

O modo transação deixa entrar muito mais gente. O recepcionista te senta para um pedido, uma única transação, e passa a banqueta para o próximo assim que ela termina, então 200 clientes podem dividir um punhado de conexões. Mesmo assim ele tem uma área de espera de tamanho fixo, e uma leva de cópias de funções que abrem vários clientes cada uma a enche.

Coisas fora do seu app também ocupam banquetas: uma ferramenta de banco de dados como o TablePlus ou o DBeaver que ficou aberta, uma automação no n8n ou no Make com uma etapa de Postgres, o seu próprio notebook rodando o app em desenvolvimento com a string de produção, uma rotina de backup. Cada um é um cliente da string que recebeu.

Uma consulta lenta segura a banqueta por mais tempo. Se os seus logs também mostram canceling statement due to statement timeout, corrija essa consulta primeiro, porque cada segundo em que ela roda é um segundo com a banqueta ocupada. Esse erro tem o seu próprio guia.

O modo sessão dá a cada cliente uma conexão até ele ir embora, então o tamanho do pool é também o limite de clientes. O modo transação empresta as conexões uma transação por vez.

Veja quem está segurando as conexões

Pergunte ao Postgres e depois ao painel. O Postgres lista cada conexão que tem aberta, e o painel do Supabase conta os clientes do pooler.

No SQL Editor, esta consulta conta as conexões pelo papel e pelo app que as abriu, e pelo que elas estão fazendo:

select usename, application_name, state, count(*)
from pg_stat_activity
where backend_type = 'client backend'
group by usename, application_name, state
order by count(*) desc;

O papel diz quem é. O guia do Supabase sobre o gerenciamento de conexões lista cada um:

PapelQuem é
authenticatora Data API, por onde passa cada chamada a supabase.from(…)
supabase_auth_admino Auth, o serviço que faz o login dos seus usuários
supabase_storage_admino Storage
postgreso painel e as ferramentas externas, Prisma e psql incluídos
um papel que você criouquem quer que tenha recebido de você a senha desse papel

Uma pilha de conexões postgres no estado idle, com um application_name que você reconhece, é um cliente sentado numa banqueta sem nada na frente. idle in transaction é o estado para olhar primeiro: segundo o guia, ele quase sempre significa que a aplicação esqueceu de confirmar ou desfazer, e a sessão segura os seus bloqueios enquanto continuar aberta.

Para o próprio pooler, abra Observability no painel. O relatório Shared Pooler (Supavisor) Client Connections conta os clientes dele ao longo do tempo. O guia avisa que esses relatórios mostram o número da última atualização, e o pg_stat_activity é a visão ao vivo.

Como corrigir "max client connections reached" no Supabase

Passe o código serverless para o modo transação, dê uma conexão a cada cópia dele e deixe o modo sessão para os trabalhos que precisam de uma sessão inteira. Faça nessa ordem.

1. Use o Transaction pooler para as funções serverless. No seu projeto Supabase, clique em Connect no topo da página, escolha Transaction pooler e copie a string. Ela termina em :6543/postgres. Coloque-a no ambiente do seu servidor no lugar da antiga, com a senha do seu banco onde a string diz [YOUR-PASSWORD].

O modo transação não guarda nada entre transações, então os prepared statements precisam estar desligados. O guia do Supabase dá a configuração por biblioteca:

BibliotecaConfiguração
Postgres.js, Drizzleprepare: false
Prismapgbouncer=true na string de conexão
asyncpgstatement_cache_size=0

2. Crie o cliente uma vez só, com um pool de um. Um cliente criado dentro do handler da requisição é uma conexão nova a cada requisição. O guia do Supabase diz para criá-lo uma vez no topo do arquivo, fora de qualquer handler, e limitar o pool dele a 1, porque todas as invocações nessa instância ativa compartilham o cliente:

import postgres from 'postgres'

export const sql = postgres(process.env.DATABASE_URL, {
  max: 1,
  prepare: false,
  ssl: 'require',
})

Para o Prisma, o mesmo conselho é connection_limit=1 na string de conexão, segundo o guia de solução de problemas do Prisma do Supabase. Se você fez o app com Cursor, Claude Code ou v0, é uma mudança curta de descrever para ele: o arquivo que cria o cliente do banco, a string nova e essas duas configurações.

3. Deixe o modo sessão para um trabalho longo. Uma migração, um pg_dump, uma ferramenta que você abre à mão: cada um é uma única sessão que quer ficar com a sua banqueta. O guia do Supabase manda esses para uma conexão direta, ou para o modo sessão numa rede sem IPv6, e é assim que se conecta um backup que roda nos runners do GitHub.

4. Feche o que você deixou aberto. Saia da ferramenta de banco de dados, pare as execuções de teste da automação e tire a string de produção do seu notebook. Uma conexão que você não consegue fechar pela ponta dela pode ser encerrada pelo SQL Editor. Esta consulta lista as que mantêm uma transação aberta:

select pid, usename, application_name, query_start, query
from pg_stat_activity
where state = 'idle in transaction';

Depois, select pg_terminate_backend(pid);, com o pid dessa lista, encerra a sessão. O Postgres desfaz o que a transação aberta dela tinha escrito sem confirmar, então leia a coluna query dela antes de encerrar.

5. Só então olhe o tamanho de computação. Se os clientes são todos tráfego de verdade, dividem as conexões como deveriam e mesmo assim passam de 200, o limite sobe com o tamanho: o Small permite 400 clientes no pooler e o Medium 600, segundo a tabela de computação do Supabase. A base de conhecimento dele diz que os limites de clientes do pooler compartilhado são fixos e só mudam com um tamanho de computação maior, e o guia de computação dele diz que uma troca costuma trazer menos de 2 minutos de indisponibilidade.

Devo aumentar o tamanho do pool?

Não para resolver isso. Em modo transação o tamanho do pool não muda em nada o limite de clientes, e nos dois modos ele decide quantas das conexões do próprio banco o pooler pode pegar.

O tamanho do pool é o número de banquetas que o recepcionista pode distribuir, e a cozinha tem 60 no plano gratuito. O FAQ do Supabase o define como o número máximo de conexões diretas que o pooler pode manter para cada combinação de usuário, banco e modo, então duas strings de conexão com um usuário ou um modo diferente ganham cada uma um pool desse tamanho. As mesmas 60 atendem a Data API, o Auth e o Storage, e o Storage se conecta pelo Supavisor com um pool próprio. O aviso do FAQ: se o Supavisor usar a maior parte das conexões disponíveis, você corre o risco de deixar outros servidores, como o Auth, sem acesso ao seu banco. O Auth é o serviço que faz o login dos seus usuários.

A regra prática dele é manter o pooler abaixo de 40% das conexões se o seu app também usa a Data API, e só ir em direção a 80% se não usa.

Em modo sessão, um pool maior deixa entrar mais clientes, sim, uma banqueta para cada um. Isso leva a fila da porta do recepcionista para dentro da cozinha. Quando as banquetas acabam ali, o Postgres responde remaining connection slots are reserved… ao serviço que pedir em seguida, e esse pode ser o Auth.

O tamanho do pool sai das mesmas conexões que a Data API, o Auth e o Storage usam. Se crescer o bastante, um deles fica sem lugar.

A string de conexão pula as suas políticas

Uma string de conexão é uma senha, e o usuário que vai nela costuma ser postgres, que segundo o próprio guia de Row Level Security do Supabase tem bypassrls. Cada política que você escreveu é pulada em cada consulta que essa string envia.

Isso muda o que o código do seu servidor precisa fazer. Uma página que lê por supabase.from(…) com a sua chave publishable é filtrada linha a linha pelas suas políticas. A mesma página levada para uma rota de servidor com Prisma ou Drizzle lê todas as linhas da tabela, e a única coisa entre um usuário e as linhas de outro é o where que a sua rota acrescenta. Se você levar páginas para uma rota de servidor para escapar desse erro, confira antes de publicar que cada uma filtra pelo usuário logado.

A string também nunca vai numa variável cujo nome comece com VITE_ ou NEXT_PUBLIC_. Esses prefixos colocam o valor no código que todo visitante baixa, e o que esses dois prefixos fazem tem um post próprio. Um navegador não consegue abrir uma conexão com o Postgres, então uma string de conexão no frontend não faz nada funcionar e entrega a senha do banco a qualquer pessoa que abra o seu site.

Se alguma das suas tabelas responde a uma requisição sem login, e se uma chave secreta que ele reconhece está no código que o seu site envia, são duas das nove verificações do scan gratuito da Reeve. Ele lê o seu app no ar como o navegador de um visitante lê, leva uns 20 segundos e não precisa de conta.

Saber quando acontecer de novo

Esse erro volta quando o tráfego volta, e a hora de pico raramente é uma hora que você passa lendo logs de funções.

Reeve Monitor verifica o seu app no ar por fora:

  • se ele está no ar, a cada 60 segundos, e a cada 15 enquanto estiver fora
  • até 10 páginas a mais, lidas em busca de palavras que precisam estar lá e palavras que não podem, como "Algo deu errado"
  • uma mensagem por e-mail, Telegram, Slack ou webhook, com uma captura de tela e um log guardados por 30 dias, para você saber qual página caiu e quando
  • as nove verificações de segurança a cada hora
  • um relatório mensal, em linguagem simples, do que ele viu

Reeve Care guarda uma cópia do seu banco de dados Supabase de antes da próxima mudança que você fizer nele:

  • uma cópia criptografada em uma programação, no armazenamento próprio da Reeve na UE, fora da sua conta do Supabase
  • cada cópia verificada antes de contar, contando as linhas de cada tabela
  • seus arquivos enviados também, assim que você conectar uma credencial do Storage
  • uma restauração com um clique, com uma cópia de segurança do estado atual feita antes
  • tudo o que o Monitor faz

O que fazer hoje

O que fazer

  • Leia o erro e a porta: (EMAXCONN) na 6543 é o limite de clientes do Transaction pooler, e (EMAXCONNSESSION) na 5432 no endereço do pooler é o tamanho do pool.
  • Conte quem está segurando as conexões com pg_stat_activity, e feche as ferramentas e as execuções de teste que ficaram conectadas.
  • Aponte o código serverless para a string do Transaction pooler, desligue os prepared statements e crie o cliente uma vez só com um pool de 1.
  • Mantenha o tamanho do pool dentro das referências de 40% e 80% do Supabase, porque o Auth e a Data API usam as mesmas conexões.
  • Confira que cada rota de servidor que usa a string de conexão filtra pelo usuário logado, já que nenhuma política faz isso para essa string.

Comece pela string de conexão no ambiente do seu servidor: a porta dela diz qual metade deste post é a sua. Se você estiver levando páginas para uma rota de servidor como parte da correção, o checklist de segurança de 10 minutos cobre o que olhar antes de colocar no ar.

Perguntas frequentes

O que significa "max client connections reached" no Supabase?

O Supavisor, o pooler entre o seu app e o seu banco de dados do Supabase, já tem tantos clientes conectados quanto aceita e recusou mais um. Em modo transação, porta 6543, quem define o limite é o tamanho de computação: 200 no plano gratuito. A mensagem chega ao seu app como um erro FATAL com o código XX000 e o prefixo (EMAXCONN).

Por que recebo "max clients reached in session mode" com poucos usuários?

Em modo sessão cada cliente fica com a sua conexão ao banco até se desconectar, então o Supavisor só admite tantos clientes quanto o tamanho do pool, 15 por padrão. Uma função serverless abre um cliente em cada cópia dela que está rodando, e um punhado de cópias enche isso. Use a string do Transaction pooler, porta 6543, para o código serverless.

Aumentar o tamanho do pool resolve "max client connections reached"?

Não em modo transação, em que o limite de clientes vem do tamanho de computação. O tamanho do pool é quantas das conexões do próprio banco o pooler pode abrir, das mesmas 60 do plano gratuito que o Auth, o Storage e a Data API usam. O Supabase recomenda manter o pooler abaixo de 40% delas se o seu app também usa a Data API.

Qual a diferença entre a porta 5432 e a 6543 no Supabase?

No endereço do pooler, 5432 é o modo sessão, em que um cliente fica com a sua conexão ao banco enquanto continuar conectado, e 6543 é o modo transação, em que os clientes se revezam em conexões compartilhadas, uma transação por vez. O Supabase recomenda 6543 para funções serverless e edge, e o modo sessão ou uma conexão direta para trabalhos longos como migrações e pg_dump.

O que significa "remaining connection slots are reserved" no Supabase?

O próprio Postgres ficou sem conexões comuns e está guardando as últimas para superusuários. Ele conta todas as conexões: as suas diretas, as do pooler e as da Data API, do Auth e do Storage. No plano gratuito o total é 60. Descubra quem as ocupa com pg_stat_activity antes de mudar qualquer configuração.

Escrito por

Vlad Tkachenko

Fundador da Reeve

Passo meus dias olhando apps criados com Lovable, Bolt, v0, Cursor e Replit, e a curta lista de erros que aparecem neles sem parar.

Mais sobre o autor

Leia depois

Todos os artigos

Faça backup do seu banco Supabase antes da próxima mudança

O Reeve guarda uma cópia criptografada em horários programados e a restaura para você se algo quebrar.

Ver backups do Supabase

Verificação externa automatizada, não uma auditoria completa. A ausência de achados não é garantia de segurança.