Zum Inhalt springen

Sicherheitsgrundlagen

Supabase "max client connections reached" erklärt

Supabase "max client connections reached": Der Pooler hat keinen Platz für noch einen Client. Der Port in deinem Connection String setzt das Limit.

Vlad Tkachenko13 Min. Lesezeit
Eine lange Theke mit einer Person auf jedem Hocker, die aus dem Bild läuft, und eine Schlange an der Tür, deren erste Person abgewiesen wurde.

Kurz gesagt

  • "max client connections reached" in Supabase kommt von Supavisor, dem Pooler zwischen deiner App und ihrer Datenbank. Er hält schon so viele Clients, wie er zulässt: 200 im Gratis-Tarif im Transaktionsmodus, Port 6543.
  • Im Session-Modus, Port 5432 an der Pooler-Adresse, ist das Limit die Pool-Größe, standardmäßig 15, und jeder Client behält seine Datenbankverbindung, bis er sich trennt. Eine Serverless-App mit diesem String wird bei ihrem sechzehnten Client abgewiesen.
  • Verleg Serverless-Code auf Port 6543, leg seinen Datenbank-Client einmal mit einem Pool von 1 an und schließ die Tools, die du verbunden gelassen hast. Eine größere Pool-Größe hebt das Client-Limit nicht an und nimmt Verbindungen, die Auth braucht.

Deine App lief wochenlang ohne Probleme. Dann bringt etwas Andrang, ein Launch oder ein Beitrag, der geteilt wurde, und die Seiten, die aus deiner Datenbank lesen, zeigen einen Fehler, während die Startseite noch lädt. In den Funktions-Logs deines Hosts steht eine Zeile:

(EMAXCONN) max client connections reached, limit: 200

Oder, bei einer App, die sich im Session-Modus verbindet, diese:

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

Du triffst darauf bei einer App mit eigenem Server: einer Next.js-App aus v0, Cursor oder Claude Code, die die Datenbank über Prisma oder Drizzle liest, einer Replit-App mit Express-Server, einer Edge Function, die ihre eigene Postgres-Verbindung öffnet. Eine Seite, die nur supabase.from(…) aufruft, geht stattdessen über die Data API, und die hat eigene Verbindungen.

Der Rat, den du zu "max client connections reached" in Supabase zuerst findest, auch am Ende von Supabases eigenem Hilfeartikel zur Postgres-Fassung dieses Fehlers, lautet: eine größere Compute-Größe nehmen. Für eine viel besuchte App stimmt das manchmal. Im Gratis-Tarif kann die Lösung eine Portnummer sein. Bevor du für irgendetwas zahlst, lies, welche der beiden Meldungen du bekommen hast und welchen Port dein Connection String benutzt. Die beiden Limits werden von verschiedenen Dingen gesetzt, und nur eines davon wächst mit dem Preis.

Was bedeutet "max client connections reached" in Supabase?

Supavisor, der Connection Pooler zwischen deiner App und deiner Supabase-Datenbank, hat schon so viele Clients verbunden, wie er zulässt, und hat den nächsten abgewiesen.

Ein Client ist hier eine offene Verbindung aus deinem Code: ein Datenbank-Client in einer laufenden Kopie deines Servers. Die Meldung stammt von Supavisor selbst, aus der Datei max_connections_error.ex in seinem Quellcode, und sie erreicht deine App als Postgres-Fehler mit dem Schweregrad FATAL und dem Code XX000. Bibliotheken drucken diese Verpackung unterschiedlich, aber die Worte sind die von oben.

Stell dir deine Datenbank als Küche mit einer Theke und einer festen Zahl von Hockern vor. Jeder Hocker ist eine Verbindung zu Postgres, der Datenbank in deinem Supabase-Projekt, und eine Anfrage nach Daten braucht einen Hocker, solange ihre Bestellung dauert. Supavisor ist der Platzanweiser an der Tür. Er entscheidet, wer wo sitzt, und er hat einen Wartebereich für Leute, die schon drin sind und noch nicht essen. Die Meldung heißt, dass die Liste des Platzanweisers voll ist.

