Connect to PlanetScale from your Mac

What you need

• Access to the database in the PlanetScale dashboard, or the pscale CLI.
• A password for the branch you want. Each password belongs to one branch and can’t read any other branch.

This page covers PlanetScale’s Vitess databases, which speak the MySQL protocol. PlanetScale Postgres databases work differently: you create role credentials and connect with a PostgreSQL connection string (pscale connect doesn’t support them).

Find your connection details

1. On the database’s dashboard page, click Connect.
2. Pick the branch, a password role and a name, then click Create password.
3. Under Select your language or framework, choose Other to see the details as a list: database name, host, user name and password.

Copy the password now: PlanetScale stores only a hash, so it can’t show it again.

Passwords from the Connect button get the Admin role. For other roles, go to the database’s Settings → Passwords → New password. The roles are:

A password’s role can’t be changed later, and on production branches with safe migrations turned on, nobody can run DDL directly, whatever the role.

Host and port. The host is a PlanetScale edge address such as aws.connect.psdb.cloud (an optimised route) or a region’s own, such as us-east.connect.psdb.cloud. The port is 3306.

IP restrictions apply per password: on the Passwords page, open a password’s menu and choose Manage IP restrictions.

Connection string

mysql://<username>:<password>@aws.connect.psdb.cloud:3306/<database>

Use the host your password was created with. Each branch is a separate MySQL database as far as your client is concerned, so you need separate details per branch. See MySQL connection strings.

TLS

TLS is required. PlanetScale signs its server certificates with a CA that’s in the system root stores of common operating systems, and promises to keep using one that is, though it may change which. So check the certificate against your system’s roots, not a downloaded copy of today’s CA.

PlanetScale warns that if you don’t verify the certificate, your connection is open to man-in-the-middle attacks. Clients built on libmysqlclient, including the mysql command, don’t load the system roots by themselves; on macOS, point them at /etc/ssl/cert.pem.

Connect with Inlet

1. Choose New Connection, pick MySQL, and enter the host, user name, password and database from the Connect page. Or build a mysql:// URL as above and paste it; Inlet fills in the form.
2. Under TLS, choose verify-full and leave the CA file empty: Inlet checks the certificate against the certificates macOS trusts, which is what PlanetScale asks for.
3. Save the password in the Keychain, since PlanetScale can’t show it again, or have Inlet ask each time.
4. Tag the environment. A production connection opens read-only until you unlock it, for ten minutes at a time.

For a production branch, also create a password with the Read-only role and use it in Inlet. That way PlanetScale itself refuses writes, independent of the client.

Connect from the command line

With the mysql client and full verification:

mysql -h aws.connect.psdb.cloud -P 3306 -u <username> -p <database> --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem

Homebrew’s mysql-client package has the client (keg-only: /opt/homebrew/opt/mysql-client/bin/mysql).

Or let the pscale CLI handle credentials. pscale shell opens the mysql client against a branch; --role reader gives you a read-only session:

pscale shell <database> <branch> --role reader

pscale connect instead opens a secure local proxy, on 127.0.0.1:3306 by default, that other tools can connect to:

pscale connect <database> <branch> --port 3309

Troubleshooting

• ERROR 1045: Access denied: the user name and password are a pair for one branch. Check you’re using the password for this branch, and that it hasn’t been deleted (deleting a password disconnects its clients, which can take up to five minutes).
• Select command denied … or Insert command denied … (ACL check error): the password’s role doesn’t allow that. Create a password with a role that does.
• ERROR 2003: Can’t connect, or refused from a new location: the password may have IP restrictions. Check them on the Passwords page.
• Connection fails without TLS: PlanetScale requires it; turn TLS on in your client.
• DDL refused on production: the branch has safe migrations on. Make schema changes on a development branch and deploy them with a deploy request.