Error establishing a database connection w WordPressie | TopHostings.pl

Komunikat „Error establishing a database connection” oznacza, że WordPress nie może w danym momencie korzystać z bazy danych potrzebnej do wygenerowania strony. Przyczyną mogą być błędne dane połączenia, niedostępny MySQL lub MariaDB, problem po migracji albo przeciążenie warstwy bazodanowej.

Nie należy zaczynać od przypadkowej edycji bazy. Najpierw trzeba ustalić, czy problem dotyczy konfiguracji WordPressa, samego serwera bazodanowego, konkretnej bazy czy tylko wybranych operacji.

Ten komunikat nie mówi, że baza została uszkodzona. Mówi jedynie, że WordPress nie zdołał uzyskać potrzebnego połączenia z bazą danych.

Co właściwie nie działa, gdy WordPress pokazuje błąd połączenia z bazą?

WordPress przechowuje w bazie między innymi treści, ustawienia, użytkowników i konfigurację wtyczek. Żeby wygenerować typową stronę, PHP musi połączyć się z MySQL lub MariaDB przy użyciu danych z wp-config.php.

Najważniejsze są cztery wartości:

DB_NAME — nazwa bazy,
DB_USER — użytkownik bazy,
DB_PASSWORD — hasło,
DB_HOST — host serwera bazy.

Jeżeli którykolwiek z tych elementów jest nieprawidłowy albo serwer bazy nie odpowiada, WordPress może zatrzymać się jeszcze przed wygenerowaniem właściwej strony.

Objaw	Co sprawdzić najpierw
Błąd pojawił się zaraz po migracji	`wp-config.php`, nazwa bazy, użytkownik, host DB
Cała strona przestała działać bez zmian w plikach	Dostępność MySQL/MariaDB, logi, limity i awaria hostingu
Problem występuje okresowo	Limity połączeń, przeciążenie i warunki prowadzące do wyczerpania dostępnych połączeń
Inne narzędzie używające tego samego hosta i danych dostępowych również nie może się połączyć	Serwer DB, konto bazy, uprawnienia lub infrastruktura hostingu

Po migracji zacznij od wp-config.php

Po przeniesieniu WordPressa na inny hosting bardzo częstym źródłem problemu są stare dane połączenia. Nowy operator może używać innej nazwy bazy, użytkownika albo hosta MySQL.

Nie zakładaj, że DB_HOST zawsze ma wartość localhost. WordPress dopuszcza również hostname, adres IP, numer portu albo socket, zależnie od konfiguracji środowiska.

Porównaj dane zapisane w wp-config.php z wartościami podanymi w panelu nowego hostingu. Nie wpisuj ich na podstawie pamięci ani starego konta.

Jeśli plik był kopiowany między serwerami, sprawdź też, czy nie pozostały w nim dane poprzedniej instalacji albo literówka powstała podczas ręcznej edycji.

Oddziel błędne dane logowania od niedostępnego serwera MySQL

Dwa problemy mogą wyglądać podobnie w przeglądarce, ale wymagają innej naprawy.

Dane połączenia są nieprawidłowe

Jeżeli serwer MySQL działa, ale WordPress używa złej nazwy użytkownika, hasła, bazy albo hosta, połączenie zostanie odrzucone.

W takim przypadku trzeba zweryfikować istniejące dane i uprawnienia użytkownika bazy. Nie ma potrzeby resetowania wszystkich haseł na koncie hostingowym.

Serwer bazy nie odpowiada

Jeśli te same poprawne dane wcześniej działały, a problem pojawił się bez zmiany konfiguracji, trzeba sprawdzić dostępność samego MySQL/MariaDB.

Pomocny jest panel hostingu, status usług oraz logi. Jeżeli również inne aplikacje korzystające z tego samego serwera bazodanowego zaczynają mieć problemy, trop infrastrukturalny staje się znacznie mocniejszy.

Okresowy błąd połączenia często wymaga sprawdzenia obciążenia

Jeżeli strona raz działa, a chwilę później pokazuje błąd bazy, sama zawartość wp-config.php jest mniej prawdopodobnym źródłem problemu. Błędne hasło zwykle nie staje się okresowo poprawne.

Przy problemie okresowym warto sprawdzić przede wszystkim, czy nowe połączenia nie są odrzucane z powodu limitu globalnego albo limitu przypisanego użytkownikowi MySQL, na przykład max_connections lub MAX_USER_CONNECTIONS/max_user_connections. Jeżeli problemowi towarzyszy nietypowy wzrost danych, sprawdź także co powiększa bazę WordPressa.

Długie zapytania, blokady, duża liczba równoległych żądań oraz przeciążenie CPU lub pamięci nie muszą same wprost generować komunikatu o braku połączenia. Mogą jednak wydłużać czas utrzymywania połączeń, zwiększać kolejki i pośrednio doprowadzić do wyczerpania dostępnej puli.

Sam komunikat WordPressa nie pozwala określić, który z tych czynników wystąpił. Potrzebne są dane z czasu awarii.

