Skip to content

PlanetScale quick start guide

Get started with PlanetScale in just a few minutes

Overview

The following guide will show you how to:

  • Create a database with PlanetScale
  • Make a schema change
  • Insert data
  • Promote your database branch to production

This guide is split up so that you can either follow it in the PlanetScale application dashboard or using the PlanetScale CLI.

Quick start with the PlanetScale application

Create an account

To complete this guide, you will need to sign up for a PlanetScale account.

You can sign up for a free account using an email address or your GitHub account.

Create a database

To create your first database, follow these steps:

  • Click the "Create a database" button on your organization's overview page.
  • Name your database using lowercase, alphanumeric characters. You may also use dashes or underscores.
  • Select a region. For the lowest latency, select a region near you or your application's hosting location.
  • Finally, click the "Create database" button to deploy your database.

Create database modalCreate database modal

Your database will be created with an initial development branch, main, which you will use to apply a schema change and insert data.

Add a schema to your database

From your new database's overview page, click on the "Branches" tab in the database navigation. This will bring you to the branch page for your database.

Create database modalCreate database modal

Click on the main branch. This will take you to the branch page for your main branch.

Click on the "Console" tab in the branch navigation. This will open up a web console connected to your database branch.

Create a table by running the following command:

Copied
CREATE TABLE `users` (
`id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
`email` varchar(255) NOT NULL,
`first_name` varchar(255),
`last_name` varchar(255)
);

You can confirm that the table has been added by running the following command:

Copied
SHOW TABLES;

Insert data into your database

Now that you have created a users table, you can insert data into that table.

Run the following command to add a user to your table.

Copied
INSERT INTO `users` (id, email, first_name, last_name)
VALUES (1, 'hp@test.com', 'Harry', 'Potter');

Run the following command to confirm the user has been added to the table:

Copied
SELECT * FROM users;

You can see the schema by running:

Copied
DESCRIBE users;

If you click on the "Schema" tab in the database navigation and click the "Refresh schema" button, you'll see the new users table that you just created.

Promote your database branch to production

When you created your PlanetScale database, a development branch named main was automatically created.

A development branch is intended for applying schema changes and is not intended for use in production.

A production branch is a highly available, protected database branch with automated scheduled backups designed for use in production. Schema changes, such as CREATE, ALTER, and DELETE, are not allowed on production branches to prevent accidental data loss.

Once you are happy with the changes you have made to your development branch, you can promote it to a production branch.

To promote a branch to production:

  • Click "Overview" in the navigation and you'll see a banner with information about promoting to production.

Create database modalCreate database modal

  • Click the "Promote branch" button.
  • In the modal that opens, select the branch you want to promote to production
  • Finally, click "Promote branch"

You have now successfully promoted your development branch to production, which provides:

  • Protection from direct schema changes
  • High availability
  • Automatic daily scheduled backups

What's next?

Now that you've created a database, applied schema changes, added data, and promoted your branch to production, it's time to connect to your application.

You can use our Connect Any Application tutorial for a general step-by-step approach, or head straight to our Connection Strings documentation for more information about creating connection strings.

Quick start with the PlanetScale CLI

Download and install the PlanetScale CLI

First, download and install the PlanetScale CLI.

Create an account

You will also need a PlanetScale account. You can sign up for a free PlanetScale account here or follow the steps below to create an account straight from the CLI.

To sign up for a new account, run the following command in your terminal:

Copied
pscale signup

You'll be prompted to enter your email address, create a new password, and confirm your password. To finalize registration, click on the confirmation link that was sent to your email.

PlanetScale account signup through CLIPlanetScale account signup through CLI

Sign in to your account

To sign in to your new PlanetScale account, enter the following:

Copied
pscale auth login

You'll be taken to a screen in the browser where you'll be asked to confirm the code displayed in your terminal. If the confirmation codes match, click the "Confirm code" button in your browser.

You should receive the message "Successfully logged in" in your terminal. You can now close the confirmation page in the browser and proceed in the terminal.

Create a database

Now that you have signed into PlanetScale using the CLI, you can create a database.

Issue the following command to create a database:

Copied
pscale database create databasename --region regionslug
  • databasename The name of your database must use lowercase, alphanumeric characters with dashes and underscores only.
  • regionslug For the lowest latency, choose the region closest to you or your application's hosting location. You can find our regions and their slugs on the Regions page.
If you do not specify a region, your database will automatically be deployed to US East - Northern Virginia.

Your database will deploy with an initial development branch, main, which you will use to apply a schema change and insert data.

Add a schema to your database

To add a schema to your database, you will need to connect to MySQL using the pscale shell.

Run the following command:

Copied
pscale shell databasename main

You are now connected to your main branch and can run MySQL queries against it.

Create a table by running the following command:

Copied
CREATE TABLE `users` (
`id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
`email` varchar(255) NOT NULL,
`first_name` varchar(255),
`last_name` varchar(255)
);

You can confirm that the table has been added by running the following command:

Copied
SHOW TABLES;

To see the users table schema, run the following:

Copied
DESCRIBE users;

PlanetScale CLI - MySQL shellPlanetScale CLI - MySQL shell

Insert data into your database

Now that you have created a users table, you can insert data into that table.

Run the following command to add a user to your table.

Copied
INSERT INTO `users` (id, email, first_name, last_name)
VALUES (1, 'hp@test.com', 'Harry', 'Potter');

Run the following command to confirm the user has been added to the table:

Copied
SELECT * FROM users;

Exit the shell by typing exit.

Promote your database branch to production

When you created your PlanetScale database, a development branch named main was automatically created. A development branch is intended for applying schema changes and is not intended for use in production.

A production branch is a highly available, protected database branch with automated scheduled backups designed for use in production. Schema changes, like CREATE, ALTER, and DELETE, are not allowed on production branches to prevent accidental data loss.

Once you are happy with the changes you have made to your initial development branch, ‘main’, you can promote it to a production branch by running the following:

Copied
pscale branch promote databasename main

You should get the following response: "Branch main in databasename was successfully promoted."

You have now successfully promoted your main branch to production, which provides:

  • Protection from direct schema changes
  • High availability
  • Automatic daily scheduled backups

What's next?

Now that you've created a database, applied schema changes, added data, and promoted your branch to production, it's time to connect to your application.

You can use our Connect Any Application tutorial for a general step-by-step approach, or head straight to our Connection Strings documentation for more information about creating connection strings.

Was this page useful?
Last updated on October 22, 2021
Help us improve this page
PrivacyTerms© 2021 PlanetScale Inc.