1405/08/25 18:33:31
چرا Next.js به دیتابیس وصل نمی‌شود؟ آموزش رفع Too Many Connections

خطای Too many connections در Next.js معمولاً زمانی ظاهر می‌شود که برنامه بخواهد به دیتابیسی متصل شود که ظرفیت اتصال همزمان آن پر شده است. این مشکل ممکن است بعد از افزایش بازدید سایت، اجرای چند درخواست همزمان یا حتی به دلیل نحوه نادرست ساخت Connection در کد اتفاق بیفتد.

نکته مهم این است که همیشه افزایش ظرفیت دیتابیس راه حل مناسبی نیست. گاهی برنامه برای هر درخواست یک اتصال یا Connection Pool جدید می‌سازد؛ در چنین شرایطی حتی یک سایت با ترافیک متوسط هم می‌تواند تعداد زیادی اتصال همزمان ایجاد کند.

برای رفع خطای too many connections next.js باید ابتدا نحوه اتصال برنامه به دیتابیس را بررسی کنید، سپس با استفاده از الگوی Singleton و تنظیم درست Connection Pool، تعداد اتصال‌های غیرضروری را کاهش دهید. در ادامه، روش انجام این کار را برای Prisma و درایور مستقیم MySQL بررسی می‌کنیم.

خطای Too Many Connections در Next.js دقیقاً به چه معناست؟

MySQL برای جلوگیری از مصرف بی رویه منابع سرور، تعداد اتصال‌های همزمان را محدود می‌کند. این محدودیت با متغیر max_connections کنترل می‌شود. وقتی تمام ظرفیت اتصال دیتابیس در اختیار برنامه‌ها و کاربران دیگر باشد، اتصال جدید با خطای Too many connections مواجه می‌شود.

برای مثال، فرض کنید ظرفیت اتصال دیتابیس شما ۱۰۰ است. اگر برنامه Next.js، پنل مدیریت و سایر سرویس‌های متصل در مجموع تمام این ظرفیت را مصرف کنند، درخواست جدید دیگر نمی‌تواند به دیتابیس وصل شود.

این خطا لزوماً به معنی وجود یک مشکل در خود MySQL نیست؛ ممکن است برنامه اتصال‌های بیشتری از نیاز واقعی ایجاد کرده باشد یا اتصال‌های قبلی را به درستی مدیریت نکند.

چرا این خطا در پروژه‌های Next.js اتفاق می‌افتد؟

چند عامل رایج می‌توانند باعث افزایش تعداد Connection ها شوند:

  • ساخت چندین نمونه از Prisma Client: اگر در بخش‌های مختلف برنامه نمونه جدیدی از Prisma Client ساخته شود، هر نمونه می‌تواند Connection Pool مستقل داشته باشد.
  • ایجاد Pool در هر درخواست: اگر در هر بار اجرای API Route یک Connection Pool جدید ساخته شود، تعداد اتصال‌ها به مرور افزایش پیدا می‌کند.
  • تعداد زیاد درخواست‌های همزمان: اجرای Queryهای متعدد در یک بازه کوتاه می‌تواند ظرفیت Connection Pool را پر کند.
  • اجرای چند Process یا Instance: هر Process ممکن است Pool جداگانه‌ای داشته باشد؛ بنابراین تعداد کل اتصال‌ها بیشتر از چیزی می‌شود که در یک فایل تنظیم کرده‌اید.
  • تنظیم نامناسب Pool: اگر حداکثر تعداد اتصال‌ها برای هر نمونه برنامه بیش از ظرفیت دیتابیس باشد، با افزایش بار احتمال بروز خطا بیشتر می‌شود.

Connection Pool چیست و چه نقشی در جلوگیری از خطا دارد؟

به جای اینکه برنامه برای هر درخواست یک اتصال مستقل به MySQL بسازد، می‌تواند از مجموعه ای از اتصال‌های آماده استفاده کند. به این مجموعه Connection Pool گفته می‌شود.

وقتی یک درخواست به دیتابیس ارسال می‌شود، Pool یک اتصال آزاد را در اختیار آن قرار می‌دهد. بعد از پایان Query، اتصال دوباره به مجموعه برمی‌گردد تا درخواست بعدی بتواند از آن استفاده کند.

