# Special characters in database passwords

Why @, :, / or # in a password break your DATABASE_URL and how to encode the password correctly – for Symfony, Laravel, Doctrine and Docker.

Web page: https://skriptbox.com/en/guides/special-characters-in-database-passwords

Many frameworks expect your database credentials as a single string, typically in `DATABASE_URL`. That works fine as long as the password consists of letters and digits. As soon as it contains an `@`, `:`, `/` or `#`, the parser reads the URL differently from what you intended – and the error message rarely hints that the password is to blame.

The fix is simple: URL-encode the password before it goes into the address. This guide shows which characters cause trouble, which encoding is the right one, and what else to watch out for in Symfony, Laravel and Docker Compose.

## How a connection URL is structured

A connection URL follows the same pattern as any other URL:

```
scheme://user:password@host:port/database?param=value

mysql://app:secret@127.0.0.1:3306/shop?serverVersion=8.0&charset=utf8mb4
postgresql://app:secret@db:5432/shop?serverVersion=16&charset=utf8
```

The URL specification, [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.1), calls the part before the `@` the “userinfo”. A parser can only tell the components apart by their delimiters: `://` ends the scheme, `:` separates user and password, `@` separates the credentials from the host, `/` introduces the database name, `?` the parameters and `#` a fragment. If one of these characters appears in the password, the whole split shifts.

## Which characters cause problems

According to RFC 3986, the userinfo may only contain letters, digits, `-` `.` `_` `~`, a handful of other symbols and percent-encoded sequences. The critical ones are:

- `@` – separates the credentials from the host. PHP’s `parse_url()` uses the last `@`, other parsers use the first. You shouldn’t rely on either.
- `/`, `?` and `#` – end the host part early. For `mysql://app:ab/cd@db/shop`, `parse_url()` simply returns `false`, and Doctrine reports `Malformed parameter "url"`.
- `:` – separates user name and password and, after the host, the port.
- `%` – starts an encoded sequence. A password like `50%off` gets mangled when decoded or is rejected as invalid.
- Spaces, quotes, `$` and `\` – not the main problem for the URL itself, but for the `.env` file or shell the URL lives in.

Typical symptoms are “Access denied” even though the password is correct, an unknown host, a wrong port, or a message saying the URL is malformed.

## Encoding it right: rawurlencode, not urlencode

Encoding replaces each problematic character with `%` followed by its byte value in hexadecimal, so `@` becomes `%40`. The safest approach is to encode everything except letters, digits and `- . _ ~`. That is exactly what PHP’s `rawurlencode()` does. Encode the user name the same way if it contains special characters.

| Password | rawurlencode (correct) | 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%off!` | `50%25off%21` | `50%25off%21` |
| `S3cr3t$Key` | `S3cr3t%24Key` | `S3cr3t%24Key` |
| `Grüße` | `Gr%C3%BC%C3%9Fe` | `Gr%C3%BC%C3%9Fe` |

The difference is the space: `urlencode()` comes from the world of form data and turns it into `+`. Doctrine and Laravel, however, decode the URL components with `rawurldecode()`, which leaves a `+` untouched. So `my+pass%2Bword` becomes `my+pass+word` – the wrong password.

You can check the encoding on the command line. The single quotes stop the shell from interpreting `$` or `#` itself:

```
php -r 'echo rawurlencode($argv[1]), "\n";' 'p@ss:w/rd#1'
p%40ss%3Aw%2Frd%231
```

