Viele Frameworks erwarten die Zugangsdaten zur Datenbank als eine einzige Zeichenkette, etwa in DATABASE_URL. Das ist praktisch, solange das Passwort nur aus Buchstaben und Ziffern besteht. Sobald ein @, :, / oder # darin vorkommt, liest der Parser die URL anders, als Sie es gemeint haben – und die Fehlermeldung verrät selten, dass das Passwort schuld ist.
Die Lösung ist einfach: Das Passwort wird URL-kodiert, bevor es in die Adresse kommt. Diese Anleitung zeigt, welche Zeichen betroffen sind, welche Kodierung die richtige ist und worauf Sie in Symfony, Laravel und Docker Compose zusätzlich achten müssen.
So ist eine Verbindungs-URL aufgebaut
Eine Verbindungs-URL folgt demselben Schema wie jede andere URL:
schema://benutzer:passwort@host:port/datenbank?parameter=wert
mysql://app:[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4
postgresql://app:geheim@db:5432/shop?serverVersion=16&charset=utf8
Der Teil vor dem @ heißt in der URL-Spezifikation RFC 3986 „userinfo“. Der Parser erkennt die einzelnen Bestandteile nur an ihren Trennzeichen: :// beendet das Schema, : trennt Benutzer und Passwort, @ trennt die Zugangsdaten vom Host, / leitet den Datenbanknamen ein, ? die Parameter und # ein Fragment. Steht eines dieser Zeichen im Passwort, verschiebt sich die Zerlegung.
Welche Zeichen Probleme machen
Nach RFC 3986 dürfen in der userinfo nur Buchstaben, Ziffern, - . _ ~, einige weitere Sonderzeichen und %-Folgen unkodiert stehen. Besonders kritisch sind:
@– trennt die Zugangsdaten vom Host. PHPsparse_url()nimmt das letzte@, andere Parser das erste. Verlassen sollten Sie sich auf keines von beiden./,?und#– beenden den Host-Teil vorzeitig. Beimysql://app:ab/cd@db/shopliefertparse_url()nur nochfalse, Doctrine meldet dannMalformed parameter "url".:– trennt Benutzername und Passwort und, nach dem Host, den Port.%– leitet eine Kodierung ein. Ein Passwort wie50%Rabattwird beim Dekodieren verfälscht oder als ungültig abgelehnt.- Leerzeichen, Anführungszeichen,
$und\– sind für die URL selbst nicht das Hauptproblem, wohl aber für die.env-Datei oder die Shell, in der die URL steht.
Typische Symptome sind „Access denied“, obwohl das Passwort stimmt, ein unbekannter Host, ein falscher Port oder eine Meldung, die URL sei fehlerhaft.
Richtig kodieren: rawurlencode statt urlencode
Beim Kodieren wird jedes problematische Zeichen durch % und seinen Byte-Wert in Hexadezimal ersetzt, aus @ wird %40. Am sichersten ist es, alles außer Buchstaben, Ziffern und - . _ ~ zu kodieren. Genau das macht PHPs rawurlencode(). Den Benutzernamen kodieren Sie auf dieselbe Weise, falls er Sonderzeichen enthält.
| Passwort | rawurlencode (richtig) | urlencode |
|---|---|---|
p@ss:w/rd#1 | p%40ss%3Aw%2Frd%231 | p%40ss%3Aw%2Frd%231 |
my pass+word | my%20pass%2Bword | my+pass%2Bword |
50%Rabatt! | 50%25Rabatt%21 | 50%25Rabatt%21 |
S3cr3t$Key | S3cr3t%24Key | S3cr3t%24Key |
Grüße | Gr%C3%BC%C3%9Fe | Gr%C3%BC%C3%9Fe |
Der Unterschied liegt beim Leerzeichen: urlencode() stammt aus der Welt der Formulardaten und macht daraus ein +. Doctrine und Laravel dekodieren die Bestandteile der URL aber mit rawurldecode(), und das lässt ein + unverändert. Aus my+pass%2Bword wird dann my+pass+word – ein falsches Passwort.
Sie können die Kodierung auf der Kommandozeile prüfen. Die einfachen Anführungszeichen verhindern, dass die Shell $ oder # selbst auswertet:
php -r 'echo rawurlencode($argv[1]), "\n";' 'p@ss:w/rd#1'
p%40ss%3Aw%2Frd%231
Ohne Kommandozeile geht es mit dem URL-Encoder & Decoder: Der Modus „Kodieren“ arbeitet standardmäßig wie rawurlencode(), und im Reiter „Verbindungs-URL“ setzen Sie Benutzer, Passwort, Host, Port und Datenbank zu einer fertigen DATABASE_URL zusammen. Die Eingaben verlassen dabei Ihren Browser nicht. JavaScripts encodeURIComponent() lässt einige Zeichen wie ! oder * unkodiert, die in der userinfo zwar erlaubt sind, bei weiterer Verarbeitung aber stören können.
Noch einfacher: Passwörter ohne Stolperfallen
Wenn Sie das Passwort selbst festlegen, können Sie das Problem von vornherein vermeiden. Lange Passwörter aus Buchstaben und Ziffern sind genauso sicher wie kürzere mit Sonderzeichen: 32 zufällige Zeichen aus Groß- und Kleinbuchstaben und Ziffern ergeben rund 190 Bit. Der Passwort-Generator erzeugt solche Passwörter, wenn Sie die Sonderzeichen abschalten. So entfallen Kodierung, Anführungszeichen und verdoppelte Dollarzeichen – und die URL bleibt lesbar.
Gibt ein Hoster das Passwort vor, ist die Kodierung der verlässliche Weg.
Symfony und Doctrine
In Symfony steht die Adresse in der Regel in .env oder, für lokale Zugangsdaten, in .env.local. Doctrine zerlegt die URL und dekodiert jeden Bestandteil, Sie tragen also die kodierte Form ein:
DATABASE_URL='mysql://app:p%40ss%3Aw%2Frd%[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4'
Zwei Stellen verdienen Aufmerksamkeit:
- Anführungszeichen in der .env: Ohne Anführungszeichen und in doppelten Anführungszeichen ersetzt Symfony
$NAMEund${NAME}durch Umgebungsvariablen. Aus"mysql://app:S3cr3t$Key@…"wird stillschweigendmysql://app:S3cr3t@…, weil es keine VariableKeygibt. Einfache Anführungszeichen übernehmen den Wert wörtlich. Eine vollständig kodierte URL enthält ohnehin kein$mehr, weil daraus%24wird. - Der Prozessor
resolve:: In vielen Projekten steht inconfig/packages/doctrine.yamldie Zeileurl: '%env(resolve:DATABASE_URL)%'.resolve:ersetzt%name%durch Container-Parameter. Inp%40ss%3Aw…sieht Symfony dann einen Parameter40ssund bricht mit „You have requested a non-existent parameter“ ab. Brauchen Sieresolve:nicht, entfernen Sie es. Andernfalls schreiben Sie jedes%in der.envdoppelt, alsop%%40ss%%3Aw….
Alternativ lassen Sie das Passwort ganz aus der URL heraus und übergeben es getrennt. Doctrine ergänzt die Werte aus der URL um die übrigen Optionen, sodass keine Kodierung nötig ist:
# .env.local
DATABASE_URL='mysql://[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4'
DATABASE_PASSWORD='p@ss:w/rd#1'
# config/packages/doctrine.yaml
doctrine:
dbal:
url: '%env(resolve:DATABASE_URL)%'
password: '%env(DATABASE_PASSWORD)%'
Wichtig: Enthält die URL doch ein Passwort, hat dieses Vorrang vor password.
Laravel
Laravel kennt beide Wege. Üblich sind einzelne Variablen wie DB_HOST, DB_USERNAME und DB_PASSWORD. Dort wird nichts URL-kodiert, das Passwort steht im Klartext:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=shop
DB_USERNAME=app
DB_PASSWORD='p@ss:w/rd#1'
Setzen Sie das Passwort in einfache Anführungszeichen, sobald es Leerzeichen, #, $ oder Anführungszeichen enthält. In doppelten Anführungszeichen ersetzt die .env-Bibliothek von Laravel Ausdrücke wie ${NAME}.
Daneben gibt es die Variable DB_URL (in älteren Versionen DATABASE_URL). Ist sie gesetzt, zerlegt Laravel sie, dekodiert die %-Folgen und lässt ihre Bestandteile Vorrang vor den einzelnen Variablen haben. Für sie gelten dieselben Regeln wie oben: Passwort mit rawurlencode() kodieren. Nach einer Änderung an der .env löschen Sie einen eventuell vorhandenen Konfigurations-Cache mit php artisan config:clear, sonst arbeitet die Anwendung weiter mit den alten Werten.
Docker und Docker Compose
Docker Compose wertet in compose.yaml selbst $ aus, um Variablen einzusetzen. Ein wörtliches Dollarzeichen schreiben Sie dort als $$. Das betrifft vor allem Passwörter, die unkodiert übergeben werden, etwa an das Datenbank-Image:
services:
db:
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: "S3cr3t$$Key"
POSTGRES_DB: shop
app:
environment:
DATABASE_URL: "postgresql://app:S3cr3t%24Key@db:5432/shop?serverVersion=16&charset=utf8"
Der Datenbank-Container erhält das Passwort im Klartext (S3cr3t$Key), die Anwendung dieselbe Zeichenfolge in kodierter Form. Beide müssen zum selben Passwort führen. Halten Sie die Werte in einer .env-Datei neben der compose.yaml, werden Werte in einfachen Anführungszeichen dort nicht interpoliert. Beachten Sie außerdem: Die Datenbank-Images übernehmen POSTGRES_PASSWORD und Co. nur beim ersten Start mit leerem Datenverzeichnis. Ein später geändertes Passwort ändern Sie in der Datenbank selbst.
Kurz zusammengefasst
- Passwort (und gegebenenfalls Benutzernamen) mit
rawurlencode()kodieren, nicht miturlencode(). - In
.env-Dateien einfache Anführungszeichen verwenden, damit$nicht interpoliert wird. - In Symfony bei
%env(resolve:…)%jedes%verdoppeln oderresolve:weglassen. - In
compose.yamlein wörtliches$als$$schreiben. - Wo möglich: Passwort als eigene Variable statt in der URL – oder gleich ein langes Passwort ohne Sonderzeichen.
Tools zum Thema
- URL-Encoder & Decoder Passwörter und Texte URL-kodieren (wie rawurlencode) und dekodieren, Verbindungs-URLs wie DATABASE_URL zusammensetzen – ohne Übertragung.
- Passwort-Generator Sichere Passwörter und Passphrasen kostenlos erzeugen – direkt im Browser, ohne Übertragung.
Weitere Anleitungen
- Weiterleitungen beim Website-Relaunch So planen Sie 301-Weiterleitungen für einen Relaunch: alte Adressen sammeln, Ziele zuordnen, Ketten vermeiden und das Ergebnis prüfen.
- Welche Favicons braucht eine Website? Welche Favicon-Dateien und Größen eine Website heute wirklich braucht – favicon.ico, SVG, Apple-Touch-Icon und Web-Manifest – samt HTML-Code.
- Verzeichnis mit Passwort schützen (.htpasswd) Ein Verzeichnis oder eine Staging-Seite mit .htaccess und .htpasswd schützen – für Apache und nginx, mit sicheren Hash-Verfahren.
- Bilder fürs Web optimieren Bilder richtig verkleinern und komprimieren: passende Größen, WebP, AVIF oder JPEG, Qualität, responsive Bilder und Lazy Loading.
- Barrierefreie Farben: Kontrast nach WCAG Was das Kontrastverhältnis nach WCAG bedeutet, welche Werte für Text und Bedienelemente gelten und wie Sie zu schwache Farben korrigieren.
- UUID v4, v7 oder ULID als Primärschlüssel? Wann sich UUIDs als Primärschlüssel lohnen, warum v7 und ULID für Datenbanken besser sind als v4 und wie Sie sie speichern.
- JWT sicher verwenden Typische Sicherheitsfehler mit JSON Web Tokens und wie Sie sie vermeiden: alg none, schwache Schlüssel, fehlende Prüfungen und Speicherort.