برای مثال، اگر تعداد اتصال‌های مجاز یک Pool برابر ۵ باشد، حداکثر پنج اتصال می‌توانند همزمان از آن Pool استفاده کنند. درخواست‌های بیشتر، بسته به تنظیمات درایور، در صف قرار می‌گیرند یا با خطا مواجه می‌شوند.

این روش دو مزیت مهم دارد: نیازی نیست برای هر Query یک اتصال جدید ساخته شود و تعداد اتصال‌های همزمان برنامه نیز قابل کنترل خواهد بود.

البته باید به یک تفاوت توجه کنید: Connection Pool با Singleton یک مفهوم نیست. Singleton از ساخته شدن چند نمونه از Client یا Pool در یک محیط اجرایی جلوگیری می‌کند؛ اما Connection Pool تعداد اتصال‌هایی را که همان نمونه می‌تواند به دیتابیس باز کند، مدیریت می‌کند. برای جلوگیری از خطای Too Many Connections معمولاً به هر دو نیاز دارید.

چطور با استفاده از Singleton تعداد اتصال‌های دیتابیس را کاهش دهیم؟

یکی از اشتباهات رایج در پروژه‌های Next.js، ساخت یک نمونه جدید از Prisma Client در فایل‌ها یا درخواست‌های مختلف است.

فرض کنید چند API Route دارید و داخل هر کدام دستور new PrismaClient() اجرا می‌شود. اگر هر بخش نمونه مستقلی بسازد، ممکن است چند Connection Pool جداگانه ایجاد شود و تعداد اتصال‌ها از ظرفیت دیتابیس عبور کند.

راهکار مناسب، ساخت یک فایل مشترک برای Prisma Client و استفاده مجدد از همان نمونه در تمام بخش‌های برنامه است.

پیاده سازی Singleton Prisma Client در Next.js

ابتدا یک فایل با نام lib/prisma.ts بسازید:

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

در این ساختار، برنامه به جای ساخت نمونه‌های متعدد، از یک Prisma Client مشترک استفاده می‌کند.

ذخیره نمونه در globalThis در محیط Development اهمیت بیشتری دارد؛ زیرا Hot Reload در Next.js ممکن است ماژول‌ها را دوباره بارگذاری کند و باعث ساخت نمونه‌های اضافی شود. در محیط Production، کش شدن ماژول Node.js برای استفاده مجدد از نمونه کافی است، مشروط به اینکه برنامه در همان Process اجرا شود.

حالا در فایل‌های دیگر، به جای ساخت Prisma Client جدید، همان نمونه را فراخوانی کنید:

import { prisma } from "@/lib/prisma";

export async function GET() {
  const users = await prisma.user.findMany();

  return Response.json(users);
}

این الگو باعث می‌شود بخش‌های مختلف برنامه از یک نمونه مشترک استفاده کنند.

توجه: در برنامه‌های Node.js که به صورت مداوم در حال سرویس دهی هستند، نباید بعد از هر Query دستور prisma.$disconnect() اجرا کنید. قطع اتصال بعد از هر درخواست باعث می‌شود برای درخواست بعدی دوباره فرایند برقراری اتصال انجام شود. مدیریت اتصال را به Prisma بسپارید و از قطع کردن مکرر آن خودداری کنید.

تنظیم Connection Pool در Prisma

حتی با پیاده سازی Singleton، باید حداکثر تعداد اتصال‌های Pool را متناسب با ظرفیت دیتابیس تنظیم کنید.

اگر از Prisma ORM نسخه ۶ یا پایین تر استفاده می‌کنید، می‌توانید پارامتر connection_limit را به آدرس اتصال دیتابیس اضافه کنید.

برای مثال:

DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/DATABASE?connection_limit=5&pool_timeout=10"

در این مثال، حداکثر تعداد اتصال‌های Pool برابر ۵ و حداکثر زمان انتظار برای دریافت اتصال آزاد از Pool برابر ۱۰ ثانیه است.

