→ سیستم‌نامه

خطای Error establishing a database connection در ووکامرس: راهنمای کامل عیب‌یابی و رفع ریشه‌ای (بر اساس یک پرونده واقعی)

11 دقیقه مطالعهآخرین بروزرسانی: سپتامبر 24, 2026

صفحه‌ی سفیدی که فقط یک جمله روی آن نوشته شده: Error establishing a database connection. برای یک فروشگاه اینترنتی، این یعنی هیچ مشتری‌ای نمی‌تواند محصولی ببیند، سبد خریدی بسازد یا پرداختی انجام دهد. در این مقاله یک پرونده‌ی واقعی از فروشگاه‌های زنجیره‌ای لارا را قدم‌به‌قدم مرور می‌کنم: از لحظه‌ی دیدن خطا تا پیدا کردن ریشه‌ی مشکل و رفع دائمی آن. هدف این است که اگر روزی با همین خطا روبه‌رو شدید، یک روش منظم داشته باشید، نه یک لیست از حدس‌های تصادفی.

این خطا دقیقاً چه معنایی دارد؟

وردپرس در ابتدای هر درخواست، قبل از هر کار دیگری، به پایگاه داده (MySQL یا MariaDB) وصل می‌شود. اگر این اتصال به هر دلیلی برقرار نشود، وردپرس کار را متوقف می‌کند و همین پیام را نشان می‌دهد. نکته‌ی مهم این است که این پیام علت را نمی‌گوید؛ فقط می‌گوید اتصال برقرار نشد. علت‌های رایج عبارت‌اند از:

  • اطلاعات اتصال اشتباه در فایل wp-config.php (نام دیتابیس، نام کاربری، رمز عبور یا آدرس هاست).
  • از کار افتادن سرویس MySQL روی سرور.
  • خراب شدن جدول‌ها یا مشکل در خود دیتابیس.
  • پر شدن ظرفیت اتصال‌ها؛ یعنی سرور سالم است، ولی به اتصال جدید اجازه نمی‌دهد.

مورد آخر معمولاً از همه گول‌زننده‌تر است، چون همه‌چیز سالم به نظر می‌رسد و خطا گاهی می‌آید و گاهی نمی‌آید. پرونده‌ی ما دقیقاً از همین نوع بود.

قدم اول: حدس نزنید، حذف کنید

اولین واکنش بیشتر افراد این است که افزونه‌ها را یکی‌یکی غیرفعال کنند یا هاست را مقصر بدانند. روش درست‌تر این است که احتمال‌ها را با شواهد یکی‌یکی کنار بگذارید:

  1. بررسی wp-config.php: نام دیتابیس، کاربر و هاست را با اطلاعات پنل هاست (مثلاً بخش MySQL Databases در cPanel) مقایسه کنید. در پرونده‌ی ما همه‌چیز درست بود.
  2. بررسی دسترسی کاربر: مطمئن شوید کاربر دیتابیس به دیتابیس سایت دسترسی کامل (ALL PRIVILEGES) دارد. این هم درست بود.
  3. بررسی سالم بودن سرویس MySQL: اگر phpMyAdmin یا ابزارهای پنل هاست به دیتابیس وصل می‌شوند، سرویس بالاست. این هم درست بود.
  4. تست مستقیم اتصال با پیام خطای واقعی: اینجا بود که ماجرا روشن شد.

قدم دوم: پیام خطای واقعی را بیرون بکشید

وردپرس پیام خطای اصلی MySQL را پنهان می‌کند. برای دیدنش می‌توان یک فایل PHP موقت ساخت که با همان اطلاعات wp-config به دیتابیس وصل شود و شماره و متن خطا را چاپ کند:

<?php
mysqli_report(MYSQLI_REPORT_OFF);
$link = @mysqli_connect('localhost', 'DB_USER', 'DB_PASSWORD', 'DB_NAME', 3306);
echo $link ? 'OK' : mysqli_connect_errno() . ' ' . mysqli_connect_error();

نتیجه در پرونده‌ی ما این بود:

1226 User has exceeded the 'max_user_connections' resource (current value: 30)

یعنی رمز و تنظیمات درست بودند، ولی هاست برای هر کاربر دیتابیس حداکثر ۳۰ اتصال هم‌زمان اجازه می‌داد و این سقف پر شده بود. هر درخواستی که بعد از پر شدن سقف می‌رسید، رد می‌شد و وردپرس همان صفحه‌ی خطا را نشان می‌داد. (تفاوت max_connections و max_user_connections را در مقاله‌ی max_connections در برابر max_user_connections مفصل توضیح داده‌ام.)

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

