wp-env: Add MySQL healthcheck to fix startup race condition

WordPress containers were starting before MySQL was ready to accept
connections, causing intermittent "Error establishing a database
connection" errors, especially in CI environments.

This change:
- Adds a healthcheck to mysql and tests-mysql services using
  mariadb-admin ping with root credentials
- Updates WordPress depends_on to use condition: service_healthy
- Starts both MySQL services in parallel for faster initialization
- Removes redundant retry logic now handled by Docker Compose

Author: LiamSarsfield

packages/env/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Bug Fixes
+
+-   Add MySQL healthcheck to prevent race condition where WordPress containers start before MySQL is ready to accept connections.
+
 ## 10.39.0 (2026-01-29)
 
 ### New Features

packages/env/lib/runtime/docker/build-docker-compose-config.js

@@ -181,6 +181,20 @@ module.exports = function buildDockerComposeConfig( config ) {
 		config.env.tests.phpmyadminPort ?? ''
 	}}:80`;
 
+	// MySQL healthcheck using mariadb-admin ping.
+	// Uses root credentials to avoid requiring special healthcheck user,
+	// which would break existing wp-env installations.
+	const mysqlHealthcheck = {
+		test: [
+			'CMD-SHELL',
+			'mariadb-admin ping -h localhost -u root -p$MYSQL_ROOT_PASSWORD',
+		],
+		interval: '5s',
+		timeout: '5s',
+		retries: 10,
+		start_period: '30s',
+	};
+
 	return {
 		services: {
 			mysql: {
@@ -193,6 +207,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_DATABASE: dbEnv.development.WORDPRESS_DB_NAME,
 				},
 				volumes: [ 'mysql:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			'tests-mysql': {
 				image: 'mariadb:lts',
@@ -204,9 +219,14 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_DATABASE: dbEnv.tests.WORDPRESS_DB_NAME,
 				},
 				volumes: [ 'mysql-test:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			wordpress: {
-				depends_on: [ 'mysql' ],
+				depends_on: {
+					mysql: {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'WordPress.Dockerfile',
@@ -224,7 +244,11 @@ module.exports = function buildDockerComposeConfig( config ) {
 				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			'tests-wordpress': {
-				depends_on: [ 'tests-mysql' ],
+				depends_on: {
+					'tests-mysql': {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'Tests-WordPress.Dockerfile',

packages/env/lib/runtime/docker/index.js

@@ -11,7 +11,6 @@ const { rimraf } = require( 'rimraf' );
 /**
  * Promisified dependencies
  */
-const sleep = util.promisify( setTimeout );
 const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
@@ -26,7 +25,6 @@ const {
 	validateRunContainer,
 } = require( './validate-run-container' );
 const {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,
@@ -174,7 +172,7 @@ class DockerRuntime {
 		}
 
 		await Promise.all( [
-			dockerCompose.upOne( 'mysql', {
+			dockerCompose.upMany( [ 'mysql', 'tests-mysql' ], {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
 					? [ '--build', '--force-recreate' ]
@@ -250,19 +248,6 @@ class DockerRuntime {
 		if ( shouldConfigureWp ) {
 			spinner.text = 'Configuring WordPress.';
 
-			try {
-				await checkDatabaseConnection( fullConfig );
-			} catch ( error ) {
-				// Wait 30 seconds for MySQL to accept connections.
-				await retry( () => checkDatabaseConnection( fullConfig ), {
-					times: 30,
-					delay: 1000,
-				} );
-
-				// It takes 3-4 seconds for MySQL to be ready after it starts accepting connections.
-				await sleep( 4000 );
-			}
-
 			// Retry WordPress installation in case MySQL *still* wasn't ready.
 			await Promise.all( [
 				retry(

packages/env/lib/test/build-docker-compose-config.js

@@ -131,4 +131,71 @@ describe( 'buildDockerComposeConfig', () => {
 		expect( dockerConfig.volumes.wordpress ).toBe( undefined );
 		expect( dockerConfig.volumes[ 'tests-wordpress' ] ).toBe( undefined );
 	} );
+
+	it( 'should add healthcheck to mysql services', () => {
+		const config = buildDockerComposeConfig( {
+			workDirectoryPath: '/some/path',
+			env: {
+				development: {
+					port: 8888,
+					mysqlPort: 3306,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+				tests: {
+					port: 8889,
+					mysqlPort: 3307,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+			},
+		} );
+
+		expect( config.services.mysql.healthcheck ).toBeDefined();
+		expect( config.services.mysql.healthcheck.test ).toContain(
+			'CMD-SHELL'
+		);
+		expect( config.services.mysql.healthcheck.interval ).toBe( '5s' );
+		expect( config.services.mysql.healthcheck.start_period ).toBe( '30s' );
+
+		expect( config.services[ 'tests-mysql' ].healthcheck ).toBeDefined();
+		expect( config.services[ 'tests-mysql' ].healthcheck.test ).toContain(
+			'CMD-SHELL'
+		);
+	} );
+
+	it( 'should use service_healthy condition for WordPress depends_on', () => {
+		const config = buildDockerComposeConfig( {
+			workDirectoryPath: '/some/path',
+			env: {
+				development: {
+					port: 8888,
+					mysqlPort: 3306,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+				tests: {
+					port: 8889,
+					mysqlPort: 3307,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+			},
+		} );
+
+		expect( config.services.wordpress.depends_on ).toEqual( {
+			mysql: { condition: 'service_healthy' },
+		} );
+		expect( config.services[ 'tests-wordpress' ].depends_on ).toEqual( {
+			'tests-mysql': { condition: 'service_healthy' },
+		} );
+	} );
 } );