عدد ۵ صرفاً یک مقدار نمونه است و باید با توجه به تعداد Processها، محدودیت دیتابیس و میزان درخواست‌های همزمان انتخاب شود.

نکته نسخه ای مهم: در Prisma ORM نسخه ۷، مدیریت Pool از طریق Driver Adapter انجام می‌شود. برای MySQL و MariaDB می‌توانید از Adapter مربوط به MariaDB استفاده کنید و مقدار connectionLimit را در تنظیمات آن مشخص کنید:

import { PrismaMariaDb } from "@prisma/adapter-mariadb";
import { PrismaClient } from "@/generated/prisma";

const adapter = new PrismaMariaDb({
  host: process.env.DB_HOST!,
  port: 3306,
  user: process.env.DB_USER!,
  password: process.env.DB_PASSWORD!,
  database: process.env.DB_NAME!,
  connectionLimit: 5,
});

export const prisma = new PrismaClient({ adapter });

این نمونه مربوط به Prisma ORM نسخه ۷ و استفاده از @prisma/adapter-mariadb است. مسیر Import کلاینت نیز باید با مسیر خروجی تنظیم شده در پروژه شما هماهنگ باشد.

بنابراین هنگام تغییر نسخه Prisma، تنظیمات اتصال را هم بررسی کنید؛ روش نسخه ۶ و نسخه ۷ یکسان نیست.

اتصال مستقیم MySQL به Next.js با mysql2 چگونه انجام می‌شود؟

همه پروژه‌های Next.js از Prisma استفاده نمی‌کنند. بعضی توسعه دهندگان ترجیح می‌دهند مستقیماً از درایور MySQL مانند mysql2 برای اجرای Queryها استفاده کنند.

در این حالت هم باید به جای ساخت یک اتصال جدید برای هر درخواست، از یک Pool مشترک استفاده کنید.

ابتدا پکیج مورد نیاز را نصب کنید:

npm install mysql2

سپس فایلی با نام lib/db.ts بسازید:

import mysql from "mysql2/promise";

const globalForMysql = globalThis as unknown as {
  pool: ReturnType<typeof mysql.createPool> | undefined;
};

export const pool =
  globalForMysql.pool ??
  mysql.createPool({
    host: process.env.DB_HOST,
    port: Number(process.env.DB_PORT || 3306),
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME,

    waitForConnections: true,
    connectionLimit: 5,
    maxIdle: 5,
    idleTimeout: 60000,
    queueLimit: 20,
  });

if (process.env.NODE_ENV !== "production") {
  globalForMysql.pool = pool;
}

در این مثال، حداکثر پنج اتصال برای Pool در نظر گرفته شده است. با فعال بودن waitForConnections، اگر تمام اتصال‌ها مشغول باشند، درخواست‌های جدید برای دریافت اتصال در صف قرار می‌گیرند. مقدار queueLimit نیز تعداد درخواست‌های منتظر در صف را محدود می‌کند.

حالا می‌توانید در API Route از Pool مشترک استفاده کنید:

import { pool } from "@/lib/db";

export async function GET() {
  const [rows] = await pool.execute(
    "SELECT * FROM users LIMIT 10"
  );

  return Response.json(rows);
}

در این روش، pool.execute() اتصال مورد نیاز را از Pool دریافت و پس از اجرای Query آزاد می‌کند.

اگر به صورت دستی از pool.getConnection() استفاده می‌کنید، باید بعد از پایان عملیات اتصال را با connection.release() به Pool برگردانید. بهتر است این کار را در بلوک finally انجام دهید تا حتی در صورت بروز خطا، اتصال بلااستفاده باقی نماند.

برای مثال:

const connection = await pool.getConnection();

try {
  const [rows] = await connection.execute(
    "SELECT * FROM users"
  );

  return rows;
} finally {
  connection.release();
}

مستندات mysql2 نیز بر آزاد کردن اتصال پس از پایان کار تأکید می‌کند.

آیا افزایش max_connections در MySQL مشکل را حل می‌کند؟

متغیر max_connections تعداد اتصال‌های همزمان مجاز به سرور MySQL را مشخص می‌کند. برای مشاهده مقدار فعلی آن، دستور زیر را اجرا کنید:

