پیام Error establishing a database connection یعنی وردپرس نتوانسته یک اتصال قابل استفاده به MySQL یا MariaDB بسازد. علت می‌تواند نام کاربری یا رمز اشتباه، متوقف شدن سرویس دیتابیس، پر شدن اتصال‌ها، خطای DNS یا شبکه، خرابی محدود جداول یا فشار منابع باشد. اولین واکنش نباید repair یا restore دیتابیس باشد؛ ابتدا باید معلوم شود اتصال اصلاً برقرار نمی‌شود یا پس از اتصال، queryها شکست می‌خورند.
پاسخ سریع: زمان شروع خطا را ثبت کنید، از وضعیت فعلی backup بگیرید، مقادیر DB_NAME، DB_USER و DB_HOST را بدون افشای رمز با تنظیمات واقعی مقایسه کنید، سلامت سرویس دیتابیس و error log آن را ببینید و اتصال را از همان میزبان برنامه آزمایش کنید. تغییر رمز، repair و restart کور می‌تواند شواهد یا دسترسی سرویس‌های دیگر را خراب کند.
الگوی خطا سرنخ مهمی است
| الگو | علت‌های محتمل |
|---|---|
| پس از انتقال یا تغییر رمز | wp-config، host، privilege یا DNS |
| گاه‌به‌گاه در ترافیک بالا | اتصال‌های اشباع، query کند، CPU یا I/O |
| همه سرویس‌های متصل خراب‌اند | سرویس دیتابیس، دیسک، شبکه یا crash |
| فقط یک سایت در سرور مشترک | credential، database name یا مجوز همان کاربر |
| wp-admin پیام repair می‌دهد | احتمال ناسازگاری یا خرابی جدول؛ نیازمند شاهد بیشتر |
تنظیمات wp-config.php را دقیق کنترل کنید
چهار مقدار اصلی در wp-config.php عبارت‌اند از DB_NAME، DB_USER، DB_PASSWORD و DB_HOST. رمز را در ticket، screenshot یا command history منتشر نکنید. در میزبانی اشتراکی ممکن است پیشوند حساب جزئی از نام database و user باشد. در Docker، localhost معمولاً خود container وردپرس است، نه container دیتابیس؛ نام service یا endpoint تعریف‌شده در همان شبکه باید استفاده شود.
پورت غیرپیش‌فرض یا socket باید مطابق مستندات محیط در DB_HOST بیان شود. قالب یک نمونه را کور کپی نکنید؛ نحوه تفسیر host به driver و پیکربندی PHP نیز وابسته است.
آیا MySQL واقعاً در حال سرویس‌دهی است؟
روی سرورهای systemd، وضعیت و رخدادهای اخیر را بخوانید. نام unit ممکن است mysql یا mariadb باشد:
systemctl status mysql
journalctl -u mysql --since "15 minutes ago"این فرمان‌ها وضعیت را تغییر نمی‌دهند. اگر سرویس متوقف است، پیش از restart علت را در log پیدا کنید: پر شدن disk، OOM، خطای InnoDB و اشکال config مسیرهای متفاوتی دارند. restart ممکن است سایت را موقتاً برگرداند اما root cause را پنهان می‌کند.
اتصال را از محل اجرای وردپرس آزمایش کنید
آزمون از لپ‌تاپ شما مسیر شبکه production را ثابت نمی‌کند. اتصال باید از همان VM یا container برنامه بررسی شود. برای جلوگیری از ثبت رمز در history، از prompt تعاملی client استفاده کنید:
mysql -h DATABASE_HOST -u DATABASE_USER -p DATABASE_NAMEخطای Access denied با Connection refused یکسان نیست. اولی معمولاً به credential یا privilege مربوط است؛ دومی به listener، host، port، firewall یا سرویس. timeout بیشتر به مسیر شبکه یا overload اشاره می‌کند. متن کامل خطا را نگه دارید، اما secret را حذف کنید.
DNS، socket و شبکه container را فراموش نکنید
اگر DB_HOST یک hostname است، resolve شدن آن را در همان محیط PHP بررسی کنید. container ممکن است DNS و فایل hosts متفاوتی با میزبان داشته باشد. در Docker Compose نام service فقط روی network مشترک قابل resolve است و publish کردن پورت دیتابیس برای ارتباط داخلی لازم نیست. اتصال Unix socket نیز به وجود همان فایل داخل محیط اجرای PHP وابسته است؛ socket میزبان خودبه‌خود داخل container دیده نمی‌شود.
اگر دیتابیس remote است، route، security group و محدودیت مبدأ را بررسی کنید. باز کردن پورت 3306 برای همه اینترنت راه‌حل قابل قبول نیست. دسترسی باید فقط از مبدأهای لازم و ترجیحاً روی شبکه خصوصی یا تونل امن برقرار شود.
منابع و ظرفیت اتصال
اگر خطا مقطعی است، تعداد connectionهای فعال، slow queryها، CPU، RAM، I/O و رخدادهای OOM را در همان بازه مقایسه کنید. افزایش max_connections بدون محاسبه حافظه می‌تواند crash را شدیدتر کند. connection pool یا plugin معیوب نیز ممکن است اتصال را آزاد نکند. ابتدا مصرف‌کننده و مدت query مشخص شود.
چه زمانی repair مطرح می‌شود؟
repair برای credential اشتباه یا سرویس خاموش کاربردی ندارد. فقط وقتی log و ابزار دیتابیس خرابی جدول را نشان می‌دهند، با backup معتبر و شناخت engine اقدام کنید. ثابت WP_ALLOW_REPAIR صفحه‌ای بدون احراز هویت معمول مدیریت ایجاد می‌کند؛ اگر موقتاً استفاده شد بلافاصله حذف شود. برای InnoDB، روش بازیابی باید بر اساس پیام واقعی MySQL و وضعیت backup انتخاب شود و اجرای دستورهای تغییر‌دهنده بدون نسخه بازیابی توصیه نمی‌شود.
پس از انتقال سایت چه چیزهایی بیشتر خطا می‌کنند؟
- نام database یا user در مقصد با مبدا متفاوت است.
- کاربر ساخته شده اما privilege دیتابیس درست اعطا نشده است.
- hostname قدیمی، private IP یا نام Docker service تغییر کرده است.
- firewall فقط subnet قبلی را مجاز می‌داند.
- DNS داخلی یا TLS دیتابیس مطابق مقصد تنظیم نشده است.
اشتباه‌های پرریسک
- قرار دادن رمز واقعی در دستور، چت یا log عمومی.
- حذف و ساخت دوباره کاربر دیتابیس بدون بررسی مصرف‌کنندگان دیگر.
- restore فوری backup قدیمی در فروشگاه و حذف سفارش‌های تازه.
- دادن دسترسی بیش از نیاز مانند privilege سراسری برای حل موقت.
- حذف فایل‌های InnoDB یا دستکاری data directory.
چه زمانی بررسی چندلایه لازم است؟
اگر اتصال مقطعی است، MySQL crash می‌کند، replication یا Docker در مسیر است، یا فروشگاه داده زنده دارد، آزمایش روی production می‌تواند دامنه قطعی را بیشتر کند. در سرویس رفع مشکل فنی وردپرس می‌توان wp-config، شبکه، privilege، لاگ MySQL و منابع سیستم را بدون حدس کنار هم بررسی کرد. اگر پاسخ عمومی سرور 500 است، راهنمای خطای 500 وردپرس مسیر وب‌سرور و PHP را پوشش می‌دهد.
پرسش‌های متداول
آیا این خطا یعنی دیتابیس پاک شده است؟
خیر. پیام فقط شکست اتصال قابل استفاده را نشان می‌دهد. وجود و سلامت داده باید جداگانه و با ابزار دیتابیس بررسی شود.
چرا خطا خودبه‌خود برطرف می‌شود؟
ممکن است اتصال آزاد، سرویس restart یا فشار کم شده باشد. این الگو نیازمند بررسی timeline است و به معنی رفع علت نیست.
آیا localhost همیشه درست است؟
خیر. در نصب تک‌سرور رایج است، اما در Docker، دیتابیس remote یا socket سفارشی باید endpoint واقعی محیط استفاده شود.
آیا می‌توان رمز دیتابیس را عوض کرد؟
بله، اما باید همه مصرف‌کنندگان هماهنگ و secret به‌صورت امن به‌روزرسانی شود. تغییر عجولانه ممکن است سرویس‌های بیشتری را قطع کند.