From b5bfc4bcb05acc6ca1dc341428812bc1022cc53e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Bajsarowicz?= Date: Sun, 22 Mar 2026 20:58:57 +0100 Subject: [PATCH] docs: add database distribution selection guide Document how to choose between MariaDB and MySQL using MYSQL_DISTRIBUTION and MYSQL_DISTRIBUTION_VERSION variables. Include note about Drupal/CakePHP using DB_DISTRIBUTION prefix and warning about switching distributions on existing volumes. --- environments/customizing.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/environments/customizing.md b/environments/customizing.md index d5a936c..e66d13a 100644 --- a/environments/customizing.md +++ b/environments/customizing.md @@ -6,9 +6,8 @@ To configure your project with a non-default PHP version, add the following to t PHP_VERSION=7.2 -The versions of MariaDB, Elasticsearch, Varnish, Redis, NodeJS and Composer may also be similarly configured using variables in the `.env` file: +The versions of Elasticsearch, Varnish, Redis, NodeJS and Composer may also be similarly configured using variables in the `.env` file: - * `MARIADB_VERSION` * `ELASTICSEARCH_VERSION` * `REDIS_VERSION` * `VALKEY_VERSION` @@ -17,6 +16,33 @@ The versions of MariaDB, Elasticsearch, Varnish, Redis, NodeJS and Composer may * `NODE_VERSION` * `COMPOSER_VERSION` +## Database + +Warden supports both **MariaDB** (default) and **MySQL** as the database engine. The distribution and version are controlled via two environment variables in your project's `.env` file: + + * `MYSQL_DISTRIBUTION` — set to `mariadb` (default) or `mysql` + * `MYSQL_DISTRIBUTION_VERSION` — the image tag/version to use + +For example, to use MariaDB 11.4: + + MYSQL_DISTRIBUTION=mariadb + MYSQL_DISTRIBUTION_VERSION=11.4 + +To use MySQL 8.4 instead: + + MYSQL_DISTRIBUTION=mysql + MYSQL_DISTRIBUTION_VERSION=8.4 + +:::{note} +Drupal and CakePHP environments use `DB_DISTRIBUTION` and `DB_DISTRIBUTION_VERSION` instead of the `MYSQL_` prefix. The values and behavior are the same. +::: + +After changing the database distribution or version, run `warden env up` to re-create the database container. + +:::{warning} +Switching distributions (e.g. from MariaDB to MySQL) is **not** a drop-in replacement for existing data volumes. If you change the distribution on an existing environment, you should export your database first, remove the db volume (`warden env down -v`), and re-import after the new container is running. +::: + Start of some environments could be skipped by using variables in `.env` file: * `WARDEN_DB=0`