قدم سوم: ببینید چه کسی اتصال‌ها را گرفته است

وقتی می‌دانید سقف پر شده، سؤال بعدی این است: این ۳۰ اتصال مشغول چه کاری هستند؟ با کوئری زیر می‌توانید فهرست اتصال‌های فعال کاربر خودتان را ببینید:

SELECT COMMAND, TIME, STATE, LEFT(INFO, 150)
FROM information_schema.PROCESSLIST
WHERE USER = 'DB_USER'
ORDER BY TIME DESC;

یک بار نگاه کردن کافی نیست. بهتر است چند بار در فاصله‌ی چند ثانیه نمونه بگیرید و کوئری‌ها را بر اساس نوع دسته‌بندی کنید تا الگو مشخص شود. در پرونده‌ی ما، از حدود ۶۰۰ نمونه‌ی کوئری فعال، بیش از ۵۸۰ مورد یک کوئری DELETE یکسان بود که از افزونه‌ی ورود با موبایل (Digits) می‌آمد و بعضی‌هایشان تا ۲۴ ثانیه طول می‌کشیدند.

ریشه‌ی اول: جدولی که بی‌صدا بزرگ شده بود

افزونه‌ی Digits برای هر بازدیدکننده اطلاعات کشورِ IP او را در یک جدول جداگانه ذخیره می‌کرد و در هر بازدید یک ردیف را از همان جدول حذف و دوباره ثبت می‌کرد. دو مشکل هم‌زمان وجود داشت:

  • جدول به حدود ۱۶۵ هزار ردیف رسیده بود که تقریباً همه‌اش کش موقت بود.
  • روی ستون‌هایی که کوئری DELETE بر اساس آن‌ها جستجو می‌کرد هیچ ایندکسی وجود نداشت.

نتیجه: هر DELETE مجبور بود کل جدول را بگردد و در این مدت جدول را قفل نگه دارد. درخواست‌های بعدی پشت این قفل صف می‌شدند، هر کدام یک اتصال را اشغال می‌کردند و خیلی زود سقف ۳۰ پر می‌شد. این همان دلیلی است که چنین مشکلی «ناگهان» ظاهر می‌شود: تا وقتی جدول کوچک است همه‌چیز سریع است، ولی از یک اندازه به بعد رفتار سیستم یک‌باره عوض می‌شود.

راه‌حل: اضافه کردن ایندکس، بدون قفل کردن سایت

در MySQL 8 و InnoDB می‌توان ایندکس را به‌صورت آنلاین اضافه کرد تا در حین ساخت، جدول قفل نشود:

ALTER TABLE wp_digits_user_session
  ADD INDEX idx_key_token (data_key(100), session_token(100)),
  ALGORITHM=INPLACE, LOCK=NONE;

ساخت این ایندکس کمتر از ۴ ثانیه طول کشید و بلافاصله بعد از آن، طولانی‌ترین کوئری از ۲۴ ثانیه به حدود ۱ ثانیه رسید. چون ستون‌ها از نوع متن بلند بودند، فقط ۱۰۰ کاراکتر اول هر ستون ایندکس شد (prefix index) که برای این نوع جستجو کاملاً کافی است.

پاکسازی امن: اول پشتیبان، بعد حذف دسته‌ای

بعد از پایدار شدن اوضاع، ردیف‌های اضافه را پاک کردیم. سه قانون را رعایت کردیم:

  1. فقط داده‌ی قابل بازسازی را پاک کنید. ردیف‌های کش کشورِ IP و سشن‌های منقضی‌شده را حذف کردیم، ولی به سشن‌های معتبر لاگین مشتری‌ها دست نزدیم.
  2. قبل از حذف، نسخه‌ی پشتیبان بگیرید. ردیف‌هایی را که قرار بود حذف شوند، در یک جدول جداگانه کپی کردیم تا در صورت نیاز قابل بازگشت باشند.
  3. دسته‌ای حذف کنید، نه یک‌جا. حذف ۱۶۵ هزار ردیف با یک دستور، خودش می‌تواند جدول را قفل کند. به همین دلیل حذف در دسته‌های ۲۰۰۰تایی و با مکث کوتاه بین هر دسته انجام شد.