Welches Limit hast du erreicht?

Die Worte des Fehlers sagen es dir, und der Port am Ende deines Connection Strings auch.

Was du siehstWer es geschickt hatWas gezählt wirdIm Gratis-Tarif
(EMAXCONN) max client connections reached, limit: …Supavisor im Transaktionsmodus, Port 6543Clients, die gleichzeitig mit dem Pooler verbunden sind200
(EMAXCONNSESSION) max clients reached in session mode …Supavisor im Session-Modus, Port 5432 auf dem Pooler-HostClients, begrenzt auf die Pool-Größe15
remaining connection slots are reserved for roles with the SUPERUSER attributePostgres selbstVerbindungen zur Datenbank60
sorry, too many clients alreadyPostgres selbstjede Verbindung, auch die reservierten60

Die Zahlen stammen aus der Tabelle in Supabases Compute-Anleitung, für Nano, die Größe, auf der der Gratis-Tarif läuft. Micro, die kleinste bezahlte Größe, hat dieselben drei. Die beiden Postgres-Meldungen kommen aus dem Quellcode von Postgres und tragen den Code 53300; Postgres 15 formuliert die erste als remaining connection slots are reserved for non-replication superuser connections.

In der Küche heißen die letzten beiden Zeilen, dass die Hocker selbst ausgehen. Die ersten beiden sind der Platzanweiser, der keine weitere Person durch die Tür lässt.

Dein Connection String sagt, durch welche Tür du gekommen bist. Er steht in den Umgebungsvariablen deines Servers, oft als DATABASE_URL, und Supabases Anleitung zum Verbinden zeigt jede Art:

  • …@db.[PROJECT-REF].supabase.co:5432/postgres ist eine direkte Verbindung, am Platzanweiser vorbei direkt auf einen Hocker.
  • …@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgres ist der Pooler im Session-Modus.
  • …@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgres ist der Pooler im Transaktionsmodus.

Warum gehen einer Supabase-App die Verbindungen aus?

Weil etwas Verbindungen schneller öffnet, als es sie zurückgibt, und Serverless-Funktionen öffnen nach Supabases eigener Beschreibung viele kurzlebige Verbindungen.

Eine Funktion auf Vercel, Netlify oder in Supabases eigenen Edge Functions läuft in so vielen Kopien, wie der Verkehr verlangt, und jede warme Kopie hält ihren eigenen Datenbank-Client. Supabases Anleitung zum Verbinden rechnet das für Postgres.js vor, eine der verbreiteten Postgres-Bibliotheken: Sie öffnet standardmäßig bis zu 10 Verbindungen pro Kopie, und laut der Anleitung reichen ein paar Dutzend Instanzen, um den Pool zu erschöpfen.

Der Session-Modus ist zuerst voll. Der Platzanweiser gibt dir einen Hocker, und du behältst ihn, bis du gehst, ob du isst oder nicht. Supabases FAQ zu Supavisor sagt das direkt: Hat der Pooler einem Client eine direkte Verbindung zugewiesen, bleibt sie bei ihm, bis er sie freiwillig abgibt. Also kann der Platzanweiser nur so viele Leute hereinlassen, wie er für diesen Connection String Hocker hat, und deshalb nennt die Meldung im Session-Modus die Pool-Größe. Supavisors Quellcode prüft genau das: Im Session-Modus wird ein neuer Client abgewiesen, sobald die schon verbundenen die Pool-Größe erreichen. Fünfzehn Hocker, und der sechzehnte Client wird an der Tür abgewiesen, egal wie still die ersten fünfzehn sind.

Der Transaktionsmodus lässt viel mehr Leute herein. Der Platzanweiser setzt dich für eine Bestellung hin, eine einzige Transaktion, und gibt den Hocker dem Nächsten, sobald sie fertig ist, also können sich 200 Clients eine Handvoll Verbindungen teilen. Er hat trotzdem einen Wartebereich fester Größe, und ein Schub von Funktionskopien, die jeweils mehrere Clients öffnen, füllt ihn.