SHOW VARIABLES LIKE 'max_connections';

برای بررسی تعداد اتصال‌های فعال:

SHOW STATUS LIKE 'Threads_connected';

و برای مشاهده بیشترین تعداد اتصال همزمان ثبت شده از زمان راه اندازی سرور:

SHOW STATUS LIKE 'Max_used_connections';

همچنین دستور زیر اطلاعات دقیق تری درباره اتصال‌های فعال و وضعیت آن‌ها نمایش می‌دهد:

SHOW PROCESSLIST;

این اطلاعات کمک می‌کنند تشخیص دهید آیا واقعاً ظرفیت دیتابیس پر شده است یا مشکل از مدیریت Pool در برنامه است.

افزایش max_connections در بعضی شرایط می‌تواند راهکار مناسبی باشد؛ اما نباید اولین اقدام شما باشد. هر اتصال دیتابیس منابعی مانند حافظه را مصرف می‌کند و بالا بردن بی رویه محدودیت اتصال می‌تواند فشار بیشتری به سرور وارد کند.

برای مثال، اگر برنامه به دلیل ایجاد چند Pool مستقل اتصال‌های غیرضروری می‌سازد، افزایش max_connections فقط زمان بروز مجدد مشکل را عقب می‌اندازد.

بهتر است ابتدا تعداد اتصال‌های فعال، نمونه‌های Client و ظرفیت Poolها بررسی شوند. بعد از اصلاح ساختار برنامه، در صورت نیاز می‌توان محدودیت دیتابیس را با توجه به منابع موجود تنظیم کرد.

نقش محیط Production و هاست Next.js در تعداد اتصال‌ها

یکی از مواردی که هنگام انتقال پروژه از سیستم توسعه به هاست نادیده گرفته می‌شود، تفاوت مدل اجرای برنامه در این دو محیط است.

در محیط Development معمولاً یک Process برنامه را اجرا می‌کند؛ اما در Production ممکن است چند Process یا Instance به صورت همزمان درخواست‌ها را پردازش کنند. هر کدام از این نمونه‌ها می‌توانند Connection Pool مستقل داشته باشند.

برای مثال، فرض کنید برنامه شما سه Process دارد و برای هر کدام یک Pool با ظرفیت ۱۰ اتصال تنظیم کرده‌اید. در این شرایط، ظرفیت بالقوه اتصال برنامه به دیتابیس می‌تواند به ۳۰ اتصال برسد؛ نه ۱۰ اتصال.

فرمول ساده محاسبه حداکثر اتصال‌های بالقوه به شکل زیر است:

Total Connections = Instances × Pool Size

این محاسبه برای برآورد اولیه است و در عمل تعداد اتصال‌های باز شده به میزان استفاده، رفتار Pool و تنظیمات درایور بستگی دارد.

در محیط‌های Serverless نیز شرایط متفاوت است. هر Function یا نمونه اجرایی ممکن است Pool خودش را داشته باشد. به همین دلیل، با افزایش ناگهانی درخواست‌ها، تعداد اتصال‌ها می‌تواند سریع تر از انتظار افزایش پیدا کند.

برای جلوگیری از این مشکل، ظرفیت Pool را بر اساس مجموع Instanceهای برنامه تنظیم کنید، نه فقط تعداد اتصال‌های یک نمونه. مستندات Prisma نیز در محیط‌های دارای چند Instance بر تقسیم ظرفیت اتصال میان آن‌ها تأکید می‌کند.

نکاتی که هنگام انتخاب هاست Next.js باید بررسی کنید

برای میزبانی یک پروژه Next.js متصل به MySQL، فقط مقدار RAM یا CPU را در نظر نگیرید. نحوه اجرای برنامه و محدودیت‌های دیتابیس نیز اهمیت دارند.

