desrosj · Oct 6, 2026 · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   Add a `mariadbVersion` option and `WP_ENV_MARIADB_VERSION` environment variable to choose the MariaDB version used by the Docker runtime, including versions older than 10.4 ([#83751](https://github.com/WordPress/gutenberg/pull/83751)).
+
 ### Bug Fixes
 
 -   Pass `-T` to `docker compose exec` when stdin is not a terminal, so commands run from a Git hook, which has a TTY on stdout but not on stdin, no longer fail with "cannot attach stdin to a TTY-enabled container" ([#78374](https://github.com/WordPress/gutenberg/pull/78374)).

@@ -45,6 +45,7 @@ $ wp-env start --runtime=playground
 | MySQL database | Yes | No (SQLite) |
 | Multisite | Yes | Yes |
 | Custom PHP version | Yes | Yes |
+| Custom MariaDB version | Yes | No (SQLite) |
 | Plugin/theme mounting | Yes | Yes |
 | `wp-env run` command | Yes | No |
 
@@ -601,6 +602,7 @@ To enable editor autocomplete and validation, add a `$schema` key:
 |----------------------|----------------|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
 | `"core"`             | `string\|null` | `null`                                 | The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress.         |
 | `"phpVersion"`       | `string\|null` | `null`                                 | The PHP version to use. If `null` is specified, `wp-env` will use the default version used with production release of WordPress. |
+| `"mariadbVersion"`   | `string\|null` | `null`                                 | The MariaDB version to use: `"lts"`, `"latest"`, or a version such as `"10.11"`. If `null` is specified, `lts` is used.          |
 | `"plugins"`          | `string[]`     | `[]`                                   | A list of plugins to install and activate in the environment.                                                                    |
 | `"themes"`           | `string[]`     | `[]`                                   | A list of themes to install in the environment.                                                                                  |
 | `"port"`             | `integer`      | `8888`                                 | The port number to use for the installation. |
@@ -827,6 +829,21 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 }
 ```
 
+### Specific MariaDB Version
+
+You can tell `wp-env` which MariaDB version the database should run, for compatibility and testing. Use `"lts"`, `"latest"`, or a version such as `"10.11"` or `"11.4.2"`. This can also be set via the environment variable `WP_ENV_MARIADB_VERSION`, which applies to every environment. The Playground runtime uses SQLite and ignores this option.
+
+```json
+{
+	"mariadbVersion": "10.11",
+	"plugins": [ "." ]
+}
+```
+
+MariaDB cannot start on a database written by a newer version. When switching to a lower version, run `wp-env destroy` first so the database is recreated.
+
+MariaDB 5.5 and 10.0 images are not published for ARM processors. On Apple silicon, run those versions under emulation by setting `DOCKER_DEFAULT_PLATFORM=linux/amd64` before running `wp-env start`.
+
 ### Multisite support
 
 You can tell `wp-env` if the site should be multisite enabled.

@@ -3,7 +3,12 @@ const {
 	parseSourceString,
 	includeTestsPath,
 } = require( './parse-source-string' );
-const { checkPort, checkVersion, checkString } = require( './validate-config' );
+const {
+	checkPort,
+	checkVersion,
+	checkMariaDBVersion,
+	checkString,
+} = require( './validate-config' );
 
 /**
  * @typedef {import('./parse-source-string').WPSource} WPSource
@@ -20,6 +25,7 @@ const { checkPort, checkVersion, checkString } = require( './validate-config' );
  * @property {?number}                  phpmyadminPort   An override for the development environment's phpMyAdmin port.
  * @property {?WPSource}                coreSource       An override for all environment's coreSource.
  * @property {?string}                  phpVersion       An override for all environment's PHP version.
+ * @property {?string}                  mariadbVersion   An override for all environment's MariaDB version.
  * @property {?Object.<string, string>} lifecycleScripts An override for various lifecycle scripts.
  */
 
@@ -65,6 +71,15 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 		environmentConfig.phpVersion = process.env.WP_ENV_PHP_VERSION;
 	}
 
+	if ( process.env.WP_ENV_MARIADB_VERSION ) {
+		checkMariaDBVersion(
+			'environment variable',
+			'WP_ENV_MARIADB_VERSION',
+			process.env.WP_ENV_MARIADB_VERSION
+		);
+		environmentConfig.mariadbVersion = process.env.WP_ENV_MARIADB_VERSION;
+	}
+
 	return environmentConfig;
 };
 

@@ -11,6 +11,7 @@ const {
 	checkStringArray,
 	checkObjectWithValues,
 	checkVersion,
+	checkMariaDBVersion,
 	checkValidURL,
 } = require( './validate-config' );
 const getConfigFromEnvironmentVars = require( './get-config-from-environment-vars' );
@@ -51,6 +52,7 @@ const mergeConfigs = require( './merge-configs' );
  * @property {Object}                    config         Mapping of wp-config.php constants to their desired values.
  * @property {Object.<string, WPSource>} mappings       Mapping of WordPress directories to local directories which should be mounted.
  * @property {string|null}               phpVersion     Version of PHP to use in the environments, of the format 0.0.
+ * @property {string|null}               mariadbVersion Version of MariaDB to use in the environments: "lts", "latest", or of the format 0.0. Null uses the default.
  */
 
 /**
@@ -79,6 +81,7 @@ const mergeConfigs = require( './merge-configs' );
 const DEFAULT_ENVIRONMENT_CONFIG = {
 	core: null,
 	phpVersion: null,
+	mariadbVersion: null,
 	plugins: [],
 	themes: [],
 	port: 8888,
@@ -327,6 +330,13 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.phpVersion = overrides.phpVersion;
 	}
 
+	if ( overrides.mariadbVersion ) {
+		overrideConfig.mariadbVersion = overrides.mariadbVersion;
+		overrideConfig.env.development.mariadbVersion =
+			overrides.mariadbVersion;
+		overrideConfig.env.tests.mariadbVersion = overrides.mariadbVersion;
+	}
+
 	if ( overrides.multisite ) {
 		overrideConfig.multisite = overrides.multisite;
 		overrideConfig.env.development.multisite = overrides.multisite;
@@ -532,6 +542,18 @@ async function parseEnvironmentConfig(
 		parsedConfig.phpVersion = config.phpVersion;
 	}
 
+	if ( config.mariadbVersion !== undefined ) {
+		// Support null as a valid input.
+		if ( config.mariadbVersion !== null ) {
+			checkMariaDBVersion(
+				configFile,
+				`${ environmentPrefix }mariadbVersion`,
+				config.mariadbVersion
+			);
+		}
+		parsedConfig.mariadbVersion = config.mariadbVersion;
+	}
+
 	if ( config.core !== undefined ) {
 		parsedConfig.coreSource = includeTestsPath(
 			await parseCoreSource( config.core, options ),

@@ -30,6 +30,7 @@ exports[`Config Integration > should load local and override configuration files
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 23306,
       "phpVersion": null,
@@ -62,6 +63,7 @@ exports[`Config Integration > should load local and override configuration files
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,
@@ -115,6 +117,7 @@ exports[`Config Integration > should load local configuration file 1`] = `
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 13306,
       "phpVersion": null,
@@ -147,6 +150,7 @@ exports[`Config Integration > should load local configuration file 1`] = `
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,
@@ -200,6 +204,7 @@ exports[`Config Integration > should use default configuration 1`] = `
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": null,
       "phpVersion": null,
@@ -232,6 +237,7 @@ exports[`Config Integration > should use default configuration 1`] = `
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": null,
       "phpVersion": null,
@@ -285,6 +291,7 @@ exports[`Config Integration > should use environment variables over local and ov
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 23306,
       "phpVersion": null,
@@ -318,6 +325,7 @@ exports[`Config Integration > should use environment variables over local and ov
         "url": "https://github.com/WordPress/WordPress.git",
       },
       "mappings": {},
+      "mariadbVersion": null,
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,

@@ -49,6 +49,7 @@ const DEFAULT_CONFIG = {
 	phpmyadminPort: null,
 	multisite: false,
 	phpVersion: null,
+	mariadbVersion: null,
 	coreSource: {
 		type: 'git',
 		url: 'https://github.com/WordPress/WordPress.git',
@@ -104,6 +105,7 @@ describe( 'parseConfig', () => {
 		delete process.env.WP_ENV_TESTS_PORT;
 		delete process.env.WP_ENV_CORE;
 		delete process.env.WP_ENV_PHP_VERSION;
+		delete process.env.WP_ENV_MARIADB_VERSION;
 		delete process.env.WP_ENV_LIFECYCLE_SCRIPT_AFTER_START;
 	} );
 
@@ -612,4 +614,106 @@ describe( 'parseConfig', () => {
 			)
 		);
 	} );
+
+	it( 'should parse mariadbVersion at the root and per environment', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					mariadbVersion: '10.11',
+					env: {
+						tests: {
+							mariadbVersion: 'latest',
+						},
+					},
+				};
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+
+		expect( parsed.mariadbVersion ).toBe( '10.11' );
+		expect( parsed.env.tests.mariadbVersion ).toBe( 'latest' );
+	} );
+
+	it( 'should accept a null mariadbVersion', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return { mariadbVersion: null };
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+
+		expect( parsed.mariadbVersion ).toBeNull();
+	} );
+
+	it( 'should throw for an invalid mariadbVersion', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return { env: { tests: { mariadbVersion: 'LTS' } } };
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				'Invalid /test/gutenberg/.wp-env.json: "tests.mariadbVersion" must be "lts", "latest", or a version such as "10.11" or "11.4.2".'
+			)
+		);
+	} );
+
+	it( 'should override mariadbVersion in every environment with WP_ENV_MARIADB_VERSION', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					mariadbVersion: '10.11',
+					env: { tests: { mariadbVersion: 'latest' } },
+				};
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+		process.env.WP_ENV_MARIADB_VERSION = '10.3';
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+
+		expect( parsed.mariadbVersion ).toBe( '10.3' );
+		expect( parsed.env.development.mariadbVersion ).toBe( '10.3' );
+		expect( parsed.env.tests.mariadbVersion ).toBe( '10.3' );
+	} );
+
+	it( 'should throw for an invalid WP_ENV_MARIADB_VERSION', async () => {
+		process.env.WP_ENV_MARIADB_VERSION = 'LTS';
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				'Invalid environment variable: "WP_ENV_MARIADB_VERSION" must be "lts", "latest", or a version such as "10.11" or "11.4.2".'
+			)
+		);
+	} );
 } );
@@ -8,6 +8,7 @@ const {
 	checkStringArray,
 	checkObjectWithValues,
 	checkVersion,
+	checkMariaDBVersion,
 	checkValidURL,
 } = require( '../validate-config' );
 
@@ -304,6 +305,40 @@ describe( 'validate-config', () => {
 		} );
 	} );
 
+	describe( 'checkMariaDBVersion', () => {
+		it( 'throws for non-string', () => {
+			expect( () =>
+				checkMariaDBVersion( 'test.json', 'test', 10.11 )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string.'
+				)
+			);
+		} );
+
+		it.each( [ 'LTS', 'Latest', '11-noble', 'lts-10', '10.x', '' ] )(
+			'throws for invalid value %j',
+			( version ) => {
+				expect( () =>
+					checkMariaDBVersion( 'test.json', 'test', version )
+				).toThrow(
+					new ValidationError(
+						'Invalid test.json: "test" must be "lts", "latest", or a version such as "10.11" or "11.4.2".'
+					)
+				);
+			}
+		);
+
+		it.each( [ 'lts', 'latest', '5', '10', '10.11', '10.3.39', '11.4.2' ] )(
+			'passes for %j',
+			( version ) => {
+				expect( () =>
+					checkMariaDBVersion( 'test.json', 'test', version )
+				).not.toThrow();
+			}
+		);
+	} );
+
 	describe( 'checkValidURL', () => {
 		it( 'throws for invalid URLs', () => {
 			expect( () =>