`.env.example` could use a better database host

[davidmcguiredesign]

Version

6.8.3

What did you expect to happen?

I expected to spin up a MariaDB instance, configure the correct DB_USER, DB_PASSWORD, DB_PORT, DB_HOST, and DB_DATABASE values, point my local Apache instance to the /bedrock/web directory, navigate to the appropriate URL in a browser, and start the WordPress install.

What actually happens?

I configured Apache and confirmed that it functioned as expected. Then I spun up a MariaDB instance and confirmed that I could open it in Beekeeper Studio (a database GUI). Then I noticed .env (copied from .env.example did not show a constant to set the port, so I used the DATABASE_URL value (and commented out the individual constants).

But when I navigated to the site's index page in my browser, the page said only that there was a problem connecting to the database.

Entering the URL into the browser opened it in Beekeeper Studio as expected. Navigating to the WordPress admin page (/wp/wp-admin) revealed the error was mysqli error 2002. This StackOverflow answer notes that connecting via localhost can trigger a different behavior than connecting via 127.0.0.1.

When I changed the host from localhost to 127.0.0.1 and reloaded the page in my browser, the install screen showed as expected.

Steps to reproduce

1. Follow the installation guide up to the “Multisite” heading.
2. As referenced in the installation guide, point Apache to serve bedrock/web as the document root. I did so by adding an entry in Apache's httpd-vhosts.conf file that mapped the bedrock.localhost:80 domain to the bedrock/web directory, and making sure httpd.conf ran Include on that file. Start (or restart) Apache.
3. Start DBngin, add a MariaDB 10 service on port 3308, and start the service.
4. Connect with Beekeeper Studio (remember the port), using user root and no password, add database wp_bedrock (at top of the right side panel).
5. ALTER the password of the root user to (for example) mysecurepassword.
6. Duplicate .env.example as .env. Comment out lines 1–3 and 10–11, and (for my vhost method) add this line below line 7: DATABASE_URL='mysql://root:mysecurepassword@localhost:3308/wp_bedrock'.
7. Navigate to https://bedrock.localhost in a browser. On my system WordPress showed an error.
8. In the DATABASE_URL constant, change localhost to 127.0.0.1.
9. Navigate to https://bedrock.localhost. On my system I saw WordPress's install page.

System info

PHP 8.4.12 (built by Homebrew, with Zend OPCache 8.4.12 and Xdebug 3.4.2)
Apache 2.4.65 (Unix)
MariaDB 10.11.6_intel
DBngin 7.9
MacOS 26.0.1
MacBook Pro 2020 (13 in. Intel, 4 Thunderbolt ports)

Log output

Please confirm this isn't a support request.

No (i.e, this is not a support request)

[retlehs]

Thanks for the issue! This is the first time in 12 years that this has been mentioned. So you're suggesting we just change localhost to 127.0.0.1?

Most frameworks default to localhost and is the most commonly used hostname. Official MySQL and MariaDB docs also use localhost in examples.

[davidmcguiredesign]

Yes, that's what I'm suggesting; though perhaps only for the DATABASE_URL constant.

I've encountered the "localhost" vs. "127.0.0.1" issue before, and connecting via TCP instead of a socket (forced by setting the host as 127.0.0.1) resolved the issue then too. I don't know if that's the best solution—it's just a simple and functional one.

Perhaps my local database server has a misconfigured socket, causing an issue that I can bypass via TCP. But I've also encountered it on Windows with a completely different dev stack, and I think I've encountered it on a production Linux server.

Is configuring a database server and socket within the scope of Bedrock? If not, changing the alternative connection example to something more resilient might outweigh the less efficient protocol. And doing so wouldn't interfere with the people who want the convenience of pasting in a single URI.