PlanetScale is a new hosted database provider. Where it differs from the rest though is in it's branching/merging features for migrations.
It allows developers to create branches off of the main
database schema and then apply their schema changes in isolation.
After they're applied, a deploy request can be opened, approved, and merged seamlessly. It promises to be fast, non-blocking on schema changes, and easily scalable.
Their free tier is generous and plenty to get started messing around with.
This will be a quick crash course in how to use the CLI to accomplish some of the basic tasks through a workflow.
Prereqs
Installed the PlanetScale, pscale
, CLI utility:
CLI Install Instructions
Installed the MySQL Shell:
MySQL Shell
I'll be using Linux and ZSH for reference.
Logging In
Logging into pscale
is easy, but interesting process. Start by running the auth login
command:
> pscale auth login
This will open a tab in your default browser which displays a code and a confirm
button.
Looking back at your shell you should see the confirmation code listed on the page:
Confirmation Code: XXXXXXX
If something goes wrong, copy and paste this URL into your browser: https://auth.planetscale.com/oauth/device?user_code=XXXXXXX
After verifying the code and accepting it on the page your terminal should show a Successfully logged in.
message.
Creating a Database
Starting out, you won't have any databases. The first step is to create one (I'm using thunks
as a database name, but obviously use whatever name you want):
> pscale database create thunks
Connecting to the Database
Note: The docs say we can just use pscale shell thunks
, however I get a error for a unknown option --defaults-extra-file
, so we'll be doing it manually-ish.
Now that we have a database, let's connect to it and take a look at what we have. In your terminal create the tunnel to your database:
> pscale connect thunks
Secure connection to database thunks and branch main is established!.
Local address to connect your application: 127.0.0.1:3306 (press ctrl-c to quit)
This will give you a local address, default: 127.0.0.1
, and the port, default: 3306
. Use these to create your connection using the mysqlsh
shell. You can omit the port if it's the default and when prompted for a password hit enter
without entering one. You'll need to do this in a different shell instance as the connection process is blocking:
> mysqlsh --sql -uroot -h127.0.0.1
Taking a look at what we have for databases:
> show databases;
+--------------------+
| Database |
+--------------------+
| thunks |
| information_schema |
| mysql |
| sys |
| performance_schema |
+--------------------+
5 rows in set (0.0279 sec)
We see our new database thunks
listed. It should be empty though:
> show tables;
Empty set (0.0245 sec)
Just as we expected.
Branches
A empty database isn't of much use, so let's create a new branch to start a migration on.
PlanetScale uses branches much like git
. So, we can create a new branch, perform our changes, and then ask the maintainer to merge/deploy those changes in. This is one of the most interesting features of PlanetScale. It allows changes to occur in isolation and deploys to be rolled out seamlessly.
By default a database is created with a branch of main
.
To create a new branch we want to run the branch
command with the desired name. We'll start by adding a users table so we can get some people into our data set:
> pscale branch create thunks add-users-table
Then check that it was successfully created:
> pscale branch list thunks
NAME STATUS PARENT BRANCH CREATED AT UPDATED AT NOTES
----------------- -------- --------------- ---------------- ---------------- -------
main n/a 14 minutes ago 13 minutes ago
add-users-table main 1 minute ago 47 seconds ago
Making Changes
The connection we created earlier was to our main
branch of the database, but the changes we want to make will be on add-users-table
. Close the mysqlsh
session and kill the connection process.
Now, reconnect using the our new branch:
> pscale connect thunks add-users-table
Secure connection to database thunks and branch add-users-table is established!.
Local address to connect your application: 127.0.0.1:3306 (press ctrl-c to quit)
Reconnect the MySQL Shell the same way as before:
> mysqlsh --sql --uroot -h127.0.0.1
Now we can make our changes:
> CREATE TABLE users (
login VARCHAR(50),
name VARCHAR(50)
);
> describe users;
+-------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+-------------+------+-----+---------+-------+
| login | varchar(50) | YES | | NULL | |
| name | varchar(50) | YES | | NULL | |
+-------+-------------+------+-----+---------+-------+
2 rows in set (0.0183 sec)
We have made the changes on our branch. Let's verify that these haven't been propagated to our main
branch yet. Do the disconnect/reconnect dance and select the main
branch. Then check the tables in the database:
> show tables;
Empty set (0.0247 sec)
Perfect.
Deploy Requests
Now that the changes we want are on our own branch, we need to create a deploy request to get them merged into the main
branch. This is very similar to a PR/MR in GitHub or GitLab.
We do this by running the deploy-request
command with the database name and the branch we want merged in:
> pscale deploy-request create thunks add-users-table
Then we're able to list the deploy requests that are pending:
> pscale deploy-request list thunks
ID NUMBER BRANCH INTO BRANCH APPROVED STATE DEPLOY STATE DEPLOYABLE QUEUED AT STARTED AT FINISHED AT CREATED AT UPDATED AT CLOSED AT
-------------- -------- ----------------- ------------- ---------- ------- -------------- ------------ -------------- -------------- ------------- ------------ ------------ -----------
zdsty5vxjfin 1 add-users-table main No open ready Yes 1 minute ago 1 minute ago
Just like a PR/MR, we'll need approval before we can deploy our changes to main
. This uses the number
listed above as the identifier:
> pscale deploy-request review --approve thunks 1
Deploy request thunks/1 is approved.
Deploying Changes
Now that our changes have been approved, we can deploy them out to main and get out database migrated:
> pscale deploy-request deploy thunks 1
Successfully deployed zdsty5vxjfin from add-users-table to main.
We should verify that our changes have been made before cleaning up. Connect to the main branch and open up a MySQL Shell then check the schema:
> describe users;
+-------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+-------------+------+-----+---------+-------+
| login | varchar(50) | YES | | NULL | |
| name | varchar(50) | YES | | NULL | |
+-------+-------------+------+-----+---------+-------+
2 rows in set (0.0213 sec)
Great, our changes are there on main. Now for some finishing tasks.
Let's start out by closing the deploy request:
> pscale deploy-request close thunks 1
Deploy request thunks/1 was successfully closed.
Now we can delete the branch:
> pscale branch delete thunks add-users-table
? Please type thunks/add-users-table to confirm: thunks/add-users-table
Branch add-users-table was successfully deleted from thunks.
We've migrated our database and cleaned up the request and branch.
Conclusion
PlanetScale is definitely cool. It brings the very familiar feel of branching, request, and merging to live databases.
It promises to be fast, non-blocking on schema changes, and easily scalable.
I do wish the CLI documentation was better. It's pretty sparse after the top-level commands, so the help
messages will be your friend.
Now that I've gotten local the local development and CLI down, I'm excited to give it a go with a app and deployment.
Top comments (0)