# Sonderzeichen im Datenbank-Passwort

Warum @, :, / oder # im Passwort die DATABASE_URL zerbrechen und wie Sie das Passwort richtig kodieren – für Symfony, Laravel, Doctrine und Docker.

Website: https://skriptbox.com/de/anleitungen/sonderzeichen-im-datenbank-passwort

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:geheim@127.0.0.1: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](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.1) „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. PHPs `parse_url()` nimmt das letzte `@`, andere Parser das erste. Verlassen sollten Sie sich auf keines von beiden.
- `/`, `?` und `#` – beenden den Host-Teil vorzeitig. Bei `mysql://app:ab/cd@db/shop` liefert `parse_url()` nur noch `false`, Doctrine meldet dann `Malformed parameter "url"`.
- `:` – trennt Benutzername und Passwort und, nach dem Host, den Port.
- `%` – leitet eine Kodierung ein. Ein Passwort wie `50%Rabatt` wird 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](https://skriptbox.com/de/tools/url-encoder): 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](https://skriptbox.com/de/tools/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%231@127.0.0.1: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 `$NAME` und `${NAME}` durch Umgebungsvariablen. Aus `"mysql://app:S3cr3t$Key@…"` wird stillschweigend `mysql://app:S3cr3t@…`, weil es keine Variable `Key` gibt. Einfache Anführungszeichen übernehmen den Wert wörtlich. Eine vollständig kodierte URL enthält ohnehin kein `$` mehr, weil daraus `%24` wird.
- **Der Prozessor `resolve:`:** In vielen Projekten steht in `config/packages/doctrine.yaml` die Zeile `url: '%env(resolve:DATABASE_URL)%'`. `resolve:` ersetzt `%name%` durch Container-Parameter. In `p%40ss%3Aw…` sieht Symfony dann einen Parameter `40ss` und bricht mit „You have requested a non-existent parameter“ ab. Brauchen Sie `resolve:` nicht, entfernen Sie es. Andernfalls schreiben Sie jedes `%` in der `.env` doppelt, also `p%%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://app@127.0.0.1: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 mit `urlencode()`.
- In `.env`-Dateien einfache Anführungszeichen verwenden, damit `$` nicht interpoliert wird.
- In Symfony bei `%env(resolve:…)%` jedes `%` verdoppeln oder `resolve:` weglassen.
- In `compose.yaml` ein 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](https://skriptbox.com/de/tools/url-encoder.md) – Passwörter und Texte URL-kodieren (wie rawurlencode) und dekodieren, Verbindungs-URLs wie DATABASE_URL zusammensetzen – ohne Übertragung.
- [Passwort-Generator](https://skriptbox.com/de/tools/passwort-generator.md) – Sichere Passwörter und Passphrasen kostenlos erzeugen – direkt im Browser, ohne Übertragung.