CREATE TABLE wp_digits_user_session_bak LIKE wp_digits_user_session;
INSERT INTO wp_digits_user_session_bak
  SELECT * FROM wp_digits_user_session
  WHERE data_key LIKE 'digits\_country\_info\_%'
     OR session_expiry < NOW();

-- تکرار تا وقتی ردیفی باقی نماند:
DELETE FROM wp_digits_user_session
WHERE data_key LIKE 'digits\_country\_info\_%'
   OR session_expiry < NOW()
LIMIT 2000;

جدول از حدود ۱۶۵ هزار ردیف به ۲ ردیف رسید. (روش کلی پاکسازی امن دیتابیس وردپرس را در مقاله‌ی جداگانه‌ای هم نوشته‌ام: اول اندازه بگیر، بعد پشتیبان بگیر، بعد فقط زباله‌ی اثبات‌شده را حذف کن.)

ریشه‌ی دوم: رباتی که قانون مسدودسازی را دور می‌زد

حتی بعد از رفع مشکل Digits، هنوز حدود ۲۸ اتصال هم‌زمان مشغول بود. بررسی لاگ بازدیدها در cPanel (بخش Visitors) تصویر روشنی داد:

  • حدود ۱۰۰۰ درخواست در ۲ دقیقه.
  • همه‌ی نمونه‌های بررسی‌شده روی URLهای فیلتر محصول بودند؛ یعنی ترکیب‌های مختلف برند، رایحه، نوع محصول و مرتب‌سازی.
  • ۲۵ درخواست از ۲۴ آی‌پی مختلف می‌آمد؛ یک شبکه‌ی ربات توزیع‌شده.
  • هیچ‌کدام Referer نداشتند.

در فایل robots.txt این مسیرها از قبل مسدود شده بودند، ولی ربات‌های مخرب robots.txt را نادیده می‌گیرند. در فایل .htaccess هم قانونی برای مسدود کردن این ربات بر اساس User-Agent وجود داشت که روی یک نسخه‌ی مشخص از مرورگر Chrome تنظیم شده بود. ربات حالا نسخه‌ی Chrome خود را مدام عوض می‌کرد (۱۱۹، ۱۳۶، ۱۴۲، ۱۴۶…) و از قانون رد می‌شد. هر درخواست فیلتر، یک صفحه‌ی بدون کش می‌ساخت که حدود ۷ ثانیه طول می‌کشید و در تمام این مدت یک اتصال دیتابیس را اشغال می‌کرد. (داستان کامل‌تر نبرد با کراولرهای فیلتر ووکامرس را در این مقاله نوشته‌ام.)

راه‌حل: قانون بر اساس رفتار، نه بر اساس ظاهر

User-Agent را می‌شود به‌راحتی جعل و عوض کرد. به جای آن، سراغ یک تفاوت رفتاری رفتیم: کاربر واقعی روی فیلتر کلیک می‌کند و مرورگرش Referer می‌فرستد؛ ربات مستقیم به URL فیلتر می‌رود. بنابراین درخواست‌های فیلتر بدون Referer به نسخه‌ی تمیز صفحه (بدون پارامترهای فیلتر) هدایت می‌شوند که از کش تحویل داده می‌شود:

RewriteCond %{HTTP_REFERER} ^-?$
RewriteCond %{HTTP_USER_AGENT} !(googlebot|bingbot|yandex|duckduckbot|applebot) [NC]
RewriteCond %{REQUEST_URI} ^/(product-category|product-attribute|brand|shop)/ [NC]
RewriteCond %{QUERY_STRING} (^|&)(filter_[^=]+|query_type_[^=]+|min_price|max_price|orderby|rating_filter|stock_status)= [NC]
RewriteRule ^(.*)$ /$1? [R=302,L]

چرا ریدایرکت و نه خطای 403؟ چون ممکن است یک مشتری واقعی لینک یک صفحه‌ی فیلترشده را از جایی کپی کرده و مستقیم باز کند. با ریدایرکت، او به‌جای صفحه‌ی خطا، صفحه‌ی دسته‌بندی را می‌بیند. در تست، درخواست ربات در ۴۱ میلی‌ثانیه ریدایرکت شد؛ در حالی که قبلاً ۷ ثانیه دیتابیس را درگیر می‌کرد.

ریشه‌ی سوم: کشی که درست کار نمی‌کرد

