Skip to content

docs: add SSL/TLS database connection guide and document missing env vars #2377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Micha Hobert (Isengo1989) merged 11 commits into from
Jul 13, 2026
Merged

docs: add SSL/TLS database connection guide and document missing env vars #2377

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
de097c8
docs: add SSL/TLS database connection guide and document missing env …
shyim Jul 13, 2026
ba55811
Apply suggestions from code review
shyim Jul 13, 2026
14c5a2c
docs: remove incorrect SSL DSN query parameter docs from database guide
shyim Jul 13, 2026
de01c6e
docs: document DATABASE_SSL_CA=true workaround for forcing SSL withou…
shyim Jul 13, 2026
d6ed34a
docs: apply markdown lint fixes
shyim Jul 13, 2026
ab6b551
fix/link-and-tables
Isengo1989 Jul 13, 2026
29d061f
docs: expand DB connection options with use cases and trade-offs
shyim Jul 13, 2026
a713b55
docs: use env var names instead of internal constants in headings
shyim Jul 13, 2026
5ed613c
docs: remove redundant connection options intro section
shyim Jul 13, 2026
9e50ed9
docs: apply markdown lint fixes (blank lines after bold headings)
shyim Jul 13, 2026
c2b4a6a
adjust/typical-syntax
Isengo1989 Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions guides/hosting/configurations/shopware/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,13 @@ This page lists all environment variables that can be used to configure Shopware
| `BLUE_GREEN_DEPLOYMENT` | `0` | This needs super privilege to create trigger |
| `COMPOSER_HOME` | `/tmp/composer` | Caching for the Plugin Manager |
| `COMPOSER_PLUGIN_LOADER` | (empty) | When set to a non-empty value (e.g., `1` or `true`), enables the Composer plugin loader instead of the database plugin loader. All plugins defined in the root `composer.json` will be automatically active, regardless of database settings. |
| `DATABASE_SSL_CA` | (empty) | Path to SSL CA file |
| `DATABASE_SSL_CERT` | (empty) | Path to SSL Cert file |
| `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` | (empty) | Disables verification of the server certificate (1 disables it) |
| `DATABASE_SSL_KEY` | (empty) | Path to SSL Key file |
| `DATABASE_URL` | (empty) | MySQL credentials as DSN |
| `DATABASE_PERSISTENT_CONNECTION` | (empty) | When set to a non-empty value (e.g., `1`), enables persistent database connections via `PDO::ATTR_PERSISTENT`. Useful for long-running worker processes to avoid repeated connection overhead. See [Database connection options](../../infrastructure/database.md#additional-database-connection-options). |
| `DATABASE_PROTOCOL_COMPRESSION` | (empty) | When set to a non-empty value (e.g., `1`), enables MySQL protocol compression (`Mysql::ATTR_COMPRESS`) to reduce network traffic. See [Database connection options](../../infrastructure/database.md#additional-database-connection-options). |
Comment thread
shyim marked this conversation as resolved.
Outdated
| `DATABASE_SSL_CA` | (empty) | Path to the SSL Certificate Authority file (PEM) for verifying a TLS database connection. Automatically applied by `MySQLFactory` — no manual Doctrine configuration needed. See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection). |
| `DATABASE_SSL_CERT` | (empty) | Path to the SSL client certificate file (PEM) for mutual TLS. Automatically applied by `MySQLFactory`. See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection). |
| `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` | (empty) | When set to `1`, skips server certificate verification (non-production only). Requires PHP 8.2+. Automatically applied by `MySQLFactory`. See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection). |
| `DATABASE_SSL_KEY` | (empty) | Path to the SSL client private key file (PEM) for mutual TLS. Automatically applied by `MySQLFactory`. See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection). |
| `DATABASE_URL` | (empty) | MySQL or MariaDB connection string as a DSN. Format: `mysql://user:password@host:port/dbname`. SSL parameters can be embedded as query parameters (`?sslmode=verify-ca&sslrootcert=/path/to/ca.pem`). See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection). |
Comment thread
shyim marked this conversation as resolved.
Outdated
| `ENABLE_OPENSEARCH_FOR_ADMIN_API` | (empty) | When set to `1`, applies OpenSearch globally for supported Admin API searches and listings in Administration. Requires `ADMIN_OPENSEARCH_URL` and `SHOPWARE_ADMIN_ES_ENABLED=1` to be configured. Experimental feature (since 6.7.9.0) |
| `ENABLE_SERVICES` | `auto` | Determines if services are enabled, auto detects that based on `APP_ENV`, other possible values are `true` (or `1`) and `false` (or `0`). When set to `0`, Shopware Services won't be installed on the system |
| `FASTLY_API_KEY` | (empty) | API key for Fastly CDN integration. **Keep this value secure and do not commit it to version control.** |
Expand Down
87 changes: 87 additions & 0 deletions guides/hosting/infrastructure/database.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,93 @@
- `DATABASE_URL` is the connection string for the MySQL primary.
- `DATABASE_REPLICA_x_URL` (e.g `DATABASE_REPLICA_0_URL`, `DATABASE_REPLICA_1_URL`) - is the connection string for the MySQL read-only server.

