docs: add SSL/TLS database connection guide and document missing env vars#2377
Conversation
…vars - Add comprehensive SSL/TLS Connection section to database infrastructure guide covering DATABASE_SSL_* env vars (auto-wired by MySQLFactory), DSN query parameter alternative, cert generation, AWS RDS example, and verification - Document two previously undocumented database env vars: DATABASE_PERSISTENT_CONNECTION and DATABASE_PROTOCOL_COMPRESSION - Fix environment variables table descriptions to clarify that DATABASE_SSL_* vars are automatically applied by MySQLFactory - Update deployment-helper docs and troubleshooting with accurate links
Developer Docs healthcheckStatus: Completed with |
There was a problem hiding this comment.
Pull request overview
Adds/expands Shopware hosting documentation around secure MySQL/MariaDB connections, and updates related environment-variable references to close gaps discovered around DATABASE_SSL_CA.
Changes:
- Adds an SSL/TLS connection section to the database infrastructure guide, including env-var based setup and a
DATABASE_URLquery-parameter alternative. - Documents two previously missing database env vars (
DATABASE_PERSISTENT_CONNECTION,DATABASE_PROTOCOL_COMPRESSION) in the environment variables reference. - Updates Deployment Helper docs to cross-link to the new SSL/TLS guidance and clarifies troubleshooting steps.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| guides/hosting/installation-updates/deployments/deployment-helper.md | Adds cross-links clarifying that DATABASE_SSL_* are applied automatically by MySQLFactory |
| guides/hosting/installation-updates/deployments/deployment-helper-troubleshooting.md | Improves TLS troubleshooting guidance and links to the SSL/TLS guide |
| guides/hosting/infrastructure/database.md | Introduces new SSL/TLS connection documentation and advanced DB connection options |
| guides/hosting/configurations/shopware/environment-variables.md | Fixes/expands DB-related env var table entries, including new variables and SSL/TLS notes |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
SSL query parameters (sslrootcert, sslcert, sslkey, etc.) do not work via DATABASE_URL for MySQL in PHP. DATABASE_SSL_* env vars are the only supported approach.
Micha Hobert (Isengo1989)
left a comment
Micha Hobert (Isengo1989)
left a comment
There was a problem hiding this comment.
Thx for the PR Soner (@shyim) 👍
Do the 2 options on DBs have any negative impacts that we should mention? For example significant longer request times (due to compression) or connection issues ?
Maybe we can add some use-cases that are very specific, I can imagine setting the persistent DB connection for a cluster can make things very bad, so its clear that this should only be set on the server that runs the worker processes.
Micha Hobert (Isengo1989)
added
feedback-required
Undocumented Feature
|
not really. persistent helps with db reconnect on any connection and compression helps with throughput, i guess it makes little bit slower, but better than LAN port 100% bottle necked 😅 |
If so, I am fine with it and we can merge. I read that this can be an issue if there are multiple servers and the connections are bound then (max connections). EDIT: Just saw the other commits, thx 👍 |
Summary
Adds a comprehensive SSL/TLS database connection guide to the database infrastructure docs and fixes documentation gaps discovered while investigating
DATABASE_SSL_CAin the Shopware source code (MySQLFactory).New SSL/TLS section in database guide:
DATABASE_SSL_*environment variables — auto-wired byMySQLFactory, no manual config neededDATABASE_SSL_DONT_VERIFY_SERVER_CERTTwo previously undocumented env vars added:
DATABASE_PERSISTENT_CONNECTION—PDO::ATTR_PERSISTENTDATABASE_PROTOCOL_COMPRESSION—Mysql::ATTR_COMPRESSFixed env vars table & deployment-helper docs:
DATABASE_URLquery parameters do not work for MySQL SSL in PHP — useDATABASE_SSL_*env vars insteadRelated links
src/Core/Framework/Adapter/Database/MySQLFactory.php— reads allDATABASE_SSL_*+DATABASE_PERSISTENT_CONNECTION+DATABASE_PROTOCOL_COMPRESSIONsrc/Core/Installer/Configuration/EnvConfigWriter.php— writesDATABASE_SSL_*during installsrc/Core/Maintenance/System/Struct/DatabaseConnectionInformation.php— readsDATABASE_SSL_*for setup flowChecklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted..wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes
No pages were moved/renamed — no redirects needed. No new non-standard terms were introduced.