Datenbankverbindung fehlgeschlagen bei der Bildergalerie beheben

Gestern lief die Galerie noch, heute bleibt die Seite weiß, oder der Installer weigert sich weiterzumachen. Hinter beidem steckt dieselbe Diagnose: Datenbankverbindung fehlgeschlagen. Das Script hat sich beim Datenbank-Server angemeldet und wurde abgewiesen, oder es hat den Server gar nicht erst gefunden. Ihre Bilder sind dabei nicht in Gefahr. Sie liegen weiter als Dateien auf dem Webspace, und auch die Datenbank selbst bleibt unberührt. Es fehlt nur der Weg dorthin. Welches Stück dieses Weges unterbrochen ist, verrät fast immer die Meldung von MySQL, sofern Sie wissen, wo sie steht und wie man sie liest.

Datenbankverbindung fehlgeschlagen: Der Stecker der Galerie steckt nicht in der Buchse der Datenbank, davor liegen vier Schlüssel

Zuerst klären: Lief die Verbindung schon einmal?

Für die Anmeldung braucht die Galerie vier Angaben, die in der Datei inc/config.php stehen: den Servernamen $db_host, den Namen der Datenbank $db_datenbank, den Benutzer $db_user und das Passwort $db_passwort. Ist die Datenbankverbindung fehlgeschlagen, beantworten Sie vor dem Prüfen der einzelnen Werte eine Frage: Hat die Verbindung schon einmal funktioniert? Davon hängt ab, wo die Ursache am wahrscheinlichsten liegt.

Noch nie, Sie richten gerade ein: Dann ist einer der vier Werte falsch abgeschrieben, die Datenbank existiert noch nicht oder der Benutzer ist ihr nicht zugeordnet. Die Ursache liegt hier fast immer in der eigenen Eingabe, nicht beim Hoster.
Lief lange, ist plötzlich weg: Hat sich beim Hoster etwas geändert? Ein neu gesetztes Passwort, ein Tarifwechsel oder ein angekündigter Serverumzug sind die häufigsten Auslöser. Haben Sie selbst nichts geändert, kommt auch eine Störung beim Hoster in Frage.
Direkt nach einem Umzug oder Update: Prüfen Sie, ob inc/config.php mit übertragen wurde und ob sie noch die Werte des alten Servers enthält.

Die Meldung von MySQL lesen

MySQL sagt ziemlich genau, was ihm nicht passt, nur eben auf Englisch und zwischen technischen Angaben. Ein typischer Eintrag lautet Access denied for user 'web123_u1'@'localhost' (using password: YES). Darin stecken drei Auskünfte: der Benutzer, mit dem sich das Script anmelden wollte, der Rechner, von dem die Anfrage kam, und ob überhaupt ein Passwort mitgeschickt wurde. Steht dort using password: NO, war $db_passwort leer. Hinter jeder Meldung steckt außerdem eine Fehlernummer, etwa 1045 für eine abgelehnte Anmeldung. Das Diagramm zeigt den ganzen Weg: vom Verbindungsversuch über die Stelle, an der Sie den Fehler zu sehen bekommen, bis zu dem Wert, den Sie korrigieren.

Animiertes Ablaufdiagramm: inc/config.php meldet sich beim MySQL-Server an, Fehler 1045 erscheint im Installer oder im Fehlerprotokoll, die Fehlernummer führt zu $db_user und $db_passwort, danach steht die Verbindung — Die Fehlernummer zeigt auf den Wert in inc/config.php, nur bei 1040 (Too many connections) ist Abwarten richtig.

Achten Sie auch auf Tippfehler, die erst in der Meldung auffallen. Lautet sie Unknown database 'web123_galeri', fehlt in Ihrer Datei ein Buchstabe. In der Meldung sehen Sie ihn schneller, als wenn Sie die Werte im Kopf durchgehen.

Die vier Werte gegenprüfen

Statt die Werte nur mit dem Kundenmenü zu vergleichen, können Sie sie ausprobieren. Viele Hoster bieten phpMyAdmin mit eigener Anmeldemaske an. Melden Sie sich dort mit genau dem Benutzer und dem Passwort an, die in Ihrer Galerie stehen. Klappt das, sind diese beiden Werte richtig, und Sie suchen beim Host oder beim Datenbanknamen weiter.

Wert	Gegenprobe	Was ein Fehlschlag bedeutet
`$db_user`	mit der Datenbankübersicht im Kundenmenü vergleichen, samt Präfix wie `web123_`	Der Benutzer heißt anders oder wurde gelöscht.
`$db_passwort`	Anmeldung in phpMyAdmin mit genau diesem Benutzer und Passwort	Passwort im Kundenmenü neu setzen und in `inc/config.php` gleich eintragen
`$db_datenbank`	nach der Anmeldung in der linken Liste von phpMyAdmin suchen	Der Name weicht ab, oder der Benutzer hat keine Rechte an dieser Datenbank.
`$db_host`	Detailansicht der Datenbank im Kundenmenü	Dort steht ein eigener Servername, die Galerie nutzt aber `localhost`.

Ein Sonderfall sind Passwörter mit Zeichen wie ', \ oder $. Im Kundenmenü funktionieren sie, in einer von Hand bearbeiteten PHP-Datei können sie falsch ankommen: Zwischen einfachen Anführungszeichen brauchen ' und \ einen vorangestellten Backslash, und $ wird zum Problem, sobald jemand die Anführungszeichen auf doppelte umstellt. Wer das ausschließen will, vergibt testweise ein Passwort nur aus Buchstaben und Ziffern, dafür mit 20 Stellen.

Wenn alle Werte stimmen

Haben Sie jeden Wert gegengeprüft und ist die Datenbankverbindung trotzdem fehlgeschlagen, liegt die Ursache wahrscheinlich nicht bei Ihnen. Tritt der Fehler nur zeitweise auf, etwa abends oder alle paar Minuten für einen Moment, ist der Datenbank-Server überlastet oder wird gerade gewartet. Die Meldung Too many connections (Fehler 1040) bestätigt das: Der Server hat sein Limit gleichzeitiger Verbindungen erreicht. An der Konfiguration ändern Sie dann nichts, denn sie ist richtig.

Sehen Sie stattdessen nach, ob Ihr Hoster eine Statusseite mit gemeldeten Störungen hat, und notieren Sie Uhrzeit und genauen Wortlaut der Meldung. Mit diesen beiden Angaben kann der Support im Protokoll seines Servers nachsehen, was passiert ist. Häuft sich der Fehler über Tage, ist ein Tarif mit mehr Leistung oder ein anderer Anbieter die ehrlichere Lösung als jede Einstellung in der Galerie.

Wenn im Bildergalerie-Script die Datenbankverbindung fehlgeschlagen ist

Im Bildergalerie-Script sehen Sie den Fehler an zwei Stellen, und er sieht dort jeweils ganz anders aus. Während der Installation prüft der Installer die Angaben aus dem Abschnitt „Datenbank“ sofort und übersetzt die Antwort des Servers in einen deutschen Satz. Die Meldung steht oben unter „Die Installation wurde noch nicht ausgeführt.“ und zusätzlich am betroffenen Feld:

Meldung des Installers (gekürzt)	MySQL-Fehler	Was zu tun ist
„Der Datenbank-Server lehnt die Anmeldung ab.“	1045	Benutzer und Passwort aus dem Kundenmenü übernehmen
„Der Datenbank-Server „…“ ist nicht erreichbar.“	2002, 2003, 2005, 2006	statt `localhost` den Servernamen des Hosters eintragen
„Die Datenbank „…“ gibt es nicht, oder der Benutzer „…“ hat keinen Zugriff darauf.“	1044, 1049	Namen samt Präfix prüfen, Benutzer der Datenbank zuordnen
„Die Verbindung zur Datenbank ist fehlgeschlagen (Fehler …: …).“	alle anderen	Nummer und Text an den Hoster geben

Beide Passwortfelder müssen Sie nach einem Fehler neu ausfüllen, der Installer schreibt sie aus Sicherheitsgründen nicht zurück ins Formular. Leerzeichen am Rand des Passworts zählen mit, das Script schneidet sie nicht ab.

Läuft die Galerie schon, wenn die Datenbankverbindung fehlgeschlagen ist, gibt es keine freundliche Meldung. Unter PHP 8.2 und neuer, das die aktuelle Version voraussetzt, bricht die Seite ab: Besucher sehen meist eine weiße Seite oder „500 Internal Server Error“, die Verwaltung genauso. Den eigentlichen Grund finden Sie im Fehlerprotokoll (error log) im Kundenmenü Ihres Webhosters. Dort steht ein Eintrag mit Uncaught mysqli_sql_exception und dahinter der Text von MySQL, also genau die Meldungen von oben. Läuft eine ältere Galerie noch auf PHP 8.0 oder älter, zeigt sie stattdessen direkt die Zeile „DBD::mysqli Error: Could not connect to the database.“ mit demselben Text dahinter. Korrigiert werden die Werte in beiden Fällen in inc/config.php.

