Bases de la sécurité
Supabase "max client connections reached" expliqué
Supabase "max client connections reached" : le pooler n'a plus de place pour un client de plus. Le port de votre chaîne de connexion fixe la limite.

En bref
- "max client connections reached" sur Supabase vient de Supavisor, le pooler placé entre votre app et sa base de données. Il a déjà autant de clients qu'il en accepte : 200 sur le plan gratuit en mode transaction, port 6543.
- En mode session, port 5432 à l'adresse du pooler, la limite est la taille du pool, 15 par défaut, et chaque client garde sa connexion à la base jusqu'à ce qu'il se déconnecte. Une app serverless sur cette chaîne est refusée à son seizième client.
- Passez le code serverless sur le port 6543, créez son client de base de données une seule fois avec un pool de 1, et fermez les outils restés connectés. Un pool plus grand ne relève pas la limite de clients, et il prend des connexions dont Auth a besoin.
Votre app tourne sans souci depuis des semaines. Puis quelque chose amène du monde, un lancement ou un post partagé, et les pages qui lisent votre base de données se mettent à afficher une erreur pendant que la page d'accueil charge encore. Dans les logs de fonctions de votre hébergeur, il y a une ligne :
(EMAXCONN) max client connections reached, limit: 200
Ou, sur une app qui se connecte en mode session, celle-ci :
(EMAXCONNSESSION) max clients reached in session mode - max clients are limited to pool_size: 15
Vous la rencontrez sur une app qui a son propre serveur : une app Next.js faite
avec v0, Cursor ou Claude Code qui lit la base via Prisma ou Drizzle, une app
Replit avec un serveur Express, une Edge Function qui ouvre sa propre connexion
Postgres. Une page qui appelle seulement supabase.from(…) passe par la Data
API, qui a ses propres connexions.
Le premier conseil que vous trouverez pour "max client connections reached" sur Supabase, y compris à la fin de l'article d'aide de Supabase sur la version Postgres de cette erreur, est de passer à une taille de calcul supérieure. Pour une app très fréquentée, c'est parfois juste. Sur le plan gratuit, la solution peut être un numéro de port. Avant de payer quoi que ce soit, regardez lequel des deux messages vous avez reçu et quel port utilise votre chaîne de connexion. Les deux limites sont fixées par des choses différentes, et une seule d'entre elles augmente avec le prix.
Que signifie "max client connections reached" sur Supabase ?
Supavisor, le pooler de connexions placé entre votre app et votre base de données Supabase, a déjà autant de clients connectés qu'il en accepte, et il a refusé le suivant.
Un client, ici, c'est une connexion ouverte depuis votre code : un client de
base de données dans une copie en cours d'exécution de votre serveur. Le
message vient de Supavisor lui-même, du fichier max_connections_error.ex de
son code source, et il arrive dans votre app sous forme d'erreur Postgres avec
la gravité FATAL et le code XX000. Les bibliothèques affichent cet emballage
de façons différentes, mais les mots sont ceux ci-dessus.
Imaginez votre base de données comme une cuisine avec un comptoir et un nombre fixe de tabourets. Chaque tabouret est une connexion à Postgres, la base de données de votre projet Supabase, et une demande de données a besoin d'un tabouret le temps que dure sa commande. Supavisor est l'hôte à la porte. Il décide qui s'assoit où, et il garde une zone d'attente pour les gens qui sont entrés mais ne mangent pas encore. Le message veut dire que la liste de l'hôte est pleine.
Quelle limite avez-vous atteinte ?
Les mots de l'erreur vous le disent, et le port à la fin de votre chaîne de connexion aussi.
| Ce que vous voyez | Qui l'a envoyé | Ce qui est compté | Sur le plan gratuit |
|---|---|---|---|
(EMAXCONN) max client connections reached, limit: … | Supavisor en mode transaction, port 6543 | les clients connectés au pooler en même temps | 200 |
(EMAXCONNSESSION) max clients reached in session mode … | Supavisor en mode session, port 5432 sur l'hôte du pooler | les clients, plafonnés à la taille du pool | 15 |
remaining connection slots are reserved for roles with the SUPERUSER attribute | Postgres lui-même | les connexions à la base | 60 |
sorry, too many clients already | Postgres lui-même | toutes les connexions, réservées comprises | 60 |
Les chiffres viennent du tableau du guide de Supabase sur le calcul, pour Nano,
la taille sur laquelle tourne le plan gratuit. Micro, la plus petite taille
payante, a les trois mêmes. Les deux messages Postgres viennent du code source
de Postgres et portent le code 53300 ; Postgres 15 formule le premier
remaining connection slots are reserved for non-replication superuser connections.
Dans la cuisine, les deux dernières lignes, ce sont les tabourets eux-mêmes qui manquent. Les deux premières, c'est l'hôte qui ne laisse plus entrer personne.
Votre chaîne de connexion dit par quelle porte vous êtes entré. Elle se trouve
dans les variables d'environnement de votre serveur, souvent sous le nom
DATABASE_URL, et le guide de connexion de Supabase montre chaque type :
…@db.[PROJECT-REF].supabase.co:5432/postgresest une connexion directe, qui passe devant l'hôte et va droit à un tabouret.…@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgresest le pooler en mode session.…@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgresest le pooler en mode transaction.
Pourquoi une app Supabase manque-t-elle de connexions ?
Parce que quelque chose ouvre des connexions plus vite qu'il ne les rend, et les fonctions serverless, selon la description même de Supabase, ouvrent beaucoup de connexions de courte durée.
Une fonction sur Vercel, sur Netlify ou dans les Edge Functions de Supabase tourne en autant de copies que le trafic le demande, et chaque copie active garde son propre client de base de données. Le guide de connexion de Supabase fait le calcul pour Postgres.js, l'une des bibliothèques Postgres courantes : elle ouvre par défaut jusqu'à 10 connexions par copie, et d'après le guide quelques dizaines d'instances suffisent à épuiser le pool.
Le mode session sature en premier. L'hôte vous donne un tabouret et vous le gardez jusqu'à votre départ, que vous mangiez ou non. La FAQ de Supabase sur Supavisor le dit sans détour : une fois que le pooler a attribué une connexion directe à un client, elle reste à ce client jusqu'à ce qu'il la rende de lui-même. L'hôte ne peut donc faire entrer qu'autant de personnes qu'il a de tabourets pour cette chaîne de connexion, et c'est pourquoi le message du mode session cite la taille du pool. Le code de Supavisor vérifie exactement cela : en mode session, un nouveau client est refusé dès que les clients déjà connectés atteignent la taille du pool. Quinze tabourets, et le seizième client est refoulé à la porte, aussi calmes que soient les quinze premiers.
Le mode transaction fait entrer bien plus de monde. L'hôte vous assoit pour une commande, une seule transaction, et donne le tabouret à la personne suivante dès qu'elle est finie, si bien que 200 clients peuvent se partager une poignée de connexions. Il a quand même une zone d'attente de taille fixe, et une vague de copies de fonctions qui ouvrent chacune plusieurs clients la remplit.
Des choses en dehors de votre app occupent aussi des tabourets : un outil de base de données comme TablePlus ou DBeaver resté ouvert, une automatisation dans n8n ou Make avec une étape Postgres, votre propre ordinateur qui fait tourner l'app en développement avec la chaîne de production, une tâche de sauvegarde. Chacun est un client de la chaîne qu'on lui a donnée.
Une requête lente garde son tabouret plus longtemps. Si vos logs montrent aussi
canceling statement due to statement timeout, corrigez d'abord cette requête,
car chaque seconde où elle tourne est une seconde où son tabouret est pris.
Cette erreur a son propre guide.
Voyez qui occupe les connexions
Demandez à Postgres, puis au tableau de bord. Postgres liste chaque connexion qu'il a ouverte, et le tableau de bord de Supabase compte les clients du pooler.
Dans le SQL Editor, cette requête compte les connexions par rôle et par app qui les a ouvertes, et selon ce qu'elles font :
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;
Le rôle vous dit de qui il s'agit. Le guide de Supabase sur la gestion des connexions les liste :
| Rôle | Qui c'est |
|---|---|
authenticator | la Data API, par laquelle passe chaque appel supabase.from(…) |
supabase_auth_admin | Auth, le service qui connecte vos utilisateurs |
supabase_storage_admin | Storage |
postgres | le tableau de bord et les outils externes, Prisma et psql compris |
| un rôle que vous avez créé | quiconque a reçu de vous le mot de passe de ce rôle |
Une pile de connexions postgres dans l'état idle, avec un
application_name que vous reconnaissez, c'est un client assis sur un tabouret
devant une assiette vide. idle in transaction est l'état à regarder en
premier : d'après le guide, il veut presque toujours dire que l'application a
oublié de valider ou d'annuler, et la session garde ses verrous tant qu'elle
reste ouverte.
Pour le pooler lui-même, ouvrez Observability dans le tableau de bord. Le
rapport Shared Pooler (Supavisor) Client Connections compte ses clients
dans le temps. Le guide précise que ces rapports montrent le chiffre de leur
dernière actualisation, et pg_stat_activity est la vue en direct.
Comment corriger "max client connections reached" sur Supabase
Passez le code serverless en mode transaction, donnez une connexion à chacune de ses copies, et gardez le mode session pour les tâches qui ont besoin d'une session entière. Faites-le dans cet ordre.
1. Utilisez le Transaction pooler pour les fonctions serverless. Dans votre
projet Supabase, cliquez sur Connect en haut de la page, choisissez
Transaction pooler et copiez la chaîne. Elle se termine par
:6543/postgres. Mettez-la dans l'environnement de votre serveur à la place de
l'ancienne, avec le mot de passe de votre base là où la chaîne indique
[YOUR-PASSWORD].
Le mode transaction ne garde rien entre deux transactions, donc les prepared statements doivent être désactivés. Le guide de Supabase donne le réglage par bibliothèque :
| Bibliothèque | Réglage |
|---|---|
| Postgres.js, Drizzle | prepare: false |
| Prisma | pgbouncer=true dans la chaîne de connexion |
| asyncpg | statement_cache_size=0 |
2. Créez le client une seule fois, avec un pool de un. Un client créé dans le gestionnaire de requête est une nouvelle connexion à chaque requête. Le guide de Supabase dit de le créer une fois en haut du fichier, en dehors de tout gestionnaire, et de plafonner son pool à 1, parce que toutes les invocations sur cette instance active partagent le client :
import postgres from 'postgres'
export const sql = postgres(process.env.DATABASE_URL, {
max: 1,
prepare: false,
ssl: 'require',
})
Pour Prisma, le même conseil est connection_limit=1 dans la chaîne de
connexion, d'après le guide de dépannage Prisma de Supabase. Si vous avez fait
l'app avec Cursor, Claude Code ou v0, c'est un petit changement à lui décrire :
le fichier qui crée le client de base de données, la nouvelle chaîne et ces deux
réglages.
3. Gardez le mode session pour une longue tâche. Une migration, un
pg_dump, un outil que vous ouvrez à la main : chacun est une seule session
qui veut garder son tabouret. Le guide de Supabase les envoie vers une
connexion directe, ou vers le mode session sur un réseau sans IPv6, et c'est
ainsi que se connecte
une sauvegarde qui tourne sur les runners de GitHub.
4. Fermez ce que vous avez laissé ouvert. Quittez l'outil de base de données, arrêtez les exécutions de test de l'automatisation et retirez la chaîne de production de votre ordinateur. Une connexion que vous ne pouvez pas fermer de son côté peut être terminée depuis le SQL Editor. Cette requête liste celles qui gardent une transaction ouverte :
select pid, usename, application_name, query_start, query
from pg_stat_activity
where state = 'idle in transaction';
Ensuite select pg_terminate_backend(pid);, avec le pid de cette liste,
termine la session. Postgres annule ce que sa transaction ouverte avait écrit
sans le valider, alors lisez sa colonne query avant de la terminer.
5. Ensuite, regardez la taille de calcul. Si les clients sont tous du vrai trafic, partagent les connexions comme il faut et sont quand même plus de 200, la limite monte avec la taille : Small permet 400 clients de pooler et Medium 600, d'après le tableau de calcul de Supabase. Sa base de connaissances dit que les limites de clients du pooler partagé sont figées et ne changent qu'avec une taille de calcul supérieure, et son guide sur le calcul dit qu'un changement s'accompagne en général de moins de 2 minutes d'interruption.
Faut-il augmenter la taille du pool ?
Pas pour corriger cela. En mode transaction, la taille du pool ne change en rien la limite de clients, et dans les deux modes elle décide combien des connexions propres de votre base le pooler peut prendre.
La taille du pool, c'est le nombre de tabourets que l'hôte peut distribuer, et la cuisine en a 60 sur le plan gratuit. La FAQ de Supabase la définit comme le nombre maximal de connexions directes que le pooler peut maintenir pour chaque combinaison d'utilisateur, de base et de mode, donc deux chaînes de connexion avec un utilisateur ou un mode différent ont chacune un pool de cette taille. Les mêmes 60 servent la Data API, Auth et Storage, et Storage se connecte via Supavisor avec un pool à lui. L'avertissement de la FAQ : si Supavisor utilise la plupart des connexions disponibles, vous risquez de priver d'autres serveurs, comme Auth, de l'accès à votre base. Auth est le service qui connecte vos utilisateurs.
Sa règle empirique est de garder le pooler sous 40 % des connexions si votre app utilise aussi la Data API, et de n'aller vers 80 % que si elle ne l'utilise pas.
En mode session, un pool plus grand fait bien entrer plus de clients, un
tabouret chacun. La file passe alors de la porte de l'hôte à la cuisine. Quand
les tabourets y manquent, Postgres répond remaining connection slots are reserved… au service qui demande ensuite, et ce peut être Auth.
La chaîne de connexion contourne vos règles
Une chaîne de connexion est un mot de passe, et l'utilisateur qu'elle contient
est le plus souvent postgres, qui a bypassrls selon le guide de Supabase
sur le Row Level Security. Chaque règle que vous avez écrite est ignorée pour
chaque requête que cette chaîne envoie.
Cela change ce que votre code serveur doit faire. Une page qui lit via
supabase.from(…) avec votre clé publishable est filtrée ligne par ligne par
vos règles. La même page déplacée dans une route serveur avec Prisma ou Drizzle
lit chaque ligne de la table, et la seule chose entre un utilisateur et les
lignes d'un autre est le where qu'ajoute votre route. Si vous déplacez des
pages dans une route serveur pour échapper à cette erreur, vérifiez avant la
mise en ligne que chacune filtre sur l'utilisateur connecté.
La chaîne ne va jamais non plus dans une variable dont le nom commence par
VITE_ ou NEXT_PUBLIC_. Ces préfixes mettent la valeur dans le code que
chaque visiteur télécharge, et
ce que font ces deux préfixes a son
propre article. Un navigateur ne peut pas ouvrir de connexion Postgres, donc
une chaîne de connexion dans le frontend ne fait rien fonctionner et remet le
mot de passe de la base à quiconque ouvre votre site.
Savoir si l'une de vos tables répond à une requête sans connexion, et si une clé secrète qu'il reconnaît se trouve dans le code que votre site envoie, ce sont deux des neuf vérifications du scan gratuit de Reeve. Il lit votre app en ligne comme le fait le navigateur d'un visiteur, prend environ 20 secondes et ne demande aucun compte.
Savoir quand cela recommence
Cette erreur revient quand le trafic revient, et l'heure chargée est rarement une heure où vous lisez des logs de fonctions.
Reeve Monitor vérifie votre app en ligne depuis l'extérieur :
- si elle répond, toutes les 60 secondes, et toutes les 15 tant qu'elle est en panne
- jusqu'à 10 pages de plus, lues pour les mots qui doivent y être et ceux qui ne doivent pas y être, comme "Une erreur est survenue"
- un message par e-mail, Telegram, Slack ou webhook, avec une capture d'écran et un log conservés 30 jours, pour savoir quelle page est tombée et quand
- les neuf vérifications de sécurité toutes les heures
- un rapport mensuel, en langage clair, de ce qu'il a vu
Reeve Care garde une copie de votre base de données Supabase d'avant le prochain changement que vous y ferez :
- une copie chiffrée selon un calendrier, sur le stockage propre de Reeve dans l'UE, en dehors de votre compte Supabase
- chaque copie vérifiée avant de compter, en comptant les lignes de chaque table
- vos fichiers envoyés aussi, dès que vous connectez un accès Storage
- une restauration en un clic, avec une copie de sécurité de l'état actuel prise d'abord
- tout ce que fait Monitor
Ce qu'il faut faire aujourd'hui
Que faire
- Lisez l'erreur et le port :
(EMAXCONN)sur6543est la limite de clients du Transaction pooler, et(EMAXCONNSESSION)sur5432à l'adresse du pooler est la taille du pool. - Comptez qui occupe les connexions avec
pg_stat_activity, et fermez les outils et les exécutions de test restés connectés. - Pointez le code serverless sur la chaîne du Transaction pooler, désactivez les prepared statements et créez le client une seule fois avec un pool de 1.
- Laissez la taille du pool dans les repères de 40 % et 80 % de Supabase, parce qu'Auth et la Data API puisent dans les mêmes connexions.
- Vérifiez que chaque route serveur qui utilise la chaîne de connexion filtre sur l'utilisateur connecté, puisqu'aucune règle ne le fait pour cette chaîne.
Commencez par la chaîne de connexion dans l'environnement de votre serveur : son port vous dit quelle moitié de cet article vous concerne. Si vous déplacez des pages dans une route serveur pour corriger cela, la checklist de sécurité en 10 minutes couvre ce qu'il faut regarder avant la mise en ligne.
FAQ
Que signifie "max client connections reached" sur Supabase ?
Supavisor, le pooler entre votre app et votre base de données Supabase, a déjà autant de clients connectés qu'il en accepte et en a refusé un de plus. En mode transaction, port 6543, c'est la taille de calcul qui fixe la limite : 200 sur le plan gratuit. Le message arrive dans votre app sous forme d'erreur FATAL avec le code XX000 et le préfixe (EMAXCONN).
Pourquoi ai-je "max clients reached in session mode" avec seulement quelques utilisateurs ?
En mode session, chaque client garde sa connexion à la base jusqu'à ce qu'il se déconnecte, donc Supavisor n'admet qu'autant de clients que la taille du pool, 15 par défaut. Une fonction serverless ouvre un client dans chaque copie d'elle-même qui tourne, et une poignée de copies suffit à remplir cela. Utilisez la chaîne du Transaction pooler, port 6543, pour le code serverless.
Augmenter la taille du pool corrige-t-il "max client connections reached" ?
Pas en mode transaction, où la limite de clients vient de la taille de calcul. La taille du pool est le nombre de connexions propres de la base que le pooler peut ouvrir, sur les mêmes 60 du plan gratuit qu'utilisent Auth, Storage et la Data API. Supabase conseille de garder le pooler sous 40 % de ces connexions si votre app utilise aussi la Data API.
Quelle différence entre le port 5432 et le port 6543 sur Supabase ?
À l'adresse du pooler, 5432 est le mode session, où un client garde sa connexion à la base tant qu'il reste connecté, et 6543 le mode transaction, où les clients se relaient sur des connexions partagées, une transaction à la fois. Supabase recommande 6543 pour les fonctions serverless et edge, et le mode session ou une connexion directe pour les longues tâches comme les migrations et pg_dump.
Que signifie "remaining connection slots are reserved" sur Supabase ?
Postgres lui-même n'a plus de connexions ordinaires et garde les dernières pour les superutilisateurs. Il compte chaque connexion : les vôtres en direct, celles du pooler, et celles de la Data API, d'Auth et de Storage. Sur le plan gratuit, le total est de 60. Trouvez qui les occupe avec pg_stat_activity avant de changer le moindre réglage.