Fix lỗi WordPress "Error establishing a database connection"

Chuyện gì đã xảy ra

Bạn mở trang WordPress và thấy chỉ một dòng thay vì trang chủ: Error establishing a database connection. Trang quản trị tại /wp-admin cũng hiển thị tương tự. WordPress không thể kết nối đến MySQL — nhưng nguyên nhân có thể là một trong sáu vấn đề khác nhau, từ gõ nhầm trong file cấu hình đến database engine bị crash.

Thực hiện lần lượt các bước dưới đây theo thứ tự. Hầu hết các site đều hoạt động trở lại sau Bước 2.

Bước 1 — Kiểm tra thông tin đăng nhập trong wp-config.php

Đây là nguyên nhân trong khoảng 70% trường hợp. Ai đó đã thay đổi mật khẩu database, chuyển site sang server mới, hoặc sao chép sang môi trường staging mà chưa cập nhật thông tin đăng nhập trong wp-config.php.

nano /var/www/html/wp-config.php

Tìm bốn dòng sau:

define( 'DB_NAME',     'your_database_name' );
define( 'DB_USER',     'your_db_user' );
define( 'DB_PASSWORD', 'your_db_password' );
define( 'DB_HOST',     'localhost' );

Đừng đoán mò — hãy kiểm tra thông tin đăng nhập trực tiếp từ shell:

mysql -u your_db_user -p -h localhost your_database_name

Nếu MySQL từ chối đăng nhập, thông tin đăng nhập đang sai. Hãy cập nhật wp-config.php cho khớp với thông tin trong MySQL, hoặc đặt lại mật khẩu user MySQL:

mysql -u root -p
ALTER USER 'your_db_user'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;

Sau đó đặt DB_PASSWORD trong wp-config.php thành mật khẩu mới đó.

Bước 2 — Xác nhận MySQL đang thực sự chạy

Thông tin đăng nhập đúng mà lỗi vẫn còn? MySQL có thể đang bị tắt.

# Ubuntu/Debian
systemctl status mysql

# CentOS/RHEL
systemctl status mysqld

Đã dừng? Khởi động lại:

systemctl start mysql
# hoặc với MariaDB
systemctl start mariadb

Nếu không chịu khởi động, hãy đọc log trước khi làm bất cứ điều gì khác:

journalctl -u mysql -n 50 --no-pager
# hoặc
tail -n 100 /var/log/mysql/error.log

Ba lỗi khởi động thường gặp nhất: đĩa đầy (MySQL cần dung lượng để ghi file tạm), cần phục hồi sau crash InnoDB (tìm dòng "InnoDB: Database was not shut down normally"), hoặc file ibdata1 bị hỏng. Log sẽ chỉ ra nguyên nhân — hãy sửa cái đó trước.

Bước 3 — Xác nhận database và user tồn tại

Sau khi đã đăng nhập vào MySQL, hãy xác minh cả database lẫn user thực sự đang tồn tại. Nghe có vẻ hiển nhiên, nhưng một lần migration thất bại hoặc lỡ tay DROP đều có thể xóa một trong hai.

mysql -u root -p

-- Kiểm tra database có tồn tại không
SHOW DATABASES LIKE 'your_database_name';

-- Kiểm tra user tồn tại với host đúng
SELECT user, host FROM mysql.user WHERE user = 'your_db_user';

-- Kiểm tra user có quyền trên database đó không
SHOW GRANTS FOR 'your_db_user'@'localhost';

User tồn tại nhưng không có quyền? Đó là vấn đề:

GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_db_user'@'localhost';
FLUSH PRIVILEGES;

Nếu bản thân database đã biến mất, hãy khôi phục từ bản backup — WordPress không thể tự tạo lại database từ đầu.

Bước 4 — Kiểm tra giá trị DB_HOST

Trong một số cấu hình, localhost không phân giải đúng. Điều này hay làm người dùng bất ngờ trên môi trường Docker, database cloud được quản lý (Amazon RDS, PlanetScale), và một số host cPanel nơi MySQL lắng nghe trên socket thay vì cổng TCP.

-- Tìm đường dẫn socket
SHOW VARIABLES LIKE 'socket';
-- Kết quả thường gặp: /var/run/mysqld/mysqld.sock