Praxisfall: Umzug zu einem neuen Hoster

Sie ziehen mit der Galerie zu einem anderen Webhoster um. Die Dateien sind kopiert, die Datenbank ist importiert, doch die Seite bleibt weiß, und im Fehlerprotokoll steht Access denied for user 'web123_u1'. Der Benutzername verrät es: Die Galerie meldet sich noch mit den Daten des alten Anbieters an. So bringen Sie sie an den neuen Ort:

Beim neuen Hoster eine Datenbank samt Benutzer anlegen und den Export vom alten Hoster dort in phpMyAdmin über „Importieren“ einspielen.
inc/config.php per FTP herunterladen. Im Browser lässt sie sich nicht öffnen, ein direkter Aufruf endet absichtlich mit Status 403.
Die vier Werte $db_host, $db_datenbank, $db_user und $db_passwort durch die neuen ersetzen. Beim Umzug ändert sich meist auch $root_dir, der absolute Pfad des Galerie-Ordners auf dem neuen Server.
Die Datei als UTF-8 ohne BOM speichern und zurück in den Ordner inc/ laden. Mit BOM landet ein unsichtbares Zeichen vor <?php, und PHP meldet „Cannot modify header information - headers already sent“.
Die Galerie aufrufen. Erscheinen die Kategorien, steht die Verbindung. Erscheint stattdessen nur die Zeile „Den Vorlagen-Ordner … gibt es nicht auf dem Server.“, stimmt $root_dir noch nicht. Beim Hochladen meldet die Verwaltung in diesem Fall, der Ordner „bilder“ sei nicht gefunden worden.

Leitet die Verwaltung dagegen zum Installer weiter, fehlt inc/config.php ganz, weil sie beim Kopieren vergessen wurde. Spielen Sie die Datei dann aus Ihrer Sicherung zurück. Eine neue Installation in die bestehende Datenbank lehnt der Installer ab, damit Ihre Galerie nicht überschrieben wird. Wer das Verhalten in Ruhe ausprobieren möchte, kann das Bildergalerie-Script kostenlos herunterladen und es in einem Testordner mit absichtlich falschem Passwort installieren.

Häufige Fragen

Bei einer abgewiesenen Verbindung tauchen immer wieder dieselben Fragen auf: woher die Werte kommen, was die MySQL-Meldung bedeutet und warum danach manchmal die Umlaute nicht stimmen.

Woher bekomme ich die richtigen Werte für die config.php?

Aus der Datenbankübersicht im Kundenmenü Ihres Hosters. Die Datei in der Galerie ist nur eine Abschrift dieser Angaben. Stimmen beide nicht mehr überein, gilt immer, was der Hoster anzeigt. Lediglich das Passwort lässt sich dort oft nicht mehr ablesen. Dann setzen Sie es neu und tragen den neuen Wert in die Datei ein.

Was bedeutet die Meldung Access denied for user oder Unknown database?

Access denied heißt: Der Server wurde gefunden, lässt die Galerie aber nicht herein, weil Benutzer und Passwort nicht zusammenpassen oder der Benutzer die genannte Datenbank nicht verwenden darf. Unknown database heißt: Die Anmeldung hat geklappt, aber eine Datenbank mit diesem Namen gibt es nicht. Meldungen mit getaddrinfo oder Connection refused bedeuten dagegen, dass unter dem angegebenen Host gar kein Server erreichbar war.

Warum werden nach dem Verbinden die Umlaute falsch dargestellt?

Dann steht die Verbindung, aber Script und Datenbank verwenden unterschiedliche Zeichensätze. Das ist ein eigenes Problem mit eigener Lösung. Das Bildergalerie-Script stellt die Verbindung seit Version 3.15 selbst auf utf8mb4 um, sodass „Thüringer Wald“ auch in älteren latin1-Tabellen richtig ankommt.

Warum sehe ich nur eine weiße Seite statt „Datenbankverbindung fehlgeschlagen“?

Die meisten Webhoster blenden PHP-Fehler für Besucher aus, damit keine Serverpfade oder Benutzernamen sichtbar werden. Der Fehler wird trotzdem festgehalten, und zwar im Fehlerprotokoll im Kundenmenü. Manche Hoster erlauben, die Fehleranzeige vorübergehend einzuschalten. Schalten Sie sie nach der Fehlersuche wieder aus.