Jeżeli hosting udostępnia informacje o wykorzystaniu zasobów, można zestawić je z diagnostyką zasobów hostingu. Limity i zachowanie warstwy MySQL opisuje też poradnik o limitach MySQL na hostingu.

Czy baza jest uszkodzona?

Komunikat o braku połączenia nie jest dowodem uszkodzenia tabel. Przy typowym problemie z loginem, hostem albo niedostępnym serwerem naprawa tabel niczego nie zmieni.

WordPress posiada mechanizm naprawy bazy uruchamiany przez ustawienie WP_ALLOW_REPAIR, ale należy używać go dopiero wtedy, gdy istnieją przesłanki wskazujące na problem ze strukturą tabel.

define( 'WP_ALLOW_REPAIR', true );

Po włączeniu mechanizmu WordPress udostępnia specjalną stronę naprawy bazy. Trzeba pamiętać, że ta funkcja nie wymaga zalogowania użytkownika, dlatego po zakończeniu operacji wpis WP_ALLOW_REPAIR powinien zostać usunięty z konfiguracji.

WP_ALLOW_REPAIR nie naprawi błędnego hasła, niewłaściwego DB_HOST, braku uprawnień użytkownika ani niedostępnego serwera MySQL — do działania mechanizmu naprawy WordPress nadal musi móc komunikować się z bazą.

Nie jest to więc uniwersalny pierwszy krok dla każdego „Error establishing a database connection”.

Logi pomagają ustalić, czy problem jest w WordPressie, PHP czy MySQL

Przy diagnozie sprawdź czas wystąpienia błędu i porównaj go z logami serwera oraz aplikacji.

W zależności od hostingu możesz znaleźć komunikaty wskazujące między innymi na:

odmowę uwierzytelnienia użytkownika bazy,
brak możliwości połączenia z hostem lub socketem,
przekroczenie liczby połączeń,
timeout,
problem z usługą MySQL/MariaDB.

Jeżeli potrzebujesz pomocy przy interpretacji komunikatów PHP i WordPressa, zobacz poradnik o error_log i debug.log.

Brak przydatnego wpisu w debug.log nie wyklucza problemu z bazą. Awaria może wystąpić na etapie, na którym WordPress nie jest jeszcze w stanie poprawnie uruchomić swojej warstwy diagnostycznej.

Bezpieczna procedura diagnozy

Ustal moment wystąpienia problemu. Czy był związany z migracją, zmianą hasła lub wdrożeniem?
Sprawdź zakres. Czy błąd występuje stale czy okresowo?
Zweryfikuj DB_NAME, DB_USER, DB_PASSWORD i DB_HOST.
Sprawdź, czy baza i użytkownik nadal istnieją.
Potwierdź, że użytkownik ma dostęp do właściwej bazy.
Jeżeli dane są poprawne, sprawdź dostępność MySQL/MariaDB.
Przy problemie okresowym sprawdź limity połączeń, obciążenie i logi z czasu awarii.
Nie uruchamiaj naprawy tabel bez przesłanek wskazujących na ich uszkodzenie.
Zmieniaj jedną rzecz naraz i po każdej zmianie wykonuj ten sam test.

Przy zgłoszeniu do supportu warto podać dokładny czas wystąpienia problemu, nazwę hosta bazy oraz komunikat błędu z logu. Hasła do bazy nie należy przesyłać w zwykłej treści zgłoszenia.

Najważniejsze wnioski

„Error establishing a database connection” oznacza brak użytecznego połączenia WordPressa z bazą, a nie automatycznie uszkodzenie danych;
po migracji pierwszym miejscem do sprawdzenia jest konfiguracja wp-config.php;
DB_HOST nie zawsze musi być równy localhost;
stały błąd po zmianie konfiguracji i okresowa awaria bez zmian wskazują na różne kierunki diagnozy;
przy problemach okresowych bezpośrednią przyczyną może być wyczerpanie limitu połączeń, a przeciążenie i długie zapytania mogą zwiększać ryzyko jego osiągnięcia;
mechanizm WP_ALLOW_REPAIR służy do naprawy tabel, nie do rozwiązywania błędnych credentials, hosta ani niedostępnego serwera;
po użyciu WP_ALLOW_REPAIR należy usunąć tę opcję z konfiguracji;
log serwera lub bazy może być bardziej użyteczny niż sam komunikat pokazany przez WordPressa.

Źródła

WordPress Developer Resources — Editing wp-config.php — konfiguracja DB_NAME, DB_USER, DB_PASSWORD i DB_HOST.
WordPress Developer Resources — Common WordPress errors — błąd połączenia z bazą i podstawowe kierunki diagnozy.
WordPress Developer Resources — wpdb — warstwa dostępu WordPressa do bazy danych.
WordPress Developer Resources — Automatic Database Optimizing — WP_ALLOW_REPAIR i strona naprawy bazy.
MySQL 8.4 Reference Manual — Too many connections — globalne i per-user limity połączeń.
MySQL 8.4 Reference Manual — Can't connect to MySQL server — diagnostyka niedostępnego hosta, portu i socketu.