MySQL

Connect to MySQL 5.7 and later with the bundled MariaDB Connector/C driver

MySQL 8 accounts on caching_sha2_password connect on the first try, with no auth plugin to switch over. The same bundled driver covers 5.7 and later, and MariaDB as well; MariaDB-specific notes are on MariaDB.

Quick setup

1. Create Connection

   Click Create Connection… on the welcome window and pick MySQL

2. Test and Save

   Fill in host, port, and credentials, click Test Connection, then Save & Connect

Connection settings

Field	Default	Notes
Host	localhost	TCP only, never a Unix socket
Port	3306
Username	empty	An empty field connects as your macOS login name
Password	empty	Stored in the macOS Keychain
Database	empty	Optional. Leave it empty to browse every database

The session character set is utf8mb4, so emoji and non-Latin text round-trip untouched. A connect attempt gives up after 10 seconds.

Connection URL

mysql://user:password@host:3306/database

Opening a URL connects directly. See Connection URL Reference.

Common setups

Where	Settings
Homebrew	localhost:3306
Docker	localhost with the mapped port, password from MYSQL_ROOT_PASSWORD
MAMP Pro	localhost:8889, user and password root
AWS RDS / Aurora	Endpoint hostname, password or AWS IAM, which signs a fresh 15-minute token on each connect
Google Cloud SQL	Connect via > Cloud SQL Auth Proxy and the instance name. See Cloud SQL Auth Proxy
Remote production	SSH tunnel

Users & Roles

Database > Users & Roles manages users, roles, and privileges. Changes are staged and shown as SQL before they run. See Users & Roles.

Query plans

EXPLAIN FORMAT=JSON, EXPLAIN FORMAT=TREE, and EXPLAIN ANALYZE render as a plan diagram or tree; plain multi-column EXPLAIN stays in the results grid. See EXPLAIN Visualization.

EXPLAIN rendered as a visual plan

Browsing

The sidebar lists every accessible database with each table’s structure and DDL. Switch databases with Cmd+K. A tab keeps the database it was opened on; MySQL switches database in place, so that tab runs on the same connection rather than a second one.

Table and column comments show in the UI: dimmed after a table’s name in the sidebar, and in the grid header tooltip. Turn that off under View Options, the button beside the sidebar’s filter field.

Releasing an idle connection

A connection holds a server thread and one slot against max_connections for as long as it is open, and MySQL’s wait_timeout rarely reclaims it because the connection check counts as activity on the server. Release the Server Connection After, in Options, hands the connection back after that many minutes of no queries and takes a new one on the next query. 0, the default, keeps it.

To stop the check itself, set Check connections to Only when I use the connection in Settings > General. That is the connection-wide setting; this one is per connection and closes the connection rather than quietening it.

Reconnecting costs a TCP connect, the TLS handshake and authentication: measured at 2ms against a server on the same machine and 800ms to 1.9s across the internet. That cost lands on the first query after an idle period, so leave this at 0 for a remote server unless the slot matters more than the wait.

A release is refused, with the reason, while the session holds anything a reconnect would destroy: an open transaction, a temporary table, a prepared statement, a GET_LOCK, LOCK TABLES, a user variable, a changed session setting, or a stored routine call, whose body is opaque.

SSL/TLS

New connections default to Preferred: TLS first, dropping to plain text only after an SSL handshake error. Pick Verify CA with the provider’s certificate for strict validation. See SSL/TLS.

Limitations

• No Unix socket connections. Give the connection a host and a port, and leave networking on in the server.
• LOAD DATA LOCAL INFILE is refused by the driver. Load the file with File > Import > Import Data… instead.

Troubleshooting

Connection refused: check the server is running (brew services start mysql), the port is right, and skip-networking is not set.

Access denied for user ’…’@’…’ (using password: YES): the password is wrong, or the grant does not cover the host you are connecting from. Check both with SHOW GRANTS FOR 'user'@'host';.

Auth plugin errors: caching_sha2_password needs no configuration. For any other plugin error, read the account’s plugin with SELECT user, plugin FROM mysql.user;.