## SSL/TLS Connection

Many cloud database providers and production environments require encrypted connections.
Shopware supports TLS for MySQL/MariaDB connections through the `DATABASE_SSL_*` environment
variables, or by embedding SSL parameters directly in `DATABASE_URL`.

### Using DATABASE_SSL_* environment variables

Shopware's `MySQLFactory` automatically reads these environment variables and applies them
to the Doctrine database connection. No additional configuration is needed — just set the
variables in your `.env.local` file:

```dotenv
DATABASE_URL="mysql://username:password@host:3306/dbname"
DATABASE_SSL_CA="/etc/ssl/certs/db-ca.pem"

Check warning on line 68 in guides/hosting/infrastructure/database.md

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] guides/hosting/infrastructure/database.md#L68 

Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
Category: PUNCTUATION
Raw output 
guides/hosting/infrastructure/database.md:68:39: Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
 URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
 Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
 Category: PUNCTUATION
DATABASE_SSL_CERT="/etc/ssl/certs/db-client-cert.pem"

Check warning on line 69 in guides/hosting/infrastructure/database.md

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] guides/hosting/infrastructure/database.md#L69 

Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
Category: PUNCTUATION
Raw output 
guides/hosting/infrastructure/database.md:69:50: Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
 URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
 Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
 Category: PUNCTUATION
DATABASE_SSL_KEY="/etc/ssl/certs/db-client-key.pem"

Check warning on line 70 in guides/hosting/infrastructure/database.md

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] guides/hosting/infrastructure/database.md#L70 

Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
Category: PUNCTUATION
Raw output 
guides/hosting/infrastructure/database.md:70:48: Unpaired symbol: ‘"’ seems to be missing (EN_UNPAIRED_QUOTES)
 URL: https://languagetool.org/insights/post/punctuation-guide/#what-are-parentheses 
 Rule: https://community.languagetool.org/rule/show/EN_UNPAIRED_QUOTES?lang=en-US
 Category: PUNCTUATION
# DATABASE_SSL_DONT_VERIFY_SERVER_CERT=1 # Uncomment to skip verification (non-production only)
```

| Variable | Description |
|----------------------------------------|--------------------------------------------------------------------------------------------|
| `DATABASE_SSL_CA` | Path to the Certificate Authority file (PEM). Used for server certificate verification. |
| `DATABASE_SSL_CERT` | Path to the client certificate file (PEM) for mutual TLS. |
| `DATABASE_SSL_KEY` | Path to the client private key file (PEM) for mutual TLS. |
| `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` | Set to `1` to skip server certificate verification (non-production only). Requires PHP 8.2+. |
Comment thread
shyim marked this conversation as resolved.
Outdated

> [!NOTE]
> `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` requires PHP 8.2 or later and the `Pdo\Mysql`
Comment thread
shyim marked this conversation as resolved.
Outdated
> class available in `ext-pdo_mysql`. For a full list of available environment variables,
> see the [Environment Variables reference](../../configurations/shopware/environment-variables.md).

### SSL parameters in DATABASE_URL (alternative)

You can also embed SSL options directly as query parameters in `DATABASE_URL`.
This works through Doctrine's DSN parser and can be used alongside or instead of
the `DATABASE_SSL_*` variables:

```dotenv
DATABASE_URL="mysql://username:password@host:3306/dbname?sslmode=verify-ca&sslrootcert=/etc/ssl/certs/db-ca.pem"
Comment thread
shyim marked this conversation as resolved.
Outdated
```