در یک فروشگاه ووکامرس روی هاست اشتراکی، کش صفحه مهم‌ترین عامل پایداری سایت است. با فعال بودن LiteSpeed Cache، صفحه‌ای که قبلاً ساخته شده در حدود ۰.۱ ثانیه و بدون هیچ اتصالی به دیتابیس تحویل داده می‌شود. همان صفحه بدون کش حدود ۷ ثانیه طول می‌کشد و یک اتصال را اشغال می‌کند. با سقف ۳۰ اتصال، کافی است حدود ۵ درخواست بدون کش در ثانیه برسد تا سایت از دسترس خارج شود.

در این پرونده، کش به چند دلیل مدام خالی می‌شد و سرعت ساخت صفحه‌ها هم پایین بود. رفع این موارد، در کنار دو اقدام قبلی، فشار روی دیتابیس را به‌شدت کم کرد.

یک هشدار مهم: در زمان بحران، وسوسه می‌شوید افزونه‌ی کش را خاموش کنید تا «مطمئن شوید مشکل از آن نیست». در مورد این خطا، این دقیقاً برعکس نتیجه می‌دهد: با خاموش شدن کش، همه‌ی درخواست‌ها به دیتابیس می‌رسند و سقف اتصال‌ها فوراً پر می‌شود. افزونه‌های امنیتی سنگین مثل Wordfence را می‌شود موقتاً غیرفعال کرد، چون روی هر بازدید در دیتابیس می‌نویسند؛ ولی کش باید روشن بماند.

نتیجه‌ی نهایی

شاخص قبل بعد
وضعیت سایت خطای اتصال به دیتابیس در دسترس
طولانی‌ترین کوئری ۲۴ ثانیه حدود ۱ ثانیه
ردیف‌های جدول کش Digits حدود ۱۶۵ هزار ۲
درخواست فیلتر ربات حدود ۷ ثانیه با اشغال یک اتصال ۴۱ میلی‌ثانیه، بدون دیتابیس
صفحه‌ی کش‌شده برای بازدیدکننده — حدود ۰.۱ ثانیه

چک‌لیست عیب‌یابی این خطا

  1. اطلاعات wp-config.php را با پنل هاست مقایسه کنید.
  2. دسترسی کاربر دیتابیس را بررسی کنید.
  3. مطمئن شوید سرویس MySQL بالاست (مثلاً phpMyAdmin باز می‌شود).
  4. با یک فایل تست موقت، شماره‌ی خطای واقعی MySQL را ببینید. اگر 1226 بود، مشکل از پر شدن سقف اتصال‌هاست.
  5. از PROCESSLIST چند بار نمونه بگیرید و ببینید کدام کوئری‌ها اتصال‌ها را اشغال کرده‌اند.
  6. کوئری‌های کند را با EXPLAIN بررسی کنید و ایندکس‌های لازم را به‌صورت آنلاین اضافه کنید.
  7. لاگ بازدیدها را برای الگوهای ربات بررسی کنید، به‌خصوص روی URLهای فیلتر و جستجو.
  8. مطمئن شوید کش صفحه روشن است و واقعاً صفحه‌ها را کش می‌کند (هدر x-litespeed-cache: hit).
  9. هر تغییر را با اندازه‌گیری قبل و بعد تأیید کنید.

درس‌هایی برای پیشگیری

  • جدول‌های افزونه‌ها را زیر نظر داشته باشید. جدول‌هایی که با هر بازدید بزرگ‌تر می‌شوند، باید پاکسازی دوره‌ای داشته باشند.
  • قانون امنیتی را بر اساس رفتار بنویسید، نه ظاهر. User-Agent و IP را می‌شود عوض کرد؛ الگوی رفتاری را سخت‌تر.
  • کش صفحه ستون اصلی پایداری است. هر کدی که کش را پاک می‌کند باید حساب‌شده و محدود باشد.
  • محدودیت هاست را بشناسید. سقف max_user_connections را از پشتیبانی بپرسید. اگر با بهینه‌سازی هم کافی نبود، زمان ارتقای سرویس یا استفاده از CDN با محافظ ربات رسیده است.
  • یک مسیر گزارش سریع داشته باشید. تیم فروش و پشتیبانی معمولاً اولین کسانی هستند که مشکل را می‌بینند؛ باید بدانند فوراً و در هر ساعتی با چه کسی تماس بگیرند.

خطای Error establishing a database connection معمولاً علامت است، نه بیماری. اگر به‌جای حدس زدن، پیام خطای واقعی را بیرون بکشید و ببینید دیتابیس دقیقاً مشغول چه کاری است، معمولاً ریشه‌ی مشکل در چند قدم پیدا می‌شود.

SOS سایتت خوابیده؟