Auch Dinge außerhalb deiner App belegen Hocker: ein Datenbank-Tool wie TablePlus oder DBeaver, das offen geblieben ist, eine Automatisierung in n8n oder Make mit einem Postgres-Schritt, dein eigener Laptop, auf dem die App in der Entwicklung gegen den Produktions-String läuft, ein Backup-Job. Jedes davon ist ein Client des Strings, den es bekommen hat.

Eine langsame Abfrage hält ihren Hocker länger. Wenn deine Logs auch canceling statement due to statement timeout zeigen, repariere zuerst diese Abfrage, denn jede Sekunde, die sie läuft, ist ihr Hocker besetzt. Dieser Fehler hat eine eigene Anleitung.

Der Session-Modus gibt jedem Client eine Verbindung, bis er geht, also ist die Pool-Größe zugleich das Client-Limit. Der Transaktionsmodus verleiht Verbindungen für jeweils eine Transaktion.

Sieh nach, wer die Verbindungen hält

Frag Postgres, dann frag das Dashboard. Postgres listet jede Verbindung, die es offen hat, und Supabases Dashboard zählt die Clients des Poolers.

Im SQL Editor zählt diese Abfrage die Verbindungen nach der Rolle und der App, die sie geöffnet haben, und danach, was sie gerade tun:

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;

Die Rolle sagt dir, wer es ist. Supabases Anleitung zur Verwaltung von Verbindungen listet sie auf:

RolleWer das ist
authenticatordie Data API, über die jeder Aufruf von supabase.from(…) läuft
supabase_auth_adminAuth, der Dienst, der deine Nutzer anmeldet
supabase_storage_adminStorage
postgresdas Dashboard und externe Tools, auch Prisma und psql
eine Rolle, die du angelegt hastwer auch immer das Passwort dieser Rolle von dir bekommen hat

Ein Haufen postgres-Verbindungen im Zustand idle, mit einem application_name, den du kennst, ist ein Client, der auf einem Hocker sitzt und nichts vor sich hat. idle in transaction ist der Zustand, den du zuerst ansehen solltest: Laut der Anleitung heißt er fast immer, dass die Anwendung vergessen hat, zu committen oder zurückzurollen, und die Sitzung hält ihre Sperren, solange sie offen bleibt.

Für den Pooler selbst öffne Observability im Dashboard. Der Bericht Shared Pooler (Supavisor) Client Connections zählt seine Clients über die Zeit. Die Anleitung weist darauf hin, dass diese Berichte den Stand ihrer letzten Aktualisierung zeigen, und pg_stat_activity ist die Live-Ansicht.

So behebst du "max client connections reached" in Supabase

Verleg Serverless-Code in den Transaktionsmodus, gib jeder Kopie davon eine Verbindung und behalt den Session-Modus für die Jobs, die eine ganze Sitzung brauchen. Mach es in dieser Reihenfolge.

1. Nimm den Transaction Pooler für Serverless-Funktionen. Drück in deinem Supabase-Projekt oben auf der Seite auf Connect, wähl Transaction pooler und kopier den String. Er endet auf :6543/postgres. Setz ihn in der Umgebung deines Servers an die Stelle des alten, mit deinem Datenbank-Passwort dort, wo im String [YOUR-PASSWORD] steht.

Der Transaktionsmodus behält zwischen Transaktionen nichts, also müssen Prepared Statements ausgeschaltet sein. Supabases Anleitung nennt die Einstellung pro Bibliothek:

BibliothekEinstellung
Postgres.js, Drizzleprepare: false
Prismapgbouncer=true im Connection String
asyncpgstatement_cache_size=0

2. Leg den Client einmal an, mit einem Pool von eins. Ein Client, der im Request-Handler angelegt wird, ist eine neue Verbindung für jede Anfrage. Supabases Anleitung sagt, ihn einmal oben in der Datei anzulegen, außerhalb jedes Handlers, und seinen Pool auf 1 zu begrenzen, weil sich alle Aufrufe auf dieser warmen Instanz den Client teilen:

import postgres from 'postgres'

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

Für Prisma lautet derselbe Rat connection_limit=1 im Connection String, aus Supabases Anleitung zur Fehlersuche mit Prisma. Wenn du die App mit Cursor, Claude Code oder v0 gebaut hast, ist das eine kurze Änderung, die du dem Tool beschreiben kannst: die Datei, die den Datenbank-Client anlegt, der neue String und diese zwei Einstellungen.

3. Behalt den Session-Modus für einen langen Job. Eine Migration, ein pg_dump, ein Tool, das du von Hand öffnest: Jedes davon ist eine einzelne Sitzung, die ihren Hocker behalten will. Supabases Anleitung schickt diese an eine direkte Verbindung oder, in einem Netz ohne IPv6, in den Session-Modus, und so verbindet sich auch ein Backup auf den Runnern von GitHub.

4. Schließ, was du offen gelassen hast. Beende das Datenbank-Tool, stopp die Testläufe der Automatisierung und nimm den Produktions-String von deinem Laptop. Eine Verbindung, die du an ihrem eigenen Ende nicht schließen kannst, lässt sich im SQL Editor beenden. Diese Abfrage listet die, die eine Transaktion offen halten:

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

Dann beendet select pg_terminate_backend(pid); mit der pid aus dieser Liste die Sitzung. Postgres rollt zurück, was ihre offene Transaktion geschrieben und nicht committet hatte, also lies ihre Spalte query, bevor du sie beendest.

5. Dann sieh dir die Compute-Größe an. Wenn die Clients alle echter Verkehr sind, sich die Verbindungen teilen, wie sie sollen, und trotzdem mehr als 200 sind, wächst das Limit mit der Größe: Small erlaubt 400 Pooler-Clients und Medium 600, laut Supabases Compute-Tabelle. Seine Wissensdatenbank sagt, die Client-Limits des geteilten Poolers seien fest eingestellt und ließen sich nur mit einer größeren Compute-Größe ändern, und seine Compute-Anleitung sagt, ein Wechsel komme meist mit weniger als 2 Minuten Ausfallzeit.

Soll ich die Pool-Größe erhöhen?

Nicht, um das zu beheben. Im Transaktionsmodus ändert die Pool-Größe das Client-Limit überhaupt nicht, und in beiden Modi bestimmt sie, wie viele der eigenen Verbindungen deiner Datenbank der Pooler nehmen darf.

Die Pool-Größe ist die Zahl der Hocker, die der Platzanweiser vergeben darf, und die Küche hat im Gratis-Tarif 60. Supabases FAQ definiert sie als die größte Zahl direkter Verbindungen, die der Pooler pro Kombination aus Nutzer, Datenbank und Modus halten kann, also bekommen zwei Connection Strings mit einem anderen Nutzer oder Modus jeder einen Pool dieser Größe. Dieselben 60 bedienen die Data API, Auth und Storage, und Storage verbindet sich über Supavisor mit einem eigenen Pool. Die Warnung der FAQ: Wenn Supavisor die meisten verfügbaren Verbindungen nutzt, riskierst du, dass andere Dienste wie Auth nicht mehr an deine Datenbank kommen. Auth ist der Dienst, der deine Nutzer anmeldet.

Ihre Faustregel ist, den Pooler unter 40 % der Verbindungen zu halten, wenn deine App auch die Data API nutzt, und nur dann Richtung 80 % zu gehen, wenn sie das nicht tut.

Im Session-Modus lässt ein größerer Pool tatsächlich mehr Clients herein, einen Hocker pro Client. Damit wandert die Schlange von der Tür des Platzanweisers in die Küche. Wenn dort die Hocker ausgehen, antwortet Postgres mit remaining connection slots are reserved… dem Dienst, der als Nächstes fragt, und das kann Auth sein.