موارد زیر را بررسی کنید:

  • تعداد Processهایی که برنامه را اجرا می‌کنند.
  • امکان اجرای همزمان چند Instance از پروژه.
  • محدودیت تعداد اتصال دیتابیس و محدودیت اتصال هر کاربر دیتابیس.
  • سازگاری نسخه Node.js با پروژه و پکیج‌های مورد استفاده.
  • منابع در دسترس برای پردازش درخواست‌های همزمان.
  • امکان مشاهده لاگ‌های برنامه و خطاهای اتصال به دیتابیس.

برای مثال، ممکن است کد برنامه کاملاً درست باشد، اما تعداد Processهای اجرایی به همراه ظرفیت Pool هر کدام از حد مجاز دیتابیس بیشتر شود. در چنین شرایطی تغییر کد Singleton به تنهایی مشکل را برطرف نمی‌کند.

در زمان انتخاب یا تغییر سرویس میزبانی، مشخصات فنی و محدودیت‌های اتصال دیتابیس را بررسی کنید. برای آشنایی با سرویس‌های آویس هاست می‌توانید صفحه هاست Next.js را مشاهده کنید.

آیا Promise.all باعث افزایش اتصال‌های دیتابیس می‌شود؟

استفاده از Promise.all() به خودی خود باعث ساخت Connection Pool جدید نمی‌شود؛ اما می‌تواند تعداد Query های همزمان را افزایش دهد.

برای مثال:

const results = await Promise.all([
  prisma.user.findMany(),
  prisma.product.findMany(),
  prisma.order.findMany(),
  prisma.category.findMany(),
  prisma.post.findMany(),
]);

در این مثال، پنج Query به صورت همزمان اجرا می‌شوند. اگر تعداد عملیات بیشتر شود و درخواست‌های کاربران نیز همزمان به برنامه برسند، فشار بیشتری به Connection Pool وارد می‌شود.

اگر ظرفیت Pool کافی نباشد، درخواست‌ها باید منتظر آزاد شدن اتصال بمانند. در بعضی شرایط نیز زمان انتظار از محدودیت تعیین شده عبور می‌کند و خطای Pool Timeout رخ می‌دهد.

برای مدیریت بهتر این وضعیت، Queryهای غیرضروری را کاهش دهید و از اجرای تعداد زیادی عملیات موازی بدون محدودیت خودداری کنید. در عملیات حجیم، می‌توانید Queryها را در دسته‌های کوچک تر اجرا کنید یا تعداد عملیات همزمان را با یک محدودکننده Concurrency کنترل کنید.

نکته مهم این است که افزایش Queryهای موازی الزاماً به معنی افزایش تعداد اتصال‌های بازشده نیست؛ Pool تعداد اتصال‌های خود را بر اساس ظرفیت تنظیم شده کنترل می‌کند. مشکل زمانی جدی می‌شود که حجم درخواست‌ها از ظرفیت پردازش Pool بیشتر شود یا نمونه‌های متعدد برنامه، Poolهای جداگانه بسازند.

تفاوت خطای Too Many Connections با Connection Timeout چیست؟

این دو خطا ممکن است در ظاهر شبیه باشند، اما لزوماً یک مشکل را نشان نمی‌دهند.

نوع خطا

مفهوم

علت احتمالی

Too Many Connections

دیتابیس ظرفیت اتصال همزمان ندارد

پر شدن محدودیت اتصال MySQL

Connection Timeout

برقراری اتصال در زمان مشخص انجام نشده است

کندی شبکه یا پاسخ ندادن دیتابیس

Pool Timeout

اتصال آزاد از Pool در زمان تعیین شده دریافت نشده است

مشغول بودن اتصال‌ها یا افزایش Queryهای همزمان

برای مثال، در Prisma ممکن است با خطای P2024 مواجه شوید. این خطا به معنای تمام شدن زمان انتظار برای دریافت اتصال از Connection Pool است و نباید آن را دقیقاً معادل خطای MySQL با متن Too many connections در نظر گرفت.

به همین دلیل، هنگام بررسی لاگ‌ها فقط به عبارت Connection توجه نکنید. متن کامل خطا، کد آن و زمان وقوع مشکل می‌توانند به شناسایی علت اصلی کمک کنند.

چک لیست رفع خطای Too Many Connections در پروژه Next.js

