Introduction
In this tutorial, you'll learn how to connect any application to your PlanetScale database.
If you're just getting started and still need to set up a database, we recommend starting with the PlanetScale quick start guide first. We also have language/framework-specific guides under "Integration guides" if you prefer a more detailed walk-through.
PlanetScale uses database branches to create a development-friendly workflow. Your database is initially created with a default branch, main
, which is meant to serve as a development branch before promoting it to production.
While developing your application, you'll need to connect to a development branch. Your production application, however, should be connected to your production database branch. Check out our Branching guide for more information about the branching workflow.
There are two ways to connect your app to PlanetScale. Both are covered below.
Option 1: Connect with username and password (Recommended)
This section will show you how to create a username and password for your branch and use those credentials to connect to your database. This is the recommended way to connect.
There are two ways to generate a new username and password for your branch:
- In the PlanetScale dashboard
- With the PlanetScale CLI
Generate credentials in the PlanetScale dashboard
Click on the branch you want to connect to.
Click "Connect".
Select the applicable language from the "Connect with" dropdown or choose "General".
If the password isn't visible, click "New password".
Copy the credentials.
Paste them in your application's MySQL configuration file (often just a
.env
file). The layout and name of this file will vary depending on the application language, but it may look something like this:DATABASE=<DATABASE_NAME> USERNAME=<USERNAME> HOST=<HOST_NAME> PASSWORD=<PASSWORD> SSL= // more information about this in next step
Check out our language integration guides in the side navigation for more explicit instructions.
To ensure a secure connection, you must validate the server-side certificate from PlanetScale. This configuration depends on your application, but often it just means adding a line to your
.env
file similar to this:MYSQL_ATTR_SSL_CA=/etc/ssl/cert.pem
The path to the certificate depends on your system. The above example shows the path for macOS, but you can find others in our Secure connections documentation.
Again, the variable name here,
MYSQL_ATTR_SSL_CA
, is just an example. The actual name and location for it will depend on the application.If you're unsure what to put here, we recommend selecting your application's language from the dropdown in the PlanetScale dashboard (see step 3 above) and copying the credentials from there. This includes the necessary SSL configuration variables and shows what files they belong in. Additionally, we show you the correct certificate path by default based on your system.
Generate credentials in the PlanetScale CLI
If you prefer working from the CLI, you can quickly spin up new credentials there. Make sure you have the CLI set up first.
Run the following command in the CLI to create a new username and password for your branch.
pscale password create <DATABASE_NAME> <BRANCH_NAME> <PASSWORD_NAME>
NoteThePASSWORD_NAME
value represents the name of the username and password being generated. You can have multiple credentials for a branch, so this gives you a way to categorize them. To manage your passwords in the dashboard, go to your database overview page, click "Settings", and then click "Passwords".Take note of the values returned. You won't be able to see this password again.
Password production-password was successfully created. Please save the values below as they will not be shown again. NAME USERNAME ACCESS HOST URL ROLE PASSWORD --------------------- ------------- --------------------------------- ------------------ -------------------------------- production-password xxxxxxxxxx xxxxxxxxxx.us-east-2.psdb.cloud Can Read & Write pscale_pw_xxxxxx_xxxxxxxxxxxxx
Paste the values from the console output into your application's MySQL configuration file. The layout and name of this file will vary depending on the application language, but it may look something like this:
DATABASE=<DATABASE_NAME> USERNAME=<USERNAME> HOST=<ACCESS HOST URL> PASSWORD=<PASSWORD> SSL= // This is covered in the next step
To ensure a secure connection, you must validate the server-side certificate from PlanetScale. This configuration depends on your application, but often it just means adding a line to your
.env
file similar to this:MYSQL_ATTR_SSL_CA=/etc/ssl/cert.pem
The path to the certificate depends on your system. The above example shows the path for macOS, but you can find others in our Secure connections documentation.
Again, the variable name here,
MYSQL_ATTR_SSL_CA
, is just an example. The actual name and location for it will depend on the application.If you're unsure what to put here, we recommend selecting your application's language from the dropdown in the PlanetScale dashboard (see step 3 from the previous section) and copying the credentials from there. This includes the necessary SSL configuration variables and shows what files they belong in. Additionally, we show you the correct certificate path by default based on your system.
Option 2: Connect using the PlanetScale proxy
Another way to connect your application to your PlanetScale database during development is using the PlanetScale proxy. You won't have to fiddle with configuring any credential details, as that's handled by PlanetScale. It's as simple as a single CLI command.
You'll use the CLI to establish a secure connection to PlanetScale. It will listen on a local port that your application can connect to. The main benefit of this method is you won't have to generate and remember multiple passwords every time you're creating or switching to a new branch.
Make sure you have the CLI set up, and then run the following command:
pscale connect <DATABASE_NAME> <BRANCH_NAME>
This establishes a secure connection and opens a port on your local machine that you can use to connect to any MySQL client.
Take note of the address it returns to you. By default it is
127.0.0.1:3306
. The CLI will use a different port if3306
is unavailable.In your application's MySQL configuration file, use the following to connect:
DATABASE=<DATABASE_NAME> HOST=127.0.0.1 PORT=3306 // use the value that was returned in the console
Your application should now be connected to the specified PlanetScale database branch!
What's next?
Once your application is connected to a development database branch, you can make schema changes in an isolated development environment without worrying about affecting production. Additionally, the PlanetScale workflow allows you to make non-blocking schema changes without locking or causing downtime for production databases.
PlanetScale workflow
Here's the general workflow that you'll go through to get schema changes from development to production:
- Follow this guide to connect to a development branch.
- Modify your schema as needed.
- Test them locally or in your staging environment.
- Once satisfied and ready to deploy your changes to production, create a deploy request.
- You or your team can review and approve the schema changes.
- Deploy your deploy request to production.
- Bonus: If you realize you made a mistake, you can click "Revert changes" to undo a schema change.
Note: you must already have a production branch in place to create a deploy request.