Die Pool-Größe kommt aus denselben Verbindungen, die die Data API, Auth und Storage nutzen. Wächst sie weit genug, bleibt einer von ihnen ohne Platz.

Der Connection String überspringt deine Regeln

Ein Connection String ist ein Passwort, und der Nutzer darin ist meistens postgres, der laut Supabases eigener Anleitung zu Row Level Security bypassrls hat. Jede Regel, die du geschrieben hast, wird für jede Abfrage übersprungen, die dieser String schickt.

Das ändert, was dein Server-Code tun muss. Eine Seite, die über supabase.from(…) mit deinem Publishable Key liest, wird Zeile für Zeile von deinen Regeln gefiltert. Dieselbe Seite, verlegt in eine Server-Route mit Prisma oder Drizzle, liest jede Zeile der Tabelle, und das Einzige zwischen einem Nutzer und den Zeilen eines anderen ist das where, das deine Route hinzufügt. Wenn du Seiten in eine Server-Route verlegst, um an diesem Fehler vorbeizukommen, prüf vor dem Ausliefern, dass jede nach dem angemeldeten Nutzer filtert.

Der String gehört auch nie in eine Variable, deren Name mit VITE_ oder NEXT_PUBLIC_ beginnt. Diese Präfixe legen den Wert in den Code, den jeder Besucher herunterlädt, und was diese beiden Präfixe tun steht in einem eigenen Beitrag. Ein Browser kann keine Postgres-Verbindung öffnen, also bringt ein Connection String im Frontend nichts zum Laufen und gibt das Datenbank-Passwort jedem, der deine Seite öffnet.

Ob eine deiner Tabellen auf eine Anfrage ohne Anmeldung antwortet und ob ein Secret Key, den er erkennt, im Code steckt, den deine Seite verschickt, sind zwei der neun Checks in Reeves kostenlosem Scan. Er liest deine Live-App so, wie der Browser eines Besuchers es tut, dauert etwa 20 Sekunden und braucht kein Konto.

Erfahren, wenn es wieder passiert

Dieser Fehler kommt zurück, wenn der Verkehr zurückkommt, und die volle Stunde ist selten eine, in der du Funktions-Logs liest.

Reeve Monitor prüft deine Live-App von außen:

  • ob sie erreichbar ist, alle 60 Sekunden, und alle 15, solange sie ausgefallen ist
  • bis zu 10 weitere Seiten, gelesen auf Worte, die da sein müssen, und Worte, die nicht da sein dürfen, etwa "Etwas ist schiefgelaufen"
  • eine Nachricht per E-Mail, Telegram, Slack oder Webhook, mit einem Screenshot und einem Log, 30 Tage aufbewahrt, damit du weißt, welche Seite wann ausgefallen ist
  • alle neun Sicherheitsprüfungen jede Stunde
  • ein monatlicher Bericht in klarer Sprache über das, was er gesehen hat

Reeve Care hält eine Kopie deiner Supabase-Datenbank von vor deiner nächsten Änderung daran:

  • eine verschlüsselte Kopie nach Zeitplan, auf Reeves eigenem Speicher in der EU, außerhalb deines Supabase-Kontos
  • jede Kopie geprüft, bevor sie zählt, durch Zählen der Zeilen in jeder Tabelle
  • auch deine hochgeladenen Dateien, sobald du einen Storage-Zugang verbindest
  • eine Wiederherstellung per Klick, mit einer Sicherheitskopie des aktuellen Stands vorab
  • alles, was Monitor tut

Was heute zu tun ist