Common SSL query parameters:

| Parameter | Description |
|---------------|----------------------------------------------------------------------|
| `sslrootcert` | Path to the CA certificate file (PEM format) |
| `sslcert` | Path to the client certificate file (for mutual TLS) |
| `sslkey` | Path to the client private key file (for mutual TLS) |
| `sslverify` | Set to `false` to skip certificate verification (non-production only)|

Comment thread
shyim marked this conversation as resolved.
Outdated
> [!NOTE]
> When both `DATABASE_SSL_*` env vars and DSN query parameters are set, the environment
> variables take precedence because `MySQLFactory` sets them as `driverOptions` after
> parsing the DSN.

### Additional database connection options

Shopware also supports these environment variables for advanced database connections:

```dotenv
# Keep the database connection open across requests (useful for worker processes)
DATABASE_PERSISTENT_CONNECTION=1

# Enable MySQL protocol compression for reduced network traffic
DATABASE_PROTOCOL_COMPRESSION=1
```

### Amazon RDS / Aurora

AWS RDS and Aurora enforce TLS by default. Download the [AWS RDS CA bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)
and reference it in your connection:

```dotenv
DATABASE_URL="mysql://username:password@your-cluster.rds.amazonaws.com:3306/dbname?sslmode=verify-ca&sslrootcert=/etc/ssl/certs/rds-ca-bundle.pem"
```

### Verify the TLS connection

To confirm that TLS is active, run this SQL query via the Shopware CLI or your MySQL client:

```sql
SHOW STATUS LIKE 'Ssl_cipher';
```

A non-empty value (for example, `TLS_AES_256_GCM_SHA384`) confirms the connection is encrypted.

## Setup for long-running environments

When running Shopware in long-lived PHP worker environments such as FrankenPHP worker mode, database connections can stay open long enough to exceed MySQL's `wait_timeout`.
Expand Down
2 changes: 1 addition & 1 deletion ...s/hosting/installation-updates/deployments/deployment-helper-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Check if:

- `DATABASE_URL` is correct and reachable from the deploy environment (host, port, credentials).
- the database service is actually up before the helper runs. In container setups, order startup so the database is ready, or add your own wait.
- TLS is required, and `DATABASE_SSL_CA` / `DATABASE_SSL_CERT` / `DATABASE_SSL_KEY` are set. To bypass server-certificate verification (non-production only), set `DATABASE_SSL_DONT_VERIFY_SERVER_CERT`. See [Environment variables](deployment-helper.md#environment-variables).
- TLS is required, and `DATABASE_SSL_CA` / `DATABASE_SSL_CERT` / `DATABASE_SSL_KEY` are set. Verify the certificate paths are correct and readable by the PHP process. To bypass server-certificate verification (non-production only), set `DATABASE_SSL_DONT_VERIFY_SERVER_CERT`. See [SSL/TLS Connection guide](../../infrastructure/database.md#ssltls-connection) and [Environment variables](deployment-helper.md#environment-variables).

## A step times out on a large shop

Expand Down
8 changes: 4 additions & 4 deletions guides/hosting/installation-updates/deployments/deployment-helper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -476,10 +476,10 @@ Deployment control:
Database:

- `DATABASE_URL` - The database connection string. Required; the Deployment Helper aborts if it is not set.
- `DATABASE_SSL_CA` - Path to the TLS CA certificate for the database connection
- `DATABASE_SSL_CERT` - Path to the TLS client certificate
- `DATABASE_SSL_KEY` - Path to the TLS client key
- `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` - Set to any value to skip server-certificate verification (non-production only)
- `DATABASE_SSL_CA` - Path to the TLS CA certificate for the database connection. Automatically applied by `MySQLFactory`. (see [SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection))
- `DATABASE_SSL_CERT` - Path to the TLS client certificate. Automatically applied by `MySQLFactory`. (see [SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection))
- `DATABASE_SSL_KEY` - Path to the TLS client key. Automatically applied by `MySQLFactory`. (see [SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection))
- `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` - Set to any value to skip server-certificate verification (non-production only). Automatically applied by `MySQLFactory`. (see [SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection))

Store authentication:

Expand Down
Loading