Without a terminal, use the [URL Encoder & Decoder](https://skriptbox.com/en/tools/url-encoder): its “Encode” mode works like `rawurlencode()` by default, and the “Connection URL” tab assembles user, password, host, port and database into a ready-to-use `DATABASE_URL`. Your input never leaves the browser. Note that JavaScript’s `encodeURIComponent()` leaves a few characters such as `!` or `*` unencoded; they are allowed in the userinfo but can still get in the way further down the line.

### Even simpler: passwords without pitfalls

If you choose the password yourself, you can avoid the problem altogether. A long password made of letters and digits is just as strong as a shorter one with symbols: 32 random characters from upper- and lowercase letters and digits give you about 190 bits. The [Password Generator](https://skriptbox.com/en/tools/password-generator) creates such passwords once you switch off symbols. No encoding, no quoting, no doubled dollar signs – and the URL stays readable.

If your host assigns the password, encoding is the reliable way to go.

## Symfony and Doctrine

In Symfony, the URL usually lives in `.env` or, for local credentials, in `.env.local`. Doctrine splits the URL and decodes each component, so you enter the encoded form:

```
DATABASE_URL='mysql://app:p%40ss%3Aw%2Frd%231@127.0.0.1:3306/shop?serverVersion=8.0&charset=utf8mb4'
```

Two things deserve attention:

- **Quotes in .env:** Unquoted and in double quotes, Symfony replaces `$NAME` and `${NAME}` with environment variables. `"mysql://app:S3cr3t$Key@…"` silently turns into `mysql://app:S3cr3t@…` because there is no variable called `Key`. Single quotes keep the value literally. A fully encoded URL contains no `$` anyway, since it becomes `%24`.
- **The `resolve:` processor:** Many projects have `url: '%env(resolve:DATABASE_URL)%'` in `config/packages/doctrine.yaml`. `resolve:` replaces `%name%` with container parameters. In `p%40ss%3Aw…`, Symfony then sees a parameter called `40ss` and fails with “You have requested a non-existent parameter”. If you don’t need `resolve:`, remove it. Otherwise, double every `%` in `.env`, as in `p%%40ss%%3Aw…`.

Alternatively, leave the password out of the URL entirely and pass it separately. Doctrine merges the values from the URL with the remaining options, so no encoding is needed:

```
# .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)%'
```

Keep in mind: if the URL does contain a password after all, it takes precedence over `password`.

## Laravel

Laravel supports both approaches. The usual one is separate variables such as `DB_HOST`, `DB_USERNAME` and `DB_PASSWORD`. Nothing is URL-encoded there; the password is written as is:

```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=shop
DB_USERNAME=app
DB_PASSWORD='p@ss:w/rd#1'
```

Wrap the password in single quotes whenever it contains spaces, `#`, `$` or quotes. Inside double quotes, the `.env` library Laravel uses replaces expressions like `${NAME}`.

There is also the `DB_URL` variable (`DATABASE_URL` in older versions). When it is set, Laravel parses it, decodes the percent sequences and lets its components take precedence over the individual variables. The same rules apply as above: encode the password with `rawurlencode()`. After changing `.env`, clear any configuration cache with `php artisan config:clear`; otherwise the application keeps using the old values.

## Docker and Docker Compose

Docker Compose interprets `$` in `compose.yaml` itself to substitute variables. To get a literal dollar sign, write `$$`. This matters mostly for passwords passed unencoded, for example to the database 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"
```

The database container receives the password in plain text (`S3cr3t$Key`), the application gets the same string in encoded form. Both have to resolve to the same password. If you keep the values in a `.env` file next to `compose.yaml`, single-quoted values there are not interpolated. Also note that the database images only apply `POSTGRES_PASSWORD` and similar variables on the first start with an empty data directory. To change the password later, change it in the database itself.

## Quick summary

- Encode the password (and the user name, if needed) with `rawurlencode()`, not `urlencode()`.
- Use single quotes in `.env` files so that `$` isn’t interpolated.
- In Symfony, with `%env(resolve:…)%`, double every `%` or drop `resolve:`.
- In `compose.yaml`, write a literal `$` as `$$`.
- Where possible, pass the password as a separate variable instead of inside the URL – or simply use a long password without special characters.


## Tools for this topic

- [URL Encoder & Decoder](https://skriptbox.com/en/tools/url-encoder.md) – URL-encode passwords and text (like rawurlencode), decode them and build connection URLs like DATABASE_URL – nothing is transmitted.
- [Password Generator](https://skriptbox.com/en/tools/password-generator.md) – Generate strong passwords and passphrases for free – right in your browser, nothing is transmitted.
