وقتی وردپرس (WordPress) پیام «Error establishing a database connection» را نمایش می‌دهد، ریشه مشکل تقریباً همیشه در فایل wp-config.php یا پیکربندی پایگاه داده MySQL است. این خطا یکی از شایع‌ترین و در عین حال گیج‌کننده‌ترین خطاهای وردپرس است، زیرا سایت کاملاً از دسترس خارج می‌شود و هیچ سرنخی در پیشخوان نمایش داده نمی‌شود. بسیاری از مدیران سایت تصور می‌کنند سرور از کار افتاده یا دیتابیس حذف شده، در حالی که در اکثر موارد یک اشتباه کوچک در نام دیتابیس، نام کاربری، رمز عبور، نام هاست یا پیشوند جداول کافی است تا اتصال قطع شود. فایل wp-config.php حاوی چهار ثابت کلیدی است که وردپرس برای اتصال به پایگاه داده استفاده می‌کند و هر اشتباهی در آن‌ها به قطع کامل ارتباط منجر می‌شود. در این نوشتار، مکانیزم اتصال وردپرس به MySQL، دلایل شکست، روش‌های تشخیص از طریق لاگ و WP-CLI، اشتباهات رایج در wp-config و راهکارهای رفع قطعی بررسی می‌شود. هدف این است که خواننده پس از مطالعه بتواند بدون نیاز به پشتیبانی هاست، خطای اتصال به دیتابیس را در چند دقیقه ریشه‌یابی و رفع کند.

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

خطای اتصال به پایگاه داده دقیقاً چیست؟

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

در سطح فنی، این خطا زمانی رخ می‌دهد که کلاس wpdb — که مسئول ارتباط وردپرس با MySQL است — نمی‌تواند اتصال برقرار کند. تابع db_connect() در این کلاس، از تابع mysqli_real_connect() یا mysql_connect() (نسخه قدیمی) استفاده می‌کند. اگر این تابع مقدار false برگرداند، وردپرس اجرای خود را متوقف می‌کند و پیام خطا را نمایش می‌دهد.

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

  • دلایل ناشی از wp-config.php: اطلاعات احراز هویت اشتباه، هاست نادرست، پیشوند جداول نامناسب یا پیکربندی charset.
  • دلایل خارج از wp-config.php: خاموش بودن MySQL، نداشتن دسترسی کاربر، پر شدن اتصالات، خرابی دیتابیس یا مسائل شبکه.

در بیش از ۷۰ درصد مواردی که به‌عنوان تجربه عملی دیده شده، ریشه در فایل wp-config.php بوده است. به همین دلیل، این فایل نقطه شروع منطقی برای عیب‌یابی است.

خطای اتصال به دیتابیس، یک پیام عمومی است. برای فهمیدن ریشه واقعی، باید خطای دقیق MySQL را استخراج کرد، نه فقط به پیام وردپرس اکتفا کرد.

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

وردپرس چگونه به MySQL وصل می‌شود؟

برای درک دقیق ریشه مشکل، باید جریان اتصال وردپرس به MySQL را در سطح کد بررسی کرد. این جریان از فایل wp-config.php شروع می‌شود و در کلاس wpdb به پایان می‌رسد.

چهار ثابت کلیدی در wp-config.php

فایل wp-config.php چهار ثابت اصلی برای اتصال به دیتابیس تعریف می‌کند:

define('DB_NAME', 'database_name_here');
define('DB_USER', 'username_here');
define('DB_PASSWORD', 'password_here');
define('DB_HOST', 'localhost');

هر یک از این ثابت‌ها نقش مشخصی دارند:

  • DB_NAME: نام دیتابیس MySQL که وردپرس در آن نصب شده است.
  • DB_USER: نام کاربری MySQL که به دیتابیس دسترسی دارد.
  • DB_PASSWORD: رمز عبور کاربر MySQL.
  • DB_HOST: آدرس سرور MySQL. معمولاً localhost، 127.0.0.1 یا یک آدرس IP/دامنه.

علاوه بر این چهار ثابت، دو ثابت اختیاری نیز وجود دارند:

define('DB_CHARSET', 'utf8mb4');
define('DB_COLLATE', '');

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