Thử thay đổi DB_HOST trong wp-config.php thành một trong các giá trị sau:

// Ép dùng TCP thay vì socket
define( 'DB_HOST', '127.0.0.1' );

// Đường dẫn socket rõ ràng
define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );

// Host từ xa (server DB riêng hoặc Docker container)
define( 'DB_HOST', '10.0.0.5' );

Bước 5 — Sửa chữa các bảng bị hỏng

Đây là tình huống khá lạ: WordPress kết nối đến MySQL bình thường, nhưng trang chủ vẫn hiển thị lỗi trong khi /wp-admin lại load được (hoặc hiển thị lỗi database khác). Nguyên nhân thường là các bảng WordPress bị hỏng.

Thêm tạm một dòng vào wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Sau đó mở URL này trên trình duyệt:

https://yoursite.com/wp-admin/maint/repair.php

Nhấn "Repair Database" và chờ. Khi xong, hãy xóa ngay dòng WP_ALLOW_REPAIR — nó cho phép bất kỳ ai kích hoạt repair mà không cần đăng nhập, đây là rủi ro bảo mật thực sự.

Thích dùng dòng lệnh hơn? Kết quả tương tự:

mysqlcheck -u root -p --repair your_database_name

Bước 6 — Kiểm tra max_connections và dung lượng đĩa

Các site lưu lượng cao hay gặp vấn đề này. MySQL có giới hạn cứng về số kết nối đồng thời (mặc định: 151). Khi đạt đến giới hạn đó, các kết nối mới sẽ thất bại và hiển thị cùng lỗi mà WordPress báo.

mysql -u root -p -e "SHOW STATUS LIKE 'Max_used_connections';"
mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"

Nếu Max_used_connections bằng max_connections, bạn đã chạm trần. Tăng ngay mà không cần restart:

mysql -u root -p -e "SET GLOBAL max_connections = 300;"

Để thiết lập này bền vững qua các lần reboot, hãy chỉnh /etc/mysql/mysql.conf.d/mysqld.cnf:

[mysqld]
max_connections = 300

Nhân tiện, hãy kiểm tra luôn dung lượng đĩa. MySQL âm thầm từ chối ghi khi phân vùng đầy, và WordPress sẽ hiểu đó là lỗi kết nối:

df -h

Bất kỳ phân vùng nào trên 90% đều đáng xem xét trước khi tiếp tục.

Xác minh

Sau khi áp dụng bất kỳ cách sửa nào, hãy xác nhận mọi thứ đang thực sự hoạt động:

Tải lại trang chủ — site phải hiển thị bình thường.
Mở /wp-admin và đăng nhập để xác nhận dashboard load được.
Chạy kiểm tra kết nối PHP nhanh:

<?php
$link = mysqli_connect('localhost', 'your_db_user', 'your_db_password', 'your_database_name');
if (!$link) {
    echo 'Connect failed: ' . mysqli_connect_error();
} else {
    echo 'Connected successfully';
    mysqli_close($link);
}

Lưu file này thành test-db.php trong thư mục web root, truy cập bằng trình duyệt, rồi xóa ngay. Đừng bao giờ để file kiểm tra kết nối thô trên server production.

Bài học rút ra

Đang chuyển site WordPress? Hãy cập nhật thông tin đăng nhập trong wp-config.php trước khi import database — không phải sau khi đã gặp lỗi rồi.
Lỗi này hoàn toàn âm thầm cho đến khi người dùng truy cập site. Một công cụ kiểm tra uptime cơ bản (UptimeRobot có gói miễn phí, hoặc một cron job ping trang chủ mỗi 5 phút) sẽ phát hiện trong vài giây thay vì vài giờ.
Backup MySQL tự động biến sự cố bảng bị hỏng thành việc khôi phục 10 phút. Không có backup, việc sửa thủ công có thể kéo dài hàng giờ.
Đang dùng shared hosting mà không có cách nào hiệu quả? Hãy liên hệ nhà cung cấp hosting. Họ thường xuyên giới hạn số kết nối database hoặc thay đổi thông tin đăng nhập mà không thông báo gì cho khách hàng.