Was zu tun ist

  • Lies den Fehler und den Port: (EMAXCONN) auf 6543 ist das Client-Limit des Transaction Poolers, und (EMAXCONNSESSION) auf 5432 an der Pooler-Adresse ist die Pool-Größe.
  • Zähl mit pg_stat_activity, wer die Verbindungen hält, und schließ die Tools und Testläufe, die du verbunden gelassen hast.
  • Richte Serverless-Code auf den String des Transaction Poolers, schalte Prepared Statements aus und leg den Client einmal mit einem Pool von 1 an.
  • Lass die Pool-Größe innerhalb von Supabases Richtwerten von 40 % und 80 %, weil Auth und die Data API aus denselben Verbindungen schöpfen.
  • Prüf, dass jede Server-Route, die den Connection String nutzt, nach dem angemeldeten Nutzer filtert, denn für diesen String tut das keine Regel.

Fang mit dem Connection String in der Umgebung deines Servers an: Sein Port sagt dir, welche Hälfte dieses Beitrags deine ist. Wenn du im Zuge der Lösung Seiten in eine Server-Route verlegst, deckt die 10-Minuten-Sicherheitscheckliste ab, worauf du vor dem Livegang achten solltest.

FAQ

Was bedeutet "max client connections reached" in Supabase?

Supavisor, der Pooler zwischen deiner App und deiner Supabase-Datenbank, hat schon so viele Clients verbunden, wie er zulässt, und einen weiteren abgewiesen. Im Transaktionsmodus, Port 6543, setzt deine Compute-Größe das Limit: 200 im Gratis-Tarif. Die Meldung erreicht deine App als FATAL-Fehler mit dem Code XX000 und dem Präfix (EMAXCONN).

Warum bekomme ich "max clients reached in session mode" mit nur wenigen Nutzern?

Im Session-Modus behält jeder Client seine Datenbankverbindung, bis er sich trennt, also lässt Supavisor nur so viele Clients herein, wie die Pool-Größe erlaubt, standardmäßig 15. Eine Serverless-Funktion öffnet in jeder laufenden Kopie einen Client, und eine Handvoll Kopien füllt das. Nimm für Serverless-Code den String des Transaction Poolers, Port 6543.

Behebt eine größere Pool-Größe "max client connections reached"?

Nicht im Transaktionsmodus, wo das Client-Limit von der Compute-Größe kommt. Die Pool-Größe ist die Zahl der eigenen Verbindungen der Datenbank, die der Pooler öffnen darf, aus denselben 60 im Gratis-Tarif, die Auth, Storage und die Data API nutzen. Supabase rät, den Pooler unter 40 % davon zu halten, wenn deine App auch die Data API nutzt.

Was ist der Unterschied zwischen Port 5432 und 6543 bei Supabase?

An der Pooler-Adresse ist 5432 der Session-Modus, in dem ein Client seine Datenbankverbindung behält, solange er verbunden bleibt, und 6543 der Transaktionsmodus, in dem sich Clients geteilte Verbindungen Transaktion für Transaktion abwechselnd nehmen. Supabase empfiehlt 6543 für Serverless- und Edge-Funktionen und den Session-Modus oder eine direkte Verbindung für lange Jobs wie Migrationen und pg_dump.

Was bedeutet "remaining connection slots are reserved" bei Supabase?

Postgres selbst sind die gewöhnlichen Verbindungen ausgegangen, und es hält die letzten paar für Superuser frei. Es zählt jede Verbindung: deine direkten, die des Poolers und die der Data API, von Auth und Storage. Im Gratis-Tarif sind es insgesamt 60. Finde mit pg_stat_activity heraus, wer sie hält, bevor du irgendeine Einstellung änderst.

Geschrieben von

Vlad Tkachenko

Gründer, Reeve

Ich schaue mir den ganzen Tag Apps an, die mit Lovable, Bolt, v0, Cursor und Replit gebaut wurden, und die kurze Liste von Fehlern, die darin immer wieder auftauchen.

Mehr über den Autor

Weiterlesen

Alle Artikel

Sichere deine Supabase-Datenbank vor der nächsten Änderung

Reeve sichert sie verschlüsselt nach Zeitplan und stellt sie für dich wieder her, wenn etwas schiefgeht.

Supabase-Backups ansehen

Automatisierte externe Prüfung, kein vollständiges Audit. Das Fehlen von Funden ist keine Garantie für Sicherheit.