برای مطالعه بیشتر درباره امنیت این فایل، مقاله چگونه فایل wp-config را امن کنیم بدون شکستن سایت؟ را ببینید.

نقش کلاس wpdb

کلاس wpdb در فایل wp-includes/wp-db.php تعریف شده است و مسئولیت ارتباط با MySQL را بر عهده دارد. این کلاس در زمان بارگذاری وردپرس، یک نمونه سراسری به نام $wpdb می‌سازد:

global $wpdb;
$result = $wpdb->get_results("SELECT * FROM wp_posts LIMIT 5");

متد db_connect() در این کلاس، فرآیند اتصال را مدیریت می‌کند:

function db_connect($allow_bail = true) {
    $this->dbh = @mysqli_real_connect(
        $this->dbh,
        $this->dbhost,
        $this->dbuser,
        $this->dbpassword,
        null,
        $this->dbport,
        $this->dbssl ? $this->dbssl : null
    );
    
    if (!$this->dbh) {
        if ($allow_bail) {
            wp_load_translations_early();
            $this->bail(sprintf('...'));
        }
        return false;
    }
    
    return true;
}

نکته کلیدی در این کد، علامت @ پیش از mysqli_real_connect است که خطاهای PHP را سرکوب می‌کند. این یعنی خطای دقیق MySQL نمایش داده نمی‌شود، مگر اینکه WP_DEBUG فعال باشد.

جریان اتصال از DB_HOST تا dbh

جریان کامل اتصال از چند مرحله عبور می‌کند:

  1. خواندن ثابت‌ها: DB_NAME، DB_USER، DB_PASSWORD، DB_HOST از wp-config.php خوانده می‌شوند.
  2. تجزیه DB_HOST: اگر DB_HOST شامل : باشد (مانند localhost:3306)، پورت جدا می‌شود.
  3. اتصال به MySQL: تابع mysqli_real_connect() فراخوانی می‌شود.
  4. انتخاب دیتابیس: با mysqli_select_db() دیتابیس مشخص می‌شود.
  5. تنظیم Charset: با set_charset() کدگذاری تعیین می‌شود.
  6. ذخیره در dbh: اتصال در خاصیت dbh ذخیره می‌شود.

هر شکستی در این مراحل، به خطای «Error establishing a database connection» منجر می‌شود.

اشتباهات رایج در فایل wp-config.php

اشتباهات در فایل wp-config.php شایع‌ترین دلیل خطای اتصال هستند. در ادامه، هر یک با جزئیات فنی بررسی می‌شود.

نام دیتابیس اشتباه

نام دیتابیس (DB_NAME) حساس به حروف بزرگ و کوچک است. در MySQL، نام دیتابیس روی سیستم‌های Linux معمولاً case-sensitive است، در حالی که روی Windows و macOS معمولاً case-insensitive است. اگر سایت روی Linux اجرا می‌شود و نام دیتابیس با حرف بزرگ نوشته شده، اتصال قطع می‌شود.

// اشتباه: نام دیتابیس با حرف بزرگ
define('DB_NAME', 'MyDatabase');

// صحیح: نام دیتابیس مطابق با MySQL
define('DB_NAME', 'mydatabase');

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

نام کاربری نادرست

نام کاربری (DB_USER) نیز case-sensitive است. مشکل شایع دیگر، استفاده از نام کاربری اشتباه است:

// اشتباه: نام کاربری root به‌جای کاربر دیتابیس
define('DB_USER', 'root');

// صحیح: کاربر دیتابیس که در پنل هاست ساخته شده
define('DB_USER', 'user_wpuser');

در هاست‌های اشتراکی، کاربر root به‌طور پیش‌فرض در دسترس نیست. اگر با root تلاش شود، خطای «Access denied for user» دریافت می‌شود.

رمز عبور اشتباه یا حاوی کاراکتر خاص

رمز عبور (DB_PASSWORD) یکی از پرتکرارترین منابع خطاست. سه مسئله اصلی:

  • رمز اشتباه: تغییر رمز در پنل هاست بدون بروزرسانی در wp-config.
  • کاراکترهای خاص: رمزهایی که شامل کاراکترهایی مانند '، "، \ هستند، باید به‌درستی escape شوند.
  • فاصله‌های اضافی: کپی-پیست از پنل هاست ممکن است فاصله اضافه وارد کند.
