Connect to MySQL in Docker from your Mac

What you need

• Docker running on your Mac.
• A container from the official mysql image with port 3306 published:

docker run --name mysql -e MYSQL_ROOT_PASSWORD=<root-password> \
  -e MYSQL_DATABASE=app -e MYSQL_USER=app -e MYSQL_PASSWORD=<app-password> \
  -p 3306:3306 -d mysql:8.4

MYSQL_ROOT_PASSWORD is mandatory (unless you opt into an empty or random root password). MYSQL_DATABASE creates a database, and MYSQL_USER with MYSQL_PASSWORD creates a user with full rights on that database. If port 3306 is taken on your Mac, publish another, for example -p 3307:3306.

Find your connection details

On a mysql:8.4 container (MySQL 8.4.11) started as above, both root and app may connect from any host (%), and use the caching_sha2_password plugin:

SELECT user, host, plugin FROM mysql.user ORDER BY user;

user	host	plugin
app	%	caching_sha2_password
mysql.infoschema	localhost	caching_sha2_password
mysql.session	localhost	caching_sha2_password
mysql.sys	localhost	caching_sha2_password
root	%	caching_sha2_password
root	localhost	caching_sha2_password

The variables only apply to a new data directory. If the container starts with an existing database (a volume at /var/lib/mysql, say), the image ignores them and changes nothing, so a new MYSQL_ROOT_PASSWORD has no effect. Change passwords with ALTER USER instead.

Wait for it to be ready. On first start the image initialises the database with a temporary server that doesn’t listen on TCP, then restarts. It’s ready when docker logs mysql shows ready for connections with port: 3306.

Connection string

mysql://app:<app-password>@127.0.0.1:3306/app

See MySQL connection strings and special characters in passwords.

TLS

MySQL 8.4 creates its own certificates on first start, so TLS is on without any setup; the log notes CA certificate ca.pem is self signed. The mysql client uses TLS when the server offers it: a test connection with the client’s default settings reported Ssl_version TLSv1.3.

Because the certificate authority is the container’s own, full verification can’t succeed. Asking for it without a CA file fails at once:

ERROR 2026 (HY000): SSL connection error: CA certificate is required if ssl-mode is VERIFY_CA or VERIFY_IDENTITY

With the container’s CA (docker cp mysql:/var/lib/mysql/ca.pem .), --ssl-mode=VERIFY_CA connects, but VERIFY_IDENTITY still fails, because the server certificate is named MySQL_Server_8.4.11_Auto_Generated_Server_Certificate, not your host:

ERROR 2026 (HY000): SSL connection error: error:0A000086:SSL routines::certificate verify failed

For a container on your own Mac, encryption without verification is fine.

Connect with Inlet

1. Choose New Connection, pick MySQL, and enter 127.0.0.1, the published port, the user and password, and the database if you made one. Or paste mysql://app:<app-password>@127.0.0.1:3306/app and Inlet fills in the form.
2. Under TLS, choose prefer or require. To check the certificate, copy ca.pem out of the container as above, choose verify-ca, and select it as the CA file.
3. Save the password in the Keychain, or have Inlet ask each time.
4. Tag the connection local (or development).

Connect from the command line

The container has a client, so you don’t need one on your Mac:

docker exec -it mysql mysql -uroot -p

From your Mac, with the MySQL client from Homebrew’s mysql-client package (keg-only, so /opt/homebrew/opt/mysql-client/bin/mysql), use 127.0.0.1:

mysql -h 127.0.0.1 -P 3306 -u app -p app

Not localhost. On Unix, MySQL programs treat localhost specially: they connect through a Unix socket file and ignore --port. With no MySQL server running on the Mac itself, that fails (here from a client container, which looks for its own socket path):

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)

Use -h 127.0.0.1, or add --protocol=TCP.

Troubleshooting

The MySQL errors below were reproduced against a mysql:8.4 container (MySQL 8.4.11), with the client in a second container reaching it through the published port, the way your Mac does.

• ERROR 1045: Access denied: wrong user or password, or the variables were ignored because the data directory already existed. Note the address: connections through the published port come from Docker’s network, not localhost, so they match '%' accounts, not 'localhost' ones.

  ERROR 1045 (28000): Access denied for user 'app'@'192.168.215.1' (using password: YES)
  

• ERROR 2003: Can’t connect to MySQL server: nothing is listening on that port. The container isn’t running, the port isn’t published, or the server is still initialising.

  ERROR 2003 (HY000): Can't connect to MySQL server on 'host.docker.internal:55479' (111)
  

  On a Mac the number in brackets is the macOS error code instead (61 for connection refused).

• ERROR 2002, Can't connect to local MySQL server through socket: you used localhost. Use 127.0.0.1.

• port is already allocated from docker run: another container already publishes that host port. Publish a different one.