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

guides/hosting/configurations/shopware/environment-variables.md

@@ -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 (`PDO::MYSQL_ATTR_COMPRESS`) to reduce network traffic. See [Database connection options](../../infrastructure/database.md#additional-database-connection-options)                                                                                                                                          |
+| `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`. For TLS connections, use the `DATABASE_SSL_*` environment variables instead of query parameters. See [Database SSL/TLS Setup](../../infrastructure/database.md#ssltls-connection).                                                                                                                                        |
 | `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.**                                                                                                                                                                                                                                                                              |

guides/hosting/infrastructure/database.md

@@ -51,6 +51,86 @@
 - `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.
+
+### 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"
+DATABASE_SSL_CERT="/etc/ssl/certs/db-client-cert.pem"
+DATABASE_SSL_KEY="/etc/ssl/certs/db-client-key.pem"
+# DATABASE_SSL_DONT_VERIFY_SERVER_CERT=1  # Uncomment to skip verification (non-production only)
+```
+
+The following table describes the available `DATABASE_SSL_*` variables.
+
+| 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+ |
+
+> [!NOTE]
+> `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` requires PHP 8.2 or later and the `PDO\MySQL`
+> class available in `ext-pdo_mysql`. For a full list of available environment variables,
+> see the [Environment Variables reference](../../configurations/shopware/environment-variables.md).
+
+#### Force SSL without a CA certificate
+
+If your database server requires TLS but you don't have the CA certificate handy
+(for example, on a managed cloud database), you can force an encrypted connection
+without certificate verification:
+
+```dotenv
+DATABASE_SSL_CA=true
+DATABASE_SSL_DONT_VERIFY_SERVER_CERT=1
+```
+
+This tells MySQL to use SSL for the connection but skip certificate validation.
+Only use this in development or staging — never in production without a proper CA.
+
+### 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"
+DATABASE_SSL_CA="/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`.

guides/hosting/installation-updates/deployments/deployment-helper-troubleshooting.md

@@ -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
 

guides/hosting/installation-updates/deployments/deployment-helper.md

@@ -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: