Basi della sicurezza
Supabase "max client connections reached", spiegato
Supabase "max client connections reached": il pooler non ha posto per un altro client. La porta nella tua stringa di connessione decide il limite.

In breve
- "max client connections reached" su Supabase arriva da Supavisor, il pooler tra la tua app e il suo database. Ha già tutti i client che accetta: 200 sul piano gratuito in modalità transazione, porta 6543.
- In modalità sessione, porta 5432 sull'indirizzo del pooler, il limite è la dimensione del pool, 15 di default, e ogni client tiene la sua connessione al database finché non si scollega. Un'app serverless con quella stringa viene respinta al suo sedicesimo client.
- Sposta il codice serverless sulla porta 6543, crea il suo client del database una sola volta con un pool di 1 e chiudi gli strumenti rimasti collegati. Un pool più grande non alza il limite di client e si prende connessioni che servono ad Auth.
La tua app funziona bene da settimane. Poi qualcosa porta gente, un lancio o un post condiviso, e le pagine che leggono dal tuo database cominciano a mostrare un errore mentre la home page si carica ancora. Nei log delle funzioni del tuo hosting c'è una riga:
(EMAXCONN) max client connections reached, limit: 200
Oppure, su un'app che si collega in modalità sessione, questa:
(EMAXCONNSESSION) max clients reached in session mode - max clients are limited to pool_size: 15
Lo incontri su un'app con un server suo: un'app Next.js fatta con v0, Cursor o
Claude Code che legge il database con Prisma o Drizzle, un'app Replit con un
server Express, una Edge Function che apre una sua connessione a Postgres. Una
pagina che chiama solo supabase.from(…) passa invece dalla Data API, che ha
connessioni sue.
Il consiglio che trovi per primo su "max client connections reached" in Supabase, compresa la fine dell'articolo di aiuto di Supabase sulla versione Postgres di questo errore, è passare a una dimensione di calcolo più grande. Per un'app molto visitata a volte è giusto. Sul piano gratuito la soluzione può essere un numero di porta. Prima di pagare qualsiasi cosa, guarda quale dei due messaggi hai ricevuto e quale porta usa la tua stringa di connessione. I due limiti li fissano cose diverse, e solo uno dei due sale con il prezzo.
Che cosa significa "max client connections reached" su Supabase?
Supavisor, il pooler di connessioni che sta tra la tua app e il tuo database Supabase, ha già tutti i client collegati che accetta, e ha respinto il successivo.
Un client, qui, è una connessione aperta dal tuo codice: un client del database
in una copia del tuo server in esecuzione. Il messaggio è di Supavisor stesso,
dal file max_connections_error.ex nel suo codice sorgente, e arriva alla tua
app come errore Postgres con la gravità FATAL e il codice XX000. Le librerie
mostrano questo involucro in modi diversi, ma le parole sono quelle sopra.
Immagina il tuo database come una cucina con un bancone e un numero fisso di sgabelli. Ogni sgabello è una connessione a Postgres, il database del tuo progetto Supabase, e una richiesta di dati ha bisogno di uno sgabello per tutto il tempo della sua ordinazione. Supavisor è l'addetto all'ingresso. Decide chi si siede dove, e tiene un'area d'attesa per chi è già entrato e non sta ancora mangiando. Il messaggio vuol dire che la lista dell'addetto è piena.
Quale limite hai raggiunto?
Te lo dicono le parole dell'errore, e anche la porta alla fine della tua stringa di connessione.
| Cosa vedi | Chi l'ha inviato | Cosa conta | Sul piano gratuito |
|---|---|---|---|
(EMAXCONN) max client connections reached, limit: … | Supavisor in modalità transazione, porta 6543 | i client collegati al pooler nello stesso momento | 200 |
(EMAXCONNSESSION) max clients reached in session mode … | Supavisor in modalità sessione, porta 5432 sull'host del pooler | i client, con il tetto alla dimensione del pool | 15 |
remaining connection slots are reserved for roles with the SUPERUSER attribute | Postgres stesso | le connessioni al database | 60 |
sorry, too many clients already | Postgres stesso | tutte le connessioni, comprese le riservate | 60 |
I numeri vengono dalla tabella della guida di Supabase sul calcolo, per Nano, la
dimensione su cui gira il piano gratuito. Micro, la dimensione a pagamento più
piccola, ha gli stessi tre. I due messaggi di Postgres vengono dal codice
sorgente di Postgres e portano il codice 53300; Postgres 15 scrive il primo
come remaining connection slots are reserved for non-replication superuser connections.
Nella cucina, le ultime due righe sono gli sgabelli stessi che finiscono. Le prime due sono l'addetto che non fa passare nessun altro dalla porta.
La tua stringa di connessione dice da quale porta sei entrato. Sta nelle
variabili d'ambiente del tuo server, spesso come DATABASE_URL, e la guida di
Supabase alla connessione mostra ogni tipo:
…@db.[PROJECT-REF].supabase.co:5432/postgresè una connessione diretta, che passa oltre l'addetto e va dritta a uno sgabello.…@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgresè il pooler in modalità sessione.…@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgresè il pooler in modalità transazione.
Perché un'app Supabase resta senza connessioni?
Perché qualcosa apre connessioni più in fretta di quanto le restituisca, e le funzioni serverless, secondo la descrizione stessa di Supabase, aprono molte connessioni di breve durata.
Una funzione su Vercel, su Netlify o nelle Edge Functions di Supabase gira in tante copie quante ne chiede il traffico, e ogni copia attiva tiene il proprio client del database. La guida di Supabase alla connessione fa il conto per Postgres.js, una delle librerie Postgres più diffuse: apre di default fino a 10 connessioni per copia, e secondo la guida qualche decina di istanze basta a esaurire il pool.
La modalità sessione si riempie per prima. L'addetto ti dà uno sgabello e lo tieni finché non te ne vai, che tu mangi o no. Le FAQ di Supabase su Supavisor lo dicono chiaramente: una volta che il pooler ha assegnato una connessione diretta a un client, questa resta a quel client finché non la cede di sua volontà. Quindi l'addetto può far entrare solo tante persone quanti sgabelli ha per quella stringa di connessione, ed è per questo che il messaggio della modalità sessione nomina la dimensione del pool. Il codice di Supavisor controlla proprio questo: in modalità sessione un nuovo client viene respinto appena quelli già collegati raggiungono la dimensione del pool. Quindici sgabelli, e il sedicesimo client resta fuori dalla porta, per quanto tranquilli siano i primi quindici.
La modalità transazione fa entrare molta più gente. L'addetto ti fa sedere per un'ordinazione, una sola transazione, e passa lo sgabello al successivo appena è finita, così 200 client possono dividersi una manciata di connessioni. Ha comunque un'area d'attesa di dimensione fissa, e un'ondata di copie di funzioni che aprono più client ciascuna la riempie.
Anche cose fuori dalla tua app occupano sgabelli: uno strumento per database come TablePlus o DBeaver rimasto aperto, un'automazione in n8n o Make con un passaggio Postgres, il tuo portatile che fa girare l'app in sviluppo con la stringa di produzione, un job di backup. Ognuno è un client della stringa che gli hai dato.
Una query lenta tiene lo sgabello più a lungo. Se i tuoi log mostrano anche
canceling statement due to statement timeout, sistema prima quella query,
perché ogni secondo in cui gira è un secondo con lo sgabello occupato.
Quell'errore ha la sua guida.
Guarda chi sta tenendo le connessioni
Chiedi a Postgres, poi alla dashboard. Postgres elenca ogni connessione che ha aperta, e la dashboard di Supabase conta i client del pooler.
Nel SQL Editor, questa query conta le connessioni per ruolo, per l'app che le ha aperte e per quello che stanno facendo:
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;
Il ruolo ti dice chi è. La guida di Supabase sulla gestione delle connessioni li elenca:
| Ruolo | Chi è |
|---|---|
authenticator | la Data API, da cui passa ogni chiamata supabase.from(…) |
supabase_auth_admin | Auth, il servizio che fa accedere i tuoi utenti |
supabase_storage_admin | Storage |
postgres | la dashboard e gli strumenti esterni, Prisma e psql compresi |
| un ruolo che hai creato | chiunque abbia ricevuto da te la password di quel ruolo |
Un mucchio di connessioni postgres nello stato idle, con un
application_name che riconosci, è un client seduto su uno sgabello senza
niente davanti. idle in transaction è lo stato da guardare per primo: secondo
la guida, quasi sempre vuol dire che l'applicazione ha dimenticato di
confermare o annullare, e la sessione tiene i suoi lock finché resta aperta.
Per il pooler stesso, apri Observability nella dashboard. Il report
Shared Pooler (Supavisor) Client Connections conta i suoi client nel tempo.
La guida avverte che questi report mostrano il dato del loro ultimo
aggiornamento, e pg_stat_activity è la vista in diretta.
Come risolvere "max client connections reached" su Supabase
Sposta il codice serverless in modalità transazione, dai una connessione a ogni sua copia e tieni la modalità sessione per i lavori che hanno bisogno di una sessione intera. Fallo in quest'ordine.
1. Usa il Transaction pooler per le funzioni serverless. Nel tuo progetto
Supabase premi Connect in cima alla pagina, scegli Transaction pooler e
copia la stringa. Finisce con :6543/postgres. Mettila nell'ambiente del tuo
server al posto della vecchia, con la password del tuo database dove la stringa
dice [YOUR-PASSWORD].
La modalità transazione non tiene niente tra una transazione e l'altra, quindi i prepared statement vanno disattivati. La guida di Supabase dà l'impostazione per libreria:
| Libreria | Impostazione |
|---|---|
| Postgres.js, Drizzle | prepare: false |
| Prisma | pgbouncer=true nella stringa di connessione |
| asyncpg | statement_cache_size=0 |
2. Crea il client una volta sola, con un pool di uno. Un client creato dentro l'handler della richiesta è una nuova connessione a ogni richiesta. La guida di Supabase dice di crearlo una volta in cima al file, fuori da qualsiasi handler, e di limitare il suo pool a 1, perché tutte le invocazioni su quell'istanza attiva condividono il client:
import postgres from 'postgres'
export const sql = postgres(process.env.DATABASE_URL, {
max: 1,
prepare: false,
ssl: 'require',
})
Per Prisma lo stesso consiglio è connection_limit=1 nella stringa di
connessione, dalla guida di Supabase alla risoluzione dei problemi con Prisma.
Se hai fatto l'app con Cursor, Claude Code o v0, è una modifica breve da
descrivergli: il file che crea il client del database, la nuova stringa e
queste due impostazioni.
3. Tieni la modalità sessione per un lavoro lungo. Una migrazione, un
pg_dump, uno strumento che apri a mano: ognuno è una sola sessione che vuole
tenersi lo sgabello. La guida di Supabase li manda a una connessione diretta,
oppure alla modalità sessione su una rete senza IPv6, ed è così che si collega
un backup che gira sui runner di GitHub.
4. Chiudi quello che hai lasciato aperto. Esci dallo strumento per database, ferma le esecuzioni di prova dell'automazione e togli la stringa di produzione dal tuo portatile. Una connessione che non riesci a chiudere dal suo capo si può terminare dal SQL Editor. Questa query elenca quelle che tengono una transazione aperta:
select pid, usename, application_name, query_start, query
from pg_stat_activity
where state = 'idle in transaction';
Poi select pg_terminate_backend(pid);, con il pid di quell'elenco, termina
la sessione. Postgres annulla ciò che la sua transazione aperta aveva scritto
senza confermare, quindi leggi la sua colonna query prima di terminarla.
5. Poi guarda la dimensione di calcolo. Se i client sono tutti traffico vero, si dividono le connessioni come devono e sono comunque più di 200, il limite sale con la dimensione: Small consente 400 client del pooler e Medium 600, secondo la tabella di calcolo di Supabase. La sua knowledge base dice che i limiti di client del pooler condiviso sono fissi e cambiano solo con una dimensione di calcolo più grande, e la sua guida sul calcolo dice che un cambio di solito comporta meno di 2 minuti di fermo.
Devo alzare la dimensione del pool?
Non per risolvere questo. In modalità transazione la dimensione del pool non cambia affatto il limite di client, e in entrambe le modalità decide quante delle connessioni proprie del tuo database il pooler può prendersi.
La dimensione del pool è il numero di sgabelli che l'addetto può assegnare, e la cucina ne ha 60 sul piano gratuito. Le FAQ di Supabase la definiscono come il numero massimo di connessioni dirette che il pooler può mantenere per ogni combinazione di utente, database e modalità, quindi due stringhe di connessione con un utente o una modalità diversi hanno ciascuna un pool di quella dimensione. Le stesse 60 servono la Data API, Auth e Storage, e Storage si collega tramite Supavisor con un pool suo. L'avvertimento delle FAQ: se Supavisor usa la maggior parte delle connessioni disponibili, rischi di lasciare altri server, come Auth, senza accesso al tuo database. Auth è il servizio che fa accedere i tuoi utenti.
La loro regola pratica è tenere il pooler sotto il 40% delle connessioni se la tua app usa anche la Data API, e spingersi verso l'80% solo se non la usa.
In modalità sessione un pool più grande fa entrare davvero più client, uno
sgabello ciascuno. Così la fila si sposta dalla porta dell'addetto alla cucina.
Quando lì finiscono gli sgabelli, Postgres risponde remaining connection slots are reserved… al servizio che chiede subito dopo, e può essere Auth.
La stringa di connessione salta le tue policy
Una stringa di connessione è una password, e l'utente che contiene di solito è
postgres, che secondo la guida di Supabase su Row Level Security ha
bypassrls. Ogni policy che hai scritto viene saltata per ogni query che quella
stringa invia.
Questo cambia quello che il codice del tuo server deve fare. Una pagina che
legge con supabase.from(…) e la tua chiave publishable viene filtrata riga per
riga dalle tue policy. La stessa pagina spostata in una route del server con
Prisma o Drizzle legge ogni riga della tabella, e l'unica cosa tra un utente e
le righe di un altro è il where che aggiunge la tua route. Se sposti pagine in
una route del server per aggirare questo errore, controlla prima di pubblicare
che ognuna filtri per l'utente che ha fatto l'accesso.
La stringa non va mai neanche in una variabile il cui nome inizia con VITE_ o
NEXT_PUBLIC_. Quei prefissi mettono il valore nel codice che ogni visitatore
scarica, e
che cosa fanno quei due prefissi ha un
articolo suo. Un browser non può aprire una connessione a Postgres, quindi una
stringa di connessione nel frontend non fa funzionare niente e consegna la
password del database a chiunque apra il tuo sito.
Se una delle tue tabelle risponde a una richiesta senza accesso, e se una chiave segreta che riconosce si trova nel codice che il tuo sito invia, sono due dei nove controlli della scansione gratuita di Reeve. Legge la tua app online come fa il browser di un visitatore, ci mette circa 20 secondi e non chiede un account.
Saperlo quando succede di nuovo
Questo errore torna quando torna il traffico, e l'ora di punta raramente è un'ora che passi a leggere i log delle funzioni.
Reeve Monitor controlla la tua app online da fuori:
- se risponde, ogni 60 secondi, e ogni 15 finché è giù
- fino a 10 pagine in più, lette per le parole che devono esserci e quelle che non devono esserci, come "Qualcosa è andato storto"
- un messaggio via email, Telegram, Slack o webhook, con uno screenshot e un log conservati 30 giorni, così sai quale pagina è caduta e quando
- tutti e nove i controlli di sicurezza ogni ora
- un report mensile, in linguaggio semplice, di quello che ha visto
Reeve Care tiene una copia del tuo database Supabase di prima della prossima modifica che ci farai:
- una copia cifrata secondo una pianificazione, sullo spazio di archiviazione di Reeve nell'UE, fuori dal tuo account Supabase
- ogni copia verificata prima che conti, contando le righe di ogni tabella
- anche i tuoi file caricati, appena colleghi una credenziale di Storage
- un ripristino in un clic, con una copia di sicurezza dello stato attuale presa prima
- tutto quello che fa Monitor
Cosa fare oggi
Cosa fare
- Leggi l'errore e la porta:
(EMAXCONN)sulla6543è il limite di client del Transaction pooler, e(EMAXCONNSESSION)sulla5432all'indirizzo del pooler è la dimensione del pool. - Conta chi tiene le connessioni con
pg_stat_activity, e chiudi gli strumenti e le esecuzioni di prova rimasti collegati. - Punta il codice serverless sulla stringa del Transaction pooler, disattiva i prepared statement e crea il client una volta sola con un pool di 1.
- Tieni la dimensione del pool dentro i riferimenti del 40% e dell'80% di Supabase, perché Auth e la Data API attingono alle stesse connessioni.
- Controlla che ogni route del server che usa la stringa di connessione filtri per l'utente che ha fatto l'accesso, visto che nessuna policy lo fa per quella stringa.
Parti dalla stringa di connessione nell'ambiente del tuo server: la sua porta ti dice quale metà di questo articolo ti riguarda. Se nel risolvere sposti pagine in una route del server, la checklist di sicurezza in 10 minuti copre cosa guardare prima di metterle online.
FAQ
Che cosa significa "max client connections reached" su Supabase?
Supavisor, il pooler tra la tua app e il tuo database Supabase, ha già tutti i client collegati che accetta e ne ha rifiutato un altro. In modalità transazione, porta 6543, il limite lo fissa la dimensione di calcolo: 200 sul piano gratuito. Il messaggio arriva alla tua app come errore FATAL con il codice XX000 e il prefisso (EMAXCONN).
Perché ricevo "max clients reached in session mode" con pochi utenti?
In modalità sessione ogni client tiene la sua connessione al database finché non si scollega, quindi Supavisor ammette solo tanti client quanto la dimensione del pool, 15 di default. Una funzione serverless apre un client in ogni sua copia in esecuzione, e una manciata di copie basta a riempirlo. Usa la stringa del Transaction pooler, porta 6543, per il codice serverless.
Alzare la dimensione del pool risolve "max client connections reached"?
Non in modalità transazione, dove il limite di client viene dalla dimensione di calcolo. La dimensione del pool è quante delle connessioni proprie del database il pooler può aprire, sulle stesse 60 del piano gratuito che usano Auth, Storage e la Data API. Supabase consiglia di tenere il pooler sotto il 40% di queste se la tua app usa anche la Data API.
Che differenza c'è tra la porta 5432 e la 6543 su Supabase?
Sull'indirizzo del pooler, 5432 è la modalità sessione, in cui un client tiene la sua connessione al database finché resta collegato, e 6543 la modalità transazione, in cui i client si alternano su connessioni condivise, una transazione alla volta. Supabase consiglia 6543 per le funzioni serverless ed edge, e la modalità sessione o una connessione diretta per i lavori lunghi come migrazioni e pg_dump.
Che cosa significa "remaining connection slots are reserved" su Supabase?
Postgres stesso ha finito le connessioni normali e tiene le ultime per i superutenti. Conta ogni connessione: le tue dirette, quelle del pooler e quelle della Data API, di Auth e di Storage. Sul piano gratuito il totale è 60. Scopri chi le occupa con pg_stat_activity prima di cambiare qualsiasi impostazione.