// اشتباه: رمز حاوی کوتیشن بدون escape
define('DB_PASSWORD', 'pass'word');

// صحیح: escape کاراکتر خاص
define('DB_PASSWORD', 'pass\'word');

// یا استفاده از رشته دو-کوتیشن
define('DB_PASSWORD', "pass'word");

توصیه امنیتی: رمزهایی که شامل کاراکترهای خاص هستند، باید در رشته‌های تک-کوتیشن با escape صحیح نوشته شوند یا از رشته‌های دو-کوتیشن استفاده شود.

DB_HOST اشتباه یا localhost در مقابل 127.0.0.1

مقدار DB_HOST یکی از کمتر شناخته‌شده‌ترین منابع خطاست. تفاوت localhost و 127.0.0.1 ظریف اما حیاتی است:

  • localhost: MySQL را ملزم به استفاده از سوکت یونیکس (Unix Socket) می‌کند که روی همان سرور قرار دارد.
  • 127.0.0.1: اتصال از طریق TCP/IP روی پورت ۳۳۰۶.

اگر سرور MySQL روی پورت غیراستاندارد اجرا شود یا سوکت یونیکس در مسیر پیش‌فرض نباشد، localhost شکست می‌خورد اما 127.0.0.1 کار می‌کند:

// اگر localhost کار نکرد، امتحان کنید
define('DB_HOST', '127.0.0.1');

// یا با پورت مشخص
define('DB_HOST', '127.0.0.1:3307');

در معماری‌های Docker و Kubernetes، DB_HOST معمولاً به نام سرویس (Service Name) یا IP کانتینر اشاره می‌کند، نه localhost. این نکته در پروژه‌های مدرن حیاتی است.

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

پیشوند جداول و تغییر ناخواسته

پیشوند جداول ($table_prefix) به‌طور پیش‌فرض wp_ است. اگر این پیشوند به‌اشتباه تغییر کند یا در زمان مهاجرت هماهنگ نشود، وردپرس نمی‌تواند جداول را پیدا کند:

// پیش‌فرض
$table_prefix = 'wp_';

// اگر دیتابیس با پیشوند متفاوت ساخته شده
$table_prefix = 'wpnew_';

این خطا معمولاً با پیام «Error establishing a database connection» نمایش داده نمی‌شود، بلکه با خطای «Table doesn't exist» یا صفحه نصب وردپرس مواجه می‌شوید. اما در برخی موارد، اگر جداول یافت نشوند، وردپرس تصور می‌کند نصب نشده و ممکن است به خطای اتصال منجر شود.

Charset و Collation ناسازگار

ثابت‌های DB_CHARSET و DB_COLLATE معمولاً مشکل ایجاد نمی‌کنند، اما در موارد خاص:

// پیش‌فرض مدرن
define('DB_CHARSET', 'utf8mb4');
define('DB_COLLATE', 'utf8mb4_unicode_ci');

// اگر دیتابیس قدیمی با utf8 ساخته شده
define('DB_CHARSET', 'utf8');
define('DB_COLLATE', 'utf8_general_ci');

اگر charset یا collation با نسخه MySQL سازگار نباشد، ممکن است خطای اتصال رخ دهد. این مشکل در MySQL 8 به‌ویژه شایع است، زیرا collation پیش‌فرض تغییر کرده است.

پورت غیراستاندارد و سوکت یونیکس

اگر MySQL روی پورت غیراستاندارد (غیر از ۳۳۰۶) اجرا شود، باید در DB_HOST مشخص شود:

// با پورت غیراستاندارد
define('DB_HOST', 'localhost:3307');
define('DB_HOST', '127.0.0.1:3307');

// یا با سوکت یونیکس
define('DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock');

در Docker، پورت MySQL معمولاً به ۳۳۰۶ نگاشت می‌شود، اما اگر چند سرویس MySQL روی یک سرور اجرا شوند، ممکن است از پورت‌های متفاوتی استفاده شود.

دلایل خارج از wp-config

هرچند اکثر خطاهای اتصال ریشه در wp-config.php دارند، برخی دلایل خارج از این فایل هستند و باید بررسی شوند.

خاموش بودن سرویس MySQL

شایع‌ترین دلیل خارجی، خاموش بودن سرویس MySQL است. در سرورهای اختصاصی و VPS، ممکن است سرویس MySQL به‌دلیل مصرف بالای حافظه یا خطای پیکربندی متوقف شود:

# بررسی وضعیت MySQL
systemctl status mysql
systemctl status mariadb

# راه‌اندازی مجدد
systemctl restart mysql

در هاست‌های اشتراکی، معمولاً نمی‌توان سرویس MySQL را مدیریت کرد و باید با پشتیبانی هاست تماس گرفت.

نداشتن دسترسی کاربر به دیتابیس

کاربر MySQL باید دسترسی لازم به دیتابیس را داشته باشد. اگر این دسترسی وجود نداشته باشد، خطای «Access denied» رخ می‌دهد:

-- بررسی دسترسی‌های کاربر
SHOW GRANTS FOR 'user_wpuser'@'localhost';

-- اعطای دسترسی کامل
GRANT ALL PRIVILEGES ON user_wpdb.* TO 'user_wpuser'@'localhost';
FLUSH PRIVILEGES;

در هاست‌های اشتراکی، این کار از پنل cPanel یا DirectAdmin انجام می‌شود. در VPS، باید از طریق MySQL CLI یا phpMyAdmin انجام شود.

خطای Too many connections

اگر تعداد اتصالات همزمان به MySQL از حد مجاز فراتر رود، خطای «Too many connections» رخ می‌دهد. این مشکل در سایت‌های پرترافیک یا هنگام حملات DDoS شایع است:

-- بررسی حداکثر اتصالات
SHOW VARIABLES LIKE 'max_connections';

-- بررسی اتصالات فعال
SHOW PROCESSLIST;

راه‌حل، افزایش max_connections در my.cnf یا بهینه‌سازی استفاده از اتصالات در وردپرس است. برای مطالعه بیشتر، مقاله چرا خطای Too many connections در MySQL رخ می‌دهد؟ را ببینید.

خرابی جداول و خاموش شدن خودکار

اگر جداول MySQL خراب شوند، ممکن است سرویس MySQL به‌طور خودکار خاموش شود یا در حالت read-only قرار گیرد:

-- بررسی و تعمیر جداول
CHECK TABLE wp_posts;
REPAIR TABLE wp_posts;
OPTIMIZE TABLE wp_posts;

برای مطالعه بیشتر درباره بهینه‌سازی دیتابیس، مقاله Database Optimization و بهینه‌سازی دیتابیس وردپرس را ببینید.

ابزارهای تشخیص خطای اتصال

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

فعال‌سازی WP_DEBUG برای نمایش خطای دقیق

اولین گام، فعال‌سازی حالت دیباگ است تا خطای دقیق MySQL نمایش داده شود:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

پس از فعال‌سازی، خطای دقیق در wp-content/debug.log ثبت می‌شود. نمونه‌ای از خطای دقیق:

WordPress database error Access denied for user 'user_wpuser'@'localhost' (using password: YES) for query SELECT * FROM wp_options

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

استفاده از WP-CLI برای بررسی اتصال

WP-CLI ابزار قدرتمندی برای بررسی وضعیت دیتابیس است:

# بررسی اتصال
wp db check

# تست کوئری
wp db query "SELECT 1"

# بررسی اطلاعات دیتابیس
wp db size
wp db tables

# بررسی وضعیت هسته
wp core version

این دستورات، تصویر دقیقی از وضعیت دیتابیس ارائه می‌دهند. برای مطالعه بیشتر، مقاله WP-CLI و مدیریت وردپرس از خط فرمان را ببینید.

اتصال مستقیم با MySQL CLI

برای تست مستقیم اتصال، از MySQL CLI استفاده کنید:

mysql -h localhost -u user_wpuser -p user_wpdb

# یا با پورت مشخص
mysql -h 127.0.0.1 -P 3307 -u user_wpuser -p user_wpdb

# بررسی جداول
SHOW TABLES;

# خروج
exit

اگر این دستور با موفقیت اجرا شود، یعنی اطلاعات احراز هویت صحیح است و مشکل در وردپرس یا PHP است. اگر خطا بدهد، ریشه در wp-config.php یا پیکربندی MySQL است.

تحلیل لاگ سرور و MySQL

لاگ‌ها بهترین منبع برای تشخیص ریشه هستند:

# لاگ خطاهای MySQL
tail -100 /var/log/mysql/error.log

# لاگ خطاهای PHP
tail -100 /var/log/php/error.log

# لاگ Apache یا Nginx
tail -100 /var/log/nginx/error.log
tail -100 /var/log/apache2/error.log

الگوهای تکراری مانند «Access denied»، «Can't connect» یا «Too many connections» ریشه مشکل را آشکار می‌کنند.

راهکارهای رفع خطا در wp-config.php

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

تأیید اطلاعات از پنل هاست

اولین گام، تأیید اطلاعات دیتابیس از پنل هاست است:

  • ورود به cPanel یا DirectAdmin.
  • بخش MySQL Databases.
  • بررسی نام دیتابیس، نام کاربری و دسترسی کاربر.
  • در صورت نیاز، بازنشانی رمز عبور.

در هاست‌های اشتراکی، این اطلاعات معمولاً در ایمیل خوش‌آمدگویی یا پنل کاربری موجود است.

بازسازی فایل wp-config.php

اگر فایل wp-config.php خراب یا ناقص است، می‌توان آن را بازسازی کرد:

  1. فایل wp-config-sample.php را کپی کنید.
  2. مقادیر DB_NAME، DB_USER، DB_PASSWORD و DB_HOST را وارد کنید.
  3. کلیدهای امنیتی را از https://api.wordpress.org/secret-key/1.1/salt/ دریافت و جایگزین کنید.
  4. پیشوند جداول را تنظیم کنید.
  5. فایل را با نام wp-config.php ذخیره کنید.
define('DB_NAME', 'user_wpdb');
define('DB_USER', 'user_wpuser');
define('DB_PASSWORD', 'your_password');
define('DB_HOST', 'localhost');
define('DB_CHARSET', 'utf8mb4');
define('DB_COLLATE', '');
$table_prefix = 'wp_';

بازنشانی رمز عبور دیتابیس

اگر رمز عبور فراموش شده یا اشتباه است، باید بازنشانی شود:

-- از MySQL CLI
ALTER USER 'user_wpuser'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;

سپس رمز جدید در wp-config.php بروزرسانی شود. توجه: در MySQL 8، دستور SET PASSWORD منسوخ شده و باید از ALTER USER استفاده کرد.

تغییر DB_HOST به 127.0.0.1

اگر localhost کار نمی‌کند، 127.0.0.1 را امتحان کنید:

define('DB_HOST', '127.0.0.1');

این تغییر در بسیاری از موارد مشکل را حل می‌کند، به‌ویژه در سرورهایی که سوکت یونیکس در مسیر غیراستاندارد قرار دارد.

اصلاح دسترسی‌های کاربر دیتابیس

اگر کاربر دسترسی کافی ندارد، باید دسترسی‌ها اصلاح شوند:

-- اعطای دسترسی کامل به دیتابیس مشخص
GRANT ALL PRIVILEGES ON user_wpdb.* TO 'user_wpuser'@'localhost';
FLUSH PRIVILEGES;

-- بررسی دسترسی‌ها
SHOW GRANTS FOR 'user_wpuser'@'localhost';

در هاست‌های اشتراکی، این کار از پنل هاست انجام می‌شود. در VPS، از MySQL CLI یا phpMyAdmin.

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

اگر دیتابیس حذف یا خراب شده باشد، باید از نسخه پشتیبان بازیابی شود:

# بازیابی از فایل SQL
mysql -u user_wpuser -p user_wpdb < backup.sql

# یا با WP-CLI
wp db import backup.sql

برای مطالعه بیشتر درباره پشتیبان‌گیری، مقاله چگونه از دیتابیس وردپرس بکاپ بگیریم؟ را ببینید.

پیشگیری از قطع اتصال دیتابیس

پیشگیری همیشه بهتر از درمان است. چند اصل کلیدی:

  • پشتیبان خودکار: از دیتابیس به‌طور روزانه نسخه پشتیبان تهیه شود.
  • مانیتورینگ: وضعیت MySQL به‌طور مستمر پایش شود.
  • افزایش محدودیت‌ها: max_connections و wait_timeout در سطح مناسب تنظیم شوند.
  • بهینه‌سازی دیتابیس: جداول دوره‌ای بهینه شوند.
  • مستندسازی: اطلاعات دیتابیس در مکانی امن ثبت شوند.
  • مراقبت از wp-config: فایل wp-config.php هرگز بدون پشتیبان ویرایش نشود.
  • استفاده از environment variables: در پروژه‌های حرفه‌ای، اطلاعات دیتابیس از متغیرهای محیطی خوانده شوند.

برای مطالعه بیشتر درباره مدیریت دیتابیس، مقاله آموزش مدیریت دیتابیس وردپرس را ببینید.

نکات امنیتی درباره فایل wp-config.php

فایل wp-config.php حاوی اطلاعات حساس است و باید محافظت شود:

# در .htaccess
<files wp-config.php>
    order allow,deny
    deny from all
</files>

# در Nginx
location ~* wp-config.php {
    deny all;
}

همچنین، مجوز فایل باید محدود باشد:

chmod 600 wp-config.php
chown www-data:www-data wp-config.php

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

wp-config.php یک فایل پیکربندی معمولی نیست، یک گنجینه اطلاعات حساس است. اگر به دست افراد نادرست بیفتد، کل سایت در خطر است.

پرسش‌های پرتکرار درباره خطای اتصال به دیتابیس

در این بخش، به پرسش‌های متداول پاسخ داده می‌شود. این ساختار برای بهینه‌سازی محتوا برای موتورهای پاسخگو (Answer Engines) نیز مفید است.

چرا وردپرس به پایگاه داده وصل نمی‌شود؟

دلایل اصلی: اطلاعات احراز هویت اشتباه در wp-config.php، خاموش بودن سرویس MySQL، نداشتن دسترسی کاربر دیتابیس، خرابی جداول یا پر شدن اتصالات. برای تشخیص دقیق، WP_DEBUG را فعال کنید.

چگونه خطای اتصال به دیتابیس را رفع کنم؟

ابتدا اطلاعات دیتابیس را از پنل هاست تأیید کنید. سپس wp-config.php را بررسی کنید. در صورت نیاز، رمز عبور را بازنشانی کنید. اگر مشکل باقی ماند، از MySQL CLI برای تست مستقیم اتصال استفاده کنید.

تفاوت localhost و 127.0.0.1 در DB_HOST چیست؟

localhost از سوکت یونیکس استفاده می‌کند و 127.0.0.1 از TCP/IP. اگر سوکت یونیکس در مسیر غیراستاندارد باشد یا MySQL روی پورت غیرپیش‌فرض اجرا شود، localhost شکست می‌خورد اما 127.0.0.1 کار می‌کند.

چگونه بفهمم مشکل از wp-config است یا از MySQL؟

با MySQL CLI تست کنید: mysql -h localhost -u user -p dbname. اگر اتصال موفق بود، مشکل در وردپرس یا PHP است. اگر خطا داد، ریشه در wp-config.php یا MySQL است.

آیا تغییر پیشوند جداول می‌تواند باعث خطای اتصال شود؟

خیر، پیشوند اشتباه باعث خطای «Table doesn't exist» می‌شود، نه خطای اتصال. اما اگر وردپرس جداول را پیدا نکند، ممکن است صفحه نصب نمایش داده شود.

چرا بعد از مهاجرت سرور، خطای اتصال رخ می‌دهد؟

در مهاجرت، اطلاعات دیتابیس تغییر می‌کند. اگر wp-config.php به‌روزرسانی نشود یا دیتابیس جدید ایجاد نشود، خطای اتصال رخ می‌دهد. برای مطالعه بیشتر، مقاله چگونه سایت وردپرسی را به هاست جدید منتقل کنیم؟ را ببینید.

آیا استفاده از رمز عبور ساده می‌تواند باعث خطای اتصال شود؟

خیر، رمز ساده خطای اتصال ایجاد نمی‌کند، اما امنیت را به خطر می‌اندازد. با این حال، رمزهایی با کاراکترهای خاص ممکن است در صورت escape نادرست، خطا ایجاد کنند.

چگونه از فایل wp-config.php نسخه پشتیبان بگیرم؟

با cp wp-config.php wp-config.php.backup یا دانلود از طریق FTP/SFTP. قبل از هر ویرایش، نسخه پشتیبان اجباری است.

آیا افزونه‌ها می‌توانند باعث خطای اتصال شوند؟

به‌طور غیرمستقیم بله. افزونه‌ای که کوئری‌های سنگین اجرا می‌کند یا اتصالات را باز نگه می‌دارد، می‌تواند به خطای «Too many connections» منجر شود.

چگونه max_connections را افزایش دهم؟

در my.cnf یا my.ini، مقدار max_connections را افزایش دهید. سپس MySQL را restart کنید. در هاست‌های اشتراکی، این تنظیم معمولاً قابل تغییر نیست و باید با پشتیبانی تماس گرفت.

آیا می‌توان از دیتابیس خارجی برای وردپرس استفاده کرد؟

بله، با تنظیم DB_HOST به آدرس سرور خارجی. اما این رویکرد نیازمند پیکربندی صحیح فایروال و دسترسی از راه دور است و معمولاً تأخیر بیشتری دارد.

چگونه از بروز این خطا در آینده جلوگیری کنم؟

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

نکات پیشرفته برای مهندسان ارشد

برای مهندسان ارشد و تیم‌های DevOps، خطای اتصال به دیتابیس یک مسئله چندلایه است. در این بخش، به نکات پیشرفته‌ای می‌پردازیم که در پروژه‌های بزرگ حیاتی می‌شوند.

تحلیل عمیق wpdb و hook‌های مرتبط

کلاس wpdb چند هوک مفید برای عیب‌یابی ارائه می‌دهد:

// ثبت کوئری‌های کند
add_filter('query', function($query) {
    $start = microtime(true);
    add_filter('query', function($q) use ($start, $query) {
        $duration = microtime(true) - $start;
        if ($duration > 0.5) {
            error_log(sprintf('Slow query (%.2fs): %s', $duration, $query));
        }
        return $q;
    });
    return $query;
});

این کد، کوئری‌هایی که بیش از ۵۰۰ میلی‌ثانیه طول می‌کشند را ثبت می‌کند. برای مطالعه بیشتر، مقاله بهینه سازی کوئری های MySQL را ببینید.

پیکربندی wp-config برای محیط‌های مختلف

در پروژه‌های حرفه‌ای، wp-config.php باید محیط‌آگاه باشد:

// تعیین محیط
define('WP_ENVIRONMENT_TYPE', getenv('WP_ENVIRONMENT_TYPE') ?: 'production');

// خواندن اطلاعات دیتابیس از محیط
define('DB_NAME', getenv('DB_NAME'));
define('DB_USER', getenv('DB_USER'));
define('DB_PASSWORD', getenv('DB_PASSWORD'));
define('DB_HOST', getenv('DB_HOST') ?: 'localhost');

// تنظیمات محیط‌آگاه
if (WP_ENVIRONMENT_TYPE === 'development') {
    define('WP_DEBUG', true);
    define('WP_DEBUG_LOG', true);
    define('WP_DEBUG_DISPLAY', false);
} else {
    define('WP_DEBUG', false);
}

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

پایش خطاهای اتصال با APM

در محیط‌های تولیدی، خطاهای اتصال باید پایش شوند:

add_action('init', function() {
    global $wpdb;
    if (mysqli_connect_errno()) {
        error_log(sprintf(
            'DB connection failed: %s (errno: %d)',
            mysqli_connect_error(),
            mysqli_connect_errno()
        ));
        // ارسال به APM
        if (function_exists('\Sentry\captureMessage')) {
            \Sentry\captureMessage('DB connection failed: ' . mysqli_connect_error());
        }
    }
});

برای مطالعه بیشتر درباره Sentry، مقاله Sentry Performance برای وردپرس چطور کار می‌کند؟ را ببینید.

Fallback دیتابیس و High Availability

در فروشگاه‌های حیاتی، توصیه می‌شود معماری دیتابیس با High Availability طراحی شود:

  • Master-Slave Replication: یک سرور master برای نوشتن، چند slave برای خواندن.
  • Galera Cluster: خوشه‌بندی MySQL با همگام‌سازی خودکار.
  • ProxySQL: لایه پروکسی برای توزیع بار و failover خودکار.
  • RDS Multi-AZ: در سرویس‌های ابری مانند AWS RDS.

در صورت قطع اتصال به master، سیستم به slave سوئیچ می‌کند و سرویس قطع نمی‌شود.

رمزنگاری اطلاعات دیتابیس در wp-config

در پروژه‌های حساس، اطلاعات دیتابیس باید رمزنگاری شوند:

// رمزنگاری با Sodium
$key = sodium_hex2bin(getenv('ENCRYPTION_KEY'));
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$encrypted = sodium_crypto_secretbox(getenv('DB_PASSWORD'), $nonce, $key);

define('DB_PASSWORD', sodium_crypto_secretbox_open(
    $encrypted,
    $nonce,
    $key
));

این رویکرد، اطلاعات حساس را از دسترسی مستقیم محافظت می‌کند. اما پیچیدگی عملیاتی خود را دارد و در اکثر پروژه‌ها ضروری نیست.

Composer و مدیریت دیتابیس

در پروژه‌های مدرن، می‌توان از Composer برای مدیریت ابزارهای دیتابیس استفاده کرد:

composer require doctrine/dbal
composer require symfony/console
use Doctrine\DBAL\DriverManager;

$conn = DriverManager::getConnection([
    'dbname' => getenv('DB_NAME'),
    'user' => getenv('DB_USER'),
    'password' => getenv('DB_PASSWORD'),
    'host' => getenv('DB_HOST'),
    'driver' => 'pdo_mysql',
]);

$stmt = $conn->executeQuery('SELECT COUNT(*) FROM wp_posts');
echo $stmt->fetchOne();

این رویکرد، انعطاف‌پذیری بیشتری برای پروژه‌های پیچیده فراهم می‌کند.

Migration دیتابیس با WP-CLI

در پروژه‌های تیمی، مهاجرت دیتابیس باید قابل تکرار باشد:

#!/bin/bash
# /usr/local/bin/db-migration.sh
SOURCE_DB="old_database"
TARGET_DB="new_database"

# پشتیبان از مبدأ
mysqldump -u user -p $SOURCE_DB > /tmp/migration.sql

# ایجاد دیتابیس مقصد
mysql -u user -p -e "CREATE DATABASE IF NOT EXISTS $TARGET_DB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"

# وارد کردن داده‌ها
mysql -u user -p $TARGET_DB < /tmp/migration.sql

# بروزرسانی wp-config
wp config set DB_NAME $TARGET_DB

# تست اتصال
wp db check

این اسکریپت، فرآیند مهاجرت را قابل تکرار و قابل اتکا می‌کند.

نکات کلیدی برای پایداری بلندمدت

در پایان، چند نکته کلیدی که باید در خاطر بماند:

  • پشتیبان خودکار: قبل از هر تغییر در wp-config.
  • WP_DEBUG در محیط توسعه: برای دیدن خطای دقیق.
  • MySQL CLI: برای تست مستقیم اتصال.
  • متغیرهای محیطی: برای اطلاعات حساس دیتابیس.
  • مانیتورینگ مستمر: پایش max_connections و وضعیت MySQL.
  • مستندسازی: اطلاعات دیتابیس در مکان امن.
  • آزمون دوره‌ای بازیابی: تست بازیابی از نسخه پشتیبان.
  • High Availability: در پروژه‌های حیاتی، معماری دیتابیس با failover.
  • امنیت wp-config: محدودیت دسترسی و رمزنگاری.
  • آموزش تیم: همه اعضا با فرآیند عیب‌یابی آشنا باشند.

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