اگر سایت شما با این خطا مواجه شده، بهتر است بررسی را به ترتیب زیر انجام دهید:

  1. تعداد اتصال‌های فعال MySQL را با Threads_connected بررسی کنید.
  2. مقدار max_connections و در صورت نیاز max_user_connections را بررسی کنید.
  3. مطمئن شوید در پروژه فقط از یک نمونه مشترک Prisma Client یا MySQL Pool در هر Process استفاده می‌شود.
  4. مقدار connection_limit یا connectionLimit را متناسب با ظرفیت دیتابیس تنظیم کنید.
  5. تعداد Processها و Instanceهای فعال برنامه را مشخص کنید.
  6. Queryهای موازی و عملیات سنگین دیتابیس را بررسی کنید.
  7. مطمئن شوید اتصال‌هایی که به صورت دستی دریافت می‌شوند، بعد از پایان عملیات آزاد شده‌اند.
  8. لاگ‌های Next.js و MySQL را بعد از اعمال تغییرات دوباره بررسی کنید.

این ترتیب کمک می‌کند به جای افزایش تصادفی محدودیت اتصال، علت اصلی مشکل را پیدا کنید.

سوالات متداول

چرا Next.js هنگام افزایش بازدید سایت به دیتابیس متصل نمی‌شود؟

یکی از دلایل احتمالی، پر شدن ظرفیت اتصال همزمان دیتابیس است. ایجاد Connection Poolهای متعدد، تنظیم نامناسب محدودیت اتصال و افزایش تعداد درخواست‌های همزمان می‌توانند باعث بروز این مشکل شوند.

آیا استفاده از Singleton در Next.js برای رفع خطا کافی است؟

خیر. Singleton از ایجاد نمونه‌های متعدد Client در یک Process جلوگیری می‌کند، اما تعداد اتصال‌های هر Pool را محدود نمی‌کند. برای مدیریت کامل اتصال‌ها باید تنظیمات Connection Pool و تعداد Processهای برنامه را هم بررسی کنید.

حداکثر Connection Pool برای Prisma چقدر باید باشد؟

عدد ثابتی برای تمام پروژه‌ها وجود ندارد. این مقدار به ظرفیت دیتابیس، تعداد Instanceهای برنامه، منابع سرور و میزان درخواست‌های همزمان بستگی دارد. در محیط‌های Serverless نیز باید تعداد Functionهای همزمان را در محاسبات لحاظ کنید.

آیا بعد از هر درخواست باید اتصال دیتابیس را قطع کنیم؟

خیر. در برنامه‌های Node.js با اجرای مداوم، بهتر است Connection Pool یا Prisma Client را بین درخواست‌ها حفظ کنید. قطع اتصال بعد از هر Query باعث ایجاد مجدد اتصال و افزایش سربار ارتباط با دیتابیس می‌شود.

جمع بندی

خطای too many connections next.js معمولاً نشانه مصرف شدن ظرفیت اتصال همزمان دیتابیس است؛ اما علت اصلی آن می‌تواند از نحوه پیاده سازی برنامه تا تنظیمات هاست و دیتابیس متفاوت باشد.

برای جلوگیری از این مشکل، از یک نمونه مشترک Prisma Client یا MySQL Pool در هر Process استفاده کنید، تعداد اتصال‌های Pool را متناسب با ظرفیت دیتابیس تنظیم کنید و درخواست‌های همزمان را تحت کنترل داشته باشید.

در پروژه‌های Production نیز تعداد Processها و Instanceها را در محاسبه ظرفیت اتصال لحاظ کنید. با این روش، احتمال پر شدن بی دلیل Connection Pool کاهش پیدا می‌کند و برنامه در شرایط افزایش ترافیک، ارتباط پایدارتری با دیتابیس خواهد داشت.

اگر پروژه Next.js شما روی هاست اجرا می‌شود و همچنان با خطای اتصال دیتابیس مواجه هستید، لاگ برنامه، تنظیمات Pool و محدودیت‌های دیتابیس را در کنار منابع سرور بررسی کنید؛ گاهی مشکل از کد نیست، بلکه ظرفیت و مدل اجرای سرویس با نیاز پروژه تناسب ندارد.