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’sparse_url()uses the last@, other parsers use the first. You shouldn’t rely on either./,?and#– end the host part early. Formysql://app:ab/cd@db/shop,parse_url()simply returnsfalse, and Doctrine reportsMalformed parameter "url".:– separates user name and password and, after the host, the port.%– starts an encoded sequence. A password like50%offgets mangled when decoded or is rejected as invalid.- Spaces, quotes,
$and\– not the main problem for the URL itself, but for the.envfile 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: 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
$NAMEand${NAME}with environment variables."mysql://app:S3cr3t$Key@…"silently turns intomysql://app:S3cr3t@…because there is no variable calledKey. Single quotes keep the value literally. A fully encoded URL contains no$anyway, since it becomes%24. - The
resolve:processor: Many projects haveurl: '%env(resolve:DATABASE_URL)%'inconfig/packages/doctrine.yaml.resolve:replaces%name%with container parameters. Inp%40ss%3Aw…, Symfony then sees a parameter called40ssand fails with “You have requested a non-existent parameter”. If you don’t needresolve:, remove it. Otherwise, double every%in.env, as inp%%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(), noturlencode(). - Use single quotes in
.envfiles so that$isn’t interpolated. - In Symfony, with
%env(resolve:…)%, double every%or dropresolve:. - 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 URL-encode passwords and text (like rawurlencode), decode them and build connection URLs like DATABASE_URL – nothing is transmitted.
- Password Generator Generate strong passwords and passphrases for free – right in your browser, nothing is transmitted.
More guides
- Redirects for a website relaunch How to plan 301 redirects for a relaunch: collect old URLs, map targets, avoid chains and check the result.
- Which favicons does a website need? Which favicon files and sizes a website really needs today – favicon.ico, SVG, Apple touch icon and web manifest – including the HTML.
- Password-protect a directory (.htpasswd) Protect a directory or staging site with .htaccess and .htpasswd – for Apache and nginx, using secure hashing.
- Optimize images for the web Resize and compress images the right way: suitable sizes, WebP, AVIF or JPEG, quality, responsive images and lazy loading.
- Accessible colors: contrast according to WCAG What the WCAG contrast ratio means, which values apply to text and UI components and how to fix colors that are too weak.
- UUID v4, v7 or ULID as a primary key? When UUIDs make sense as primary keys, why v7 and ULID suit databases better than v4 and how to store them.
- Using JWT securely Common security mistakes with JSON Web Tokens and how to avoid them: alg none, weak keys, missing checks and where to store tokens.