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
If you already have your PlanetScale database set up, you may find the Connecting your application or Branching guides more helpful.
This guide is split up so that you can either follow it in the PlanetScale dashboard or using the PlanetScale CLI.
Getting started — PlanetScale dashboard
You'll need a PlanetScale account to complete this guide.
Create a database
Follow these steps to create a database:
- Click the "Create a database" button on your organization's overview page.
- Name your database using lowercase, alphanumeric characters or underscores. You may also use dashes, but we don't recommend that, as sharded databases require them to be escaped.
- 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.
Your database is created with an initial development branch, main
, which you will use to apply a schema change and insert data. Think of this as your development environment where you can test schema changes before deploying your database to production. Once you promote your branch to production, you can always create new branches (isolated copies of the production schema) off of production to use for development.
Add a schema to your database
This quickstart demonstrates how to create and use two relational tables: categories
and products
.
From your database's overview page, click on the "Console" tab in the database navigation. This will open up a web console connected to your database branch.
By default the
main
branch is preselected. Click "Connect".Create the
categories
andproducts
tables by running the following commands in the web console:CREATE TABLE categories ( id int NOT NULL AUTO_INCREMENT PRIMARY KEY, name varchar(255) NOT NULL );
CREATE TABLE products ( id int NOT NULL AUTO_INCREMENT PRIMARY KEY, name varchar(255) NOT NULL, image_url varchar(255), category_id INT, KEY category_id_idx (category_id) );
NotePlanetScale does not support foreign key constraints, but we do support the use of relationships with foreign keys, as shown in this example. For more information, check out our Operating without foreign key constraints documentation.You can confirm that the tables have been added by running:
SHOW TABLES;
Insert data into your database
Now that you have created your tables, let's insert some data. Run the following commands to add a product and category to your tables:
INSERT INTO categories (name)
VALUES ('Office supplies');
INSERT INTO products (name, image_url, category_id)
VALUES ('Ballpoint pen', 'https://example.com/500x500', '1');
You can confirm the data has been added with:
SELECT * FROM products;
SELECT * FROM categories;
If you click on the "Schema" tab in the database navigation and click the "Refresh schema" button, you'll see the new database schema.
Promote your database branch to production
All of the work you've done so far has been on a development branch, main
, that was automatically created when you created the database.
Once you are happy with the changes you have made to your development branch, you can promote the branch to 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.
To promote a branch to production:
Click "Overview" in the navigation, and you'll see a banner with information about promoting to production.
Click the "Promote branch" button.
In the modal that opens, select the branch you want to promote to production
Click "Promote branch"
The main
branch is now your production branch. It contains the categories
and products
tables you created, along with the data you inserted. In addition, a production branch 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, one of our language-specific guides, or head straight to our Connection Strings documentation for more information about creating connection strings.
When you want to continue development on your database:
- Create a new branch off of your production branch
- Go through the same process described in this doc to make schema changes
- Create a deploy request to merge the changes into your production branch
Getting started — PlanetScale CLI
Make sure you first have downloaded and installed the PlanetScale CLI.
You will also need a PlanetScale account. You can sign up for a free PlanetScale account here or run pscale signup
to create an account straight from the CLI.
Sign in to your account
To authenticate with the PlanetScale CLI, enter the following:
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
Run the following command to create a database:
pscale database create <DATABASE_NAME> --region <REGION_SLUG>
- DATABASE_NAME — Your database name can contain lowercase, alphanumeric characters, or underscores. We allow dashes, but don't recommend them, as they may need to be escaped in some instances.
- REGION_SLUG — 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.
Your database will deploy with an initial development branch, main
, which you will use to apply a schema change and insert data. Think of this as your development environment where you can test schema changes before deploying your database to production. Once you promote your branch to production, you can always create new branches (isolated copies of the production schema) off of production to use for development.
Add a schema to your database
To add a schema to your database, you will need to connect to MySQL, so make sure you mysql-client
installed.
Run the following command:
pscale shell <DATABASE_NAME> main
You are now connected to your
main
branch and can run MySQL queries against it.Create the
categories
andproducts
tables by running the following:CREATE TABLE categories ( id int NOT NULL AUTO_INCREMENT PRIMARY KEY, name varchar(255) NOT NULL );
CREATE TABLE products ( id int NOT NULL AUTO_INCREMENT PRIMARY KEY, name varchar(255) NOT NULL, image_url varchar(255), category_id INT, KEY category_id_idx (category_id) );
NotePlanetScale does not support foreign key constraints, but we do support the use of relationships with foreign keys, as shown in this example. For more information, check out our Operating without foreign key constraints documentation.You can confirm that the table has been added by running:
SHOW TABLES;
To see the table schemas, run:
DESCRIBE categories;
DESCRIBE products;
Insert data into your database
Now that you have your schema set up, let's insert some data.
Run the following commands to add one entry to each table:
INSERT INTO `categories` (name) VALUES ('Office supplies');
INSERT INTO `products` (name, image_url, category_id) VALUES ('Ballpoint pen', 'https://example.com/500x500', '1');
You can confirm the data has been added with:
SELECT * FROM products;
SELECT * FROM categories;
Exit the shell by typing
exit
.
Promote your database branch to production
All of the work you've done so far has been on a development branch, main
, that was automatically created when you created the database.
Once you are happy with the changes you have made to your development branch, you can promote the branch to 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.
To promote your branch to production, run:
pscale branch promote <DATABASE_NAME> main
The main
branch is now your production branch. It contains the categories
and products
tables you created, along with the data you inserted. In addition, a production branch 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, one of our language-specific guides, or head straight to our Connection Strings documentation for more information about creating connection strings.
When you want to continue development on your database:
- Create a new branch off of your production branch
- Go through the same process described in this doc to make schema changes
- Create a deploy request to merge the changes into your production branch