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.

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:[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4
postgresql://app:secret@db:5432/shop?serverVersion=16&charset=utf8

The URL specification, RFC 3986, 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.

Passwordrawurlencode (correct)urlencode
p@ss:w/rd#1p%40ss%3Aw%2Frd%231p%40ss%3Aw%2Frd%231
my pass+wordmy%20pass%2Bwordmy+pass%2Bword
50%off!50%25off%2150%25off%21
S3cr3t$KeyS3cr3t%24KeyS3cr3t%24Key
GrüßeGr%C3%BC%C3%9FeGr%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: 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 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%[email protected]: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://[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)%'

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

More guides