Основи безпеки
Supabase "max client connections reached": пояснення
Supabase "max client connections reached": у пулера немає місця ще для одного клієнта. Ліміт визначає порт у вашому рядку підключення.

Коротко
- "max client connections reached" у Supabase надходить від Supavisor, пулера між вашим застосунком і його базою даних. У нього вже стільки клієнтів, скільки він приймає: 200 на безкоштовному тарифі в режимі транзакцій, порт 6543.
- У режимі сесії, порт 5432 на адресі пулера, ліміт дорівнює розміру пулу, 15 за замовчуванням, і кожен клієнт тримає своє підключення до бази, доки не відʼєднається. Serverless-застосунок із таким рядком отримує відмову на шістнадцятому клієнті.
- Переведіть serverless-код на порт 6543, створіть його клієнт бази даних один раз із пулом 1 і закрийте інструменти, які лишилися підключеними. Більший розмір пулу не піднімає ліміт клієнтів і забирає підключення, потрібні Auth.
Ваш застосунок тижнями працював без проблем. Потім щось приводить людей, запуск або допис, яким поділилися, і сторінки, що читають із вашої бази даних, починають показувати помилку, поки головна сторінка ще вантажиться. У логах функцій вашого хостингу є один рядок:
(EMAXCONN) max client connections reached, limit: 200
Або, у застосунку, що підключається в режимі сесії, ось цей:
(EMAXCONNSESSION) max clients reached in session mode - max clients are limited to pool_size: 15
Ви натрапляєте на це в застосунку з власним сервером: у застосунку на Next.js
з v0, Cursor чи Claude Code, що читає базу через Prisma або Drizzle, у
застосунку на Replit із сервером Express, у Edge Function, яка відкриває власне
підключення до Postgres. Сторінка, що лише викликає supabase.from(…), іде
натомість через Data API, а та має власні підключення.
Порада, яку ви знайдете першою щодо "max client connections reached" у Supabase, зокрема наприкінці власної довідкової статті Supabase про Postgres-версію цієї помилки, звучить так: перейти на більший розмір обчислень. Для застосунку з великим трафіком це іноді правильно. На безкоштовному тарифі рішенням може бути номер порту. Перш ніж за щось платити, подивіться, яке з двох повідомлень ви отримали і який порт використовує ваш рядок підключення. Два ліміти задають різні речі, і лише один із них росте разом із ціною.
Що означає "max client connections reached" у Supabase?
Supavisor, пулер підключень між вашим застосунком і вашою базою даних Supabase, уже має стільки підключених клієнтів, скільки дозволяє, і відмовив наступному.
Клієнт тут означає одне відкрите підключення з вашого коду: один клієнт бази
даних в одній запущеній копії вашого сервера. Повідомлення належить самому
Supavisor, воно з файлу max_connections_error.ex у його вихідному коді, і
доходить до вашого застосунку як помилка Postgres із рівнем FATAL і кодом
XX000. Бібліотеки показують цю обгортку по-різному, але слова ті самі, що
вище.
Уявіть свою базу даних як кухню з барною стійкою і сталою кількістю стільців. Кожен стілець означає підключення до Postgres, бази даних у вашому проєкті Supabase, і запиту по дані потрібен стілець, поки триває його замовлення. Supavisor стоїть адміністратором біля дверей. Він вирішує, хто де сідає, і тримає зону очікування для тих, хто вже зайшов, але ще не їсть. Повідомлення означає, що список адміністратора заповнений.
Який ліміт ви вичерпали?
Це кажуть слова помилки, і так само порт у кінці вашого рядка підключення.
| Що ви бачите | Хто надіслав | Що рахується | На безкоштовному тарифі |
|---|---|---|---|
(EMAXCONN) max client connections reached, limit: … | Supavisor у режимі транзакцій, порт 6543 | клієнти, одночасно підключені до пулера | 200 |
(EMAXCONNSESSION) max clients reached in session mode … | Supavisor у режимі сесії, порт 5432 на хості пулера | клієнти, обмежені розміром пулу | 15 |
remaining connection slots are reserved for roles with the SUPERUSER attribute | сам Postgres | підключення до бази | 60 |
sorry, too many clients already | сам Postgres | усі підключення, разом із зарезервованими | 60 |
Цифри взято з таблиці в посібнику Supabase про обчислення, для Nano, розміру,
на якому працює безкоштовний тариф. Micro, найменший платний розмір, має ті самі
три. Обидва повідомлення Postgres походять із вихідного коду Postgres і мають
код 53300; Postgres 15 формулює перше як remaining connection slots are reserved for non-replication superuser connections.
На кухні два останні рядки означають, що закінчилися самі стільці. Два перші означають адміністратора, який більше нікого не пускає у двері.
Ваш рядок підключення каже, через які двері ви зайшли. Він лежить у змінних
середовища вашого сервера, часто як DATABASE_URL, і посібник Supabase про
підключення показує кожен вид:
…@db.[PROJECT-REF].supabase.co:5432/postgresозначає пряме підключення, повз адміністратора одразу на стілець.…@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgresозначає пулер у режимі сесії.…@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgresозначає пулер у режимі транзакцій.
Чому застосунку на Supabase не вистачає підключень?
Бо щось відкриває підключення швидше, ніж повертає їх, а serverless-функції, за власним описом Supabase, відкривають багато короткочасних підключень.
Функція на Vercel, на Netlify чи в Edge Functions самого Supabase працює в стількох копіях, скільки вимагає трафік, і кожна активна копія тримає власний клієнт бази даних. Посібник Supabase про підключення рахує це для Postgres.js, однієї з поширених бібліотек Postgres: за замовчуванням вона відкриває до 10 підключень на копію, і, за словами посібника, кількох десятків екземплярів достатньо, щоб вичерпати пул.
Режим сесії заповнюється першим. Адміністратор дає вам стілець, і ви тримаєте його, доки не підете, їсте ви чи ні. FAQ Supabase про Supavisor каже це прямо: щойно пулер призначив клієнтові пряме підключення, воно лишається в цього клієнта, доки той сам його не віддасть. Тож адміністратор може впустити лише стільки людей, скільки має стільців для цього рядка підключення, і тому повідомлення режиму сесії називає розмір пулу. Код Supavisor перевіряє саме це: у режимі сесії новому клієнтові відмовляють, щойно вже підключені досягають розміру пулу. Пʼятнадцять стільців, і шістнадцятий клієнт лишається за дверима, хоч би як тихо сиділи перші пʼятнадцять.
Режим транзакцій пускає набагато більше людей. Адміністратор садить вас на одне замовлення, одну транзакцію, і віддає стілець наступному, щойно вона закінчиться, тож 200 клієнтів можуть ділити жменю підключень. Зона очікування в нього все одно має сталий розмір, і хвиля копій функцій, кожна з яких відкриває кілька клієнтів, її заповнює.
Стільці займають і речі поза вашим застосунком: інструмент для баз даних на кшталт TablePlus чи DBeaver, який лишився відкритим, автоматизація в n8n або Make із кроком Postgres, ваш власний ноутбук, де застосунок працює в розробці з продакшн-рядком, завдання резервного копіювання. Кожне з них є клієнтом того рядка, який йому дали.
Повільний запит тримає свій стілець довше. Якщо у ваших логах також є
canceling statement due to statement timeout, спершу виправте цей запит, бо
кожна секунда його роботи означає секунду зайнятого стільця.
Для цієї помилки є окремий розбір.
Подивіться, хто тримає підключення
Спитайте Postgres, потім панель. Postgres перелічує кожне відкрите підключення, а панель Supabase рахує клієнтів пулера.
У SQL Editor цей запит рахує підключення за роллю, за застосунком, що їх відкрив, і за тим, що вони зараз роблять:
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;
Роль каже, хто це. Посібник Supabase про керування підключеннями їх перелічує:
| Роль | Хто це |
|---|---|
authenticator | Data API, через яку проходить кожен виклик supabase.from(…) |
supabase_auth_admin | Auth, сервіс, що виконує вхід ваших користувачів |
supabase_storage_admin | Storage |
postgres | панель і зовнішні інструменти, зокрема Prisma і psql |
| роль, яку створили ви | будь-хто, кому ви дали пароль цієї ролі |
Купа підключень postgres у стані idle з application_name, який ви
впізнаєте, означає клієнта, що сидить на стільці з порожньою тарілкою.
idle in transaction варто дивитися першим: за посібником, цей стан майже
завжди означає, що застосунок забув зафіксувати або відкотити транзакцію, а
сесія тримає свої блокування, доки лишається відкритою.
Для самого пулера відкрийте Observability у панелі. Звіт
Shared Pooler (Supavisor) Client Connections рахує його клієнтів у часі.
Посібник попереджає, що ці звіти показують кількість на момент останнього
оновлення, а pg_stat_activity дає живу картину.
Як виправити "max client connections reached" у Supabase
Переведіть serverless-код у режим транзакцій, дайте кожній його копії одне підключення, а режим сесії лиште для завдань, яким потрібна ціла сесія. Робіть це саме в такому порядку.
1. Беріть Transaction pooler для serverless-функцій. У вашому проєкті
Supabase натисніть Connect угорі сторінки, виберіть Transaction pooler і
скопіюйте рядок. Він закінчується на :6543/postgres. Покладіть його в
середовище вашого сервера замість старого, з паролем вашої бази там, де в рядку
стоїть [YOUR-PASSWORD].
Режим транзакцій нічого не зберігає між транзакціями, тому prepared statements треба вимкнути. Посібник Supabase дає налаштування для кожної бібліотеки:
| Бібліотека | Налаштування |
|---|---|
| Postgres.js, Drizzle | prepare: false |
| Prisma | pgbouncer=true у рядку підключення |
| asyncpg | statement_cache_size=0 |
2. Створіть клієнт один раз, із пулом в одне підключення. Клієнт, створений усередині обробника запиту, дає нове підключення на кожен запит. Посібник Supabase каже створити його один раз угорі файлу, поза будь-яким обробником, і обмежити його пул до 1, бо всі виклики на цьому активному екземплярі ділять один клієнт:
import postgres from 'postgres'
export const sql = postgres(process.env.DATABASE_URL, {
max: 1,
prepare: false,
ssl: 'require',
})
Для Prisma та сама порада звучить як connection_limit=1 у рядку підключення,
з посібника Supabase про усунення проблем із Prisma. Якщо ви зробили застосунок
у Cursor, Claude Code чи v0, це коротка зміна, яку легко йому описати: файл, що
створює клієнт бази даних, новий рядок і ці два налаштування.
3. Лиште режим сесії для одного довгого завдання. Міграція, pg_dump,
інструмент, який ви відкриваєте вручну: кожне з них є однією сесією, що хоче
тримати свій стілець. Посібник Supabase відправляє їх на пряме підключення або,
у мережі без IPv6, у режим сесії, і саме так підключається
резервна копія, що працює на раннерах GitHub.
4. Закрийте те, що лишили відкритим. Вийдіть з інструмента для баз даних, зупиніть тестові запуски автоматизації і приберіть продакшн-рядок зі свого ноутбука. Підключення, яке не вдається закрити з його боку, можна завершити в SQL Editor. Цей запит показує ті, що тримають відкриту транзакцію:
select pid, usename, application_name, query_start, query
from pg_stat_activity
where state = 'idle in transaction';
Потім select pg_terminate_backend(pid); із pid з цього списку завершує
сесію. Postgres відкочує все, що її відкрита транзакція записала й не
зафіксувала, тож прочитайте її стовпець query, перш ніж її завершувати.
5. Тоді подивіться на розмір обчислень. Якщо всі клієнти означають справжній трафік, ділять підключення як слід і все одно їх більше за 200, ліміт росте з розміром: Small дозволяє 400 клієнтів пулера, а Medium 600, за таблицею обчислень Supabase. Його база знань каже, що ліміти клієнтів спільного пулера зафіксовані й змінюються лише з більшим розміром обчислень, а його посібник про обчислення каже, що зміна зазвичай означає менш ніж 2 хвилини простою.
Чи варто збільшити розмір пулу?
Не для того, щоб це виправити. У режимі транзакцій розмір пулу зовсім не змінює ліміт клієнтів, а в обох режимах він визначає, скільки власних підключень вашої бази може забрати пулер.
Розмір пулу означає кількість стільців, які адміністратор може роздати, а на кухні їх 60 на безкоштовному тарифі. FAQ Supabase визначає його як найбільшу кількість прямих підключень, яку пулер може тримати для кожної комбінації користувача, бази та режиму, тож два рядки підключення з іншим користувачем чи режимом отримують кожен пул такого розміру. Ті самі 60 обслуговують Data API, Auth і Storage, а Storage підключається через Supavisor із власним пулом. Попередження з FAQ: якщо Supavisor використовує більшість доступних підключень, ви ризикуєте позбавити інші сервери, як-от Auth, доступу до вашої бази. Auth означає сервіс, який виконує вхід ваших користувачів.
Його практичне правило таке: тримати пулер нижче 40 % підключень, якщо ваш застосунок також користується Data API, і підходити до 80 % лише тоді, коли не користується.
У режимі сесії більший пул справді пускає більше клієнтів, по стільцю на
кожного. Так черга переходить від дверей адміністратора на кухню. Коли там
закінчуються стільці, Postgres відповідає remaining connection slots are reserved… тому сервісу, що попросить наступним, і це може бути Auth.
Рядок підключення обходить ваші політики
Рядок підключення є паролем, а користувач у ньому зазвичай postgres, який,
за власним посібником Supabase про Row Level Security, має bypassrls. Кожна
політика, яку ви написали, пропускається для кожного запиту, що надсилає цей
рядок.
Це змінює те, що має робити код вашого сервера. Сторінку, яка читає через
supabase.from(…) з вашим publishable-ключем, ваші політики фільтрують рядок
за рядком. Та сама сторінка, перенесена в серверний маршрут із Prisma чи
Drizzle, читає кожен рядок таблиці, і між одним користувачем і рядками іншого
стоїть лише where, який додає ваш маршрут. Якщо ви переносите сторінки в
серверний маршрут, щоб обійти цю помилку, перед публікацією перевірте, що
кожна фільтрує за користувачем, який увійшов.
Рядок також ніколи не кладуть у змінну, назва якої починається з VITE_ або
NEXT_PUBLIC_. Ці префікси кладуть значення в код, який завантажує кожен
відвідувач, і
що роблять ці два префікси пояснює
окремий допис. Браузер не вміє відкрити підключення до Postgres, тож рядок
підключення у фронтенді нічого не запускає і віддає пароль від бази кожному,
хто відкриє ваш сайт.
Чи відповідає якась із ваших таблиць на запит без входу, і чи є секретний ключ, який він розпізнає, у коді, що надсилає ваш сайт, перевіряють дві з девʼяти перевірок безкоштовного сканування Reeve. Воно читає ваш робочий застосунок так, як це робить браузер відвідувача, триває близько 20 секунд і не потребує облікового запису.
Дізнатися, коли це станеться знову
Ця помилка повертається разом із трафіком, а година пік рідко буває годиною, яку ви проводите над логами функцій.
Reeve Monitor перевіряє ваш робочий застосунок ззовні:
- чи він доступний, кожні 60 секунд, і кожні 15, поки він лежить
- до 10 додаткових сторінок, які читаються на слова, що мають там бути, і слова, яких там бути не повинно, як-от "Щось пішло не так"
- повідомлення електронною поштою, у Telegram, Slack чи на вебхук, зі знімком екрана і логом, які зберігаються 30 днів, щоб ви знали, яка сторінка впала і коли
- усі девʼять перевірок безпеки щогодини
- щомісячний звіт простою мовою про те, що він бачив
Reeve Care тримає копію вашої бази даних Supabase, зроблену до наступної зміни, яку ви в ній зробите:
- зашифрована копія за розкладом, у власному сховищі Reeve в ЄС, поза вашим обліковим записом Supabase
- кожна копія перевірена, перш ніж зарахуватися, підрахунком рядків у кожній таблиці
- ваші вивантажені файли теж, щойно ви підключите доступ до Storage
- відновлення в один клік, із безпечною копією поточного стану, зробленою заздалегідь
- усе, що робить Monitor
Що зробити сьогодні
Що робити
- Прочитайте помилку і порт:
(EMAXCONN)на6543означає ліміт клієнтів Transaction pooler, а(EMAXCONNSESSION)на5432на адресі пулера означає розмір пулу. - Порахуйте через
pg_stat_activity, хто тримає підключення, і закрийте інструменти та тестові запуски, які лишилися підключеними. - Спрямуйте serverless-код на рядок Transaction pooler, вимкніть prepared statements і створіть клієнт один раз із пулом 1.
- Тримайте розмір пулу в межах орієнтирів Supabase у 40 % і 80 %, бо Auth і Data API беруть із тих самих підключень.
- Перевірте, що кожен серверний маршрут, який використовує рядок підключення, фільтрує за користувачем, який увійшов, адже для цього рядка цього не робить жодна політика.
Почніть із рядка підключення в середовищі вашого сервера: його порт підкаже, яка половина цього допису стосується вас. Якщо ви переносите сторінки в серверний маршрут, щоб це виправити, 10-хвилинний чекліст безпеки покриває, на що подивитися перед запуском.
Поширені запитання
Що означає "max client connections reached" у Supabase?
Supavisor, пулер між вашим застосунком і вашою базою даних Supabase, уже має стільки підключених клієнтів, скільки приймає, і відмовив ще одному. У режимі транзакцій, порт 6543, ліміт задає розмір обчислень: 200 на безкоштовному тарифі. Повідомлення доходить до вашого застосунку як помилка FATAL із кодом XX000 і префіксом (EMAXCONN).
Чому я бачу "max clients reached in session mode", коли користувачів лише кілька?
У режимі сесії кожен клієнт тримає своє підключення до бази, доки не відʼєднається, тому Supavisor пускає лише стільки клієнтів, скільки дозволяє розмір пулу, 15 за замовчуванням. Serverless-функція відкриває клієнт у кожній своїй запущеній копії, і кількох копій достатньо, щоб це заповнити. Для serverless-коду беріть рядок Transaction pooler, порт 6543.
Чи виправить "max client connections reached" більший розмір пулу?
Не в режимі транзакцій, де ліміт клієнтів залежить від розміру обчислень. Розмір пулу означає, скільки власних підключень бази може відкрити пулер, із тих самих 60 на безкоштовному тарифі, якими користуються Auth, Storage і Data API. Supabase радить тримати пулер нижче 40 % від них, якщо ваш застосунок також користується Data API.
Яка різниця між портом 5432 і 6543 у Supabase?
На адресі пулера 5432 означає режим сесії, у якому клієнт тримає своє підключення до бази, доки лишається підключеним, а 6543 означає режим транзакцій, у якому клієнти по черзі користуються спільними підключеннями, по одній транзакції. Supabase радить 6543 для serverless і edge-функцій, а режим сесії або пряме підключення для довгих завдань, як-от міграції та pg_dump.
Що означає "remaining connection slots are reserved" у Supabase?
У самого Postgres закінчилися звичайні підключення, і останні кілька він тримає для суперкористувачів. Він рахує кожне підключення: ваші прямі, підключення пулера, Data API, Auth і Storage. На безкоштовному тарифі їх разом 60. Зʼясуйте через pg_stat_activity, хто їх тримає, перш ніж міняти будь-яке налаштування.