wp-env: Fix MySQL startup race condition causing database connection errors

[LiamSarsfield]

What?

Closes #62242

Adds a MySQL healthcheck to wp-env to prevent the race condition where WordPress containers start before MySQL is ready to accept connections.

Why?

WordPress containers were starting before MySQL was ready to accept connections, causing intermittent "Error establishing a database connection" errors. This is especially problematic in CI environments where timing variations are more common.

The root cause is that Docker Compose's depends_on in array format only waits for the container to start, not for the service to be ready. MySQL can take several seconds after container start to initialize and accept connections.

How?

1. Added MySQL healthcheck using MariaDB's official healthcheck.sh script with --connect and --innodb_initialized flags. This verifies both TCP connectivity and that the InnoDB storage engine is fully initialized.

2. Added MARIADB_AUTO_UPGRADE=1 environment variable to MySQL containers. This ensures the healthcheck user is automatically created for existing wp-env installations that don't have it. Without this, healthcheck.sh would fail on existing databases. This is the recommended approach from MariaDB documentation.

3. Used generous timeouts for CI environments - 60s start_period, 10s timeout, 12 retries (5s interval) provides ~2 minutes total window for slow CI runners.

4. Updated depends_on for wordpress and tests-wordpress services to use the object format with condition: service_healthy, so they wait for MySQL to be healthy before starting.

5. Start both MySQL services in parallel - Changed dockerCompose.upOne('mysql') to dockerCompose.upMany(['mysql', 'tests-mysql']) to allow both MySQL services to initialize concurrently while sources download.

6. Fixed clean() reliability - The clean command now starts only the MySQL service(s) needed for the environment being cleaned (previously always started only mysql even when cleaning tests).

7. Removed dead code - Removed the checkDatabaseConnection function and associated retry logic since Docker Compose healthchecks now handle MySQL readiness.

Testing Instructions

Setup

1. Clone this branch:

   git clone -b fix/HOG-482-wp-env-mysql-healthcheck https://github.com/LiamSarsfield/gutenberg.git
   cd gutenberg
   npm install

2. Link the local wp-env globally (so wp-env command uses this PR's code):

   cd packages/env
   npm link

3. Navigate to any directory with a .wp-env.json file (or any plugin/theme):

   cd /path/to/your/project

Test basic functionality

wp-env destroy  # Start fresh (optional but recommended)
wp-env start

Verify WordPress loads without "Error establishing a database connection".

Verify the healthcheck is working

# Check the MySQL container health status:
docker ps --format "table {{.Names}}\t{{.Status}}" | grep mysql
# Should show "(healthy)" in the status column

Test the clean command

wp-env clean development
wp-env clean tests
wp-env clean all

Test with existing installation (verifies MARIADB_AUTO_UPGRADE)

wp-env start  # Start normally first
wp-env stop
wp-env start  # Should work without issues on restart

Run unit tests

cd /path/to/gutenberg
npm run test:unit -- packages/env/lib/test/

All 47 tests pass.

Cleanup

When done testing, unlink the local wp-env:

npm unlink -g @wordpress/env

Testing Instructions for Keyboard

Not applicable - this PR has no user interface changes.

Screenshots or screencast

Not applicable - this PR has no visual changes.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: First-time Contributor.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @paolopiaggio, @peterfabian.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: paolopiaggio, peterfabian.

Co-authored-by: LiamSarsfield <[email protected]>
Co-authored-by: talldan <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: louiswol94 <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @LiamSarsfield! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.