|
| 1 | +--- |
| 2 | +nav: |
| 3 | + title: Database |
| 4 | + position: 20 |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +# Database |
| 9 | + |
| 10 | +This guide explains how to operate Shopware with a reliable database setup. |
| 11 | +It covers cluster-based scaling for read traffic and connection handling for long-running PHP worker environments. |
| 12 | + |
| 13 | +## Cluster Setup |
| 14 | + |
| 15 | +::: info |
| 16 | +We recommend the usage of [ProxySQL](https://proxysql.com/) as a proxy for the database cluster instead of configuring the application to connect to different database servers directly. |
| 17 | +ProxySQL allows you to manage the database cluster more efficiently and provides additional features like query caching, connection pooling, load balancing, and failover. |
| 18 | +::: |
| 19 | + |
| 20 | +To scale Shopware even further, we recommend using a database cluster. |
| 21 | +A database cluster consists of multiple read-only servers managed by a single primary instance. |
| 22 | + |
| 23 | +Shopware already splits read and write SQL queries by default. |
| 24 | +When a write [`INSERT`/`UPDATE`/`DELETE`/...](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48) query is executed, the query is delegated to the primary server, and the current connection uses only the primary node for subsequent calls. |
| 25 | +This is ensured by the `executeStatement` method in the [DebugStack decoration](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48). |
| 26 | +That way, Shopware can ensure read-write consistency for records within the same request. |
| 27 | +However, it doesn't take into account that read-only child nodes might not be in sync with the primary node. |
| 28 | +This is left to the database replication process. |
| 29 | + |
| 30 | +### Preparing Shopware |
| 31 | + |
| 32 | +We suggest following the steps below to make the splitting the most effective. |
| 33 | + |
| 34 | +#### Using the optimal MySQL configuration |
| 35 | + |
| 36 | +By default, Shopware does not set specific MySQL configurations that make sure the database is optimized for Shopware usage. |
| 37 | +These variables are set in cluster mode only on the read-only server. |
| 38 | +To make sure that Shopware works flawlessly, these configurations must be configured directly on the MySQL server so these variables are set on any server. |
| 39 | + |
| 40 | +The following options should be set: |
| 41 | + |
| 42 | +- Make sure that `group_concat_max_len` is by default higher or equal to `320000` |
| 43 | +- Make sure that `sql_mode` doesn't contain `ONLY_FULL_GROUP_BY` |
| 44 | + |
| 45 | +After this change, you can set also `SQL_SET_DEFAULT_SESSION_VARIABLES=0` in the `.env` file so Shopware does not check for those variables at runtime. |
| 46 | + |
| 47 | +### Configure the database cluster |
| 48 | + |
| 49 | +To use the MySQL cluster, you have to configure the following in the `.env` file: |
| 50 | + |
| 51 | +- `DATABASE_URL` is the connection string for the MySQL primary. |
| 52 | +- `DATABASE_REPLICA_x_URL` (e.g `DATABASE_REPLICA_0_URL`, `DATABASE_REPLICA_1_URL`) - is the connection string for the MySQL read-only server. |
| 53 | + |
| 54 | +## Setup for long-running environments |
| 55 | + |
| 56 | +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`. |
| 57 | +This can lead to `MySQL server has gone away` errors on later requests. |
| 58 | + |
| 59 | +Shopware does not install a reconnect package by default, but you can enable this behavior yourself with [`facile-it/doctrine-mysql-come-back`](https://github.com/facile-it/doctrine-mysql-come-back): |
| 60 | + |
| 61 | +```bash |
| 62 | +composer require facile-it/doctrine-mysql-come-back |
| 63 | +``` |
| 64 | + |
| 65 | +Configure the wrapper class on `DATABASE_URL` with `Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connection`: |
| 66 | + |
| 67 | +```dotenv |
| 68 | +DATABASE_URL="mysql://username:password@localhost:3306/dbname?wrapperClass=?wrapperClass=Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connection&driverOptions[x_reconnect_attempts]=3" |
| 69 | +``` |
| 70 | + |
| 71 | +If you are using Shopware with read replicas, use `Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connections\PrimaryReadReplicaConnection` instead: |
| 72 | + |
| 73 | +```dotenv |
| 74 | +DATABASE_URL="mysql://username:password@localhost:3306/dbname?wrapperClass=Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connections\PrimaryReadReplicaConnection&driverOptions[x_reconnect_attempts]=3" |
| 75 | +DATABASE_REPLICA_0_URL="mysql://username:password@replica:3306/dbname" |
| 76 | +``` |
0 commit comments