In this tutorial, we’re going to create a simple Rails application named blog and connect it to a PlanetScale database. We’ll perform the initial migration from our local Rails application, and set up the database for future development.

• Install Ruby and the Rails gem.
• Install the PlanetScale CLI.
• Authenticate the CLI with the following command:

Copied
pscale auth login

To connect a Rails application to a PlanetScale database, we start by creating a sample Rails project named blog and installing the libraries we'll need to connect to our PlanetScale database.

Open the command line and follow these steps:

1. Create a Rails app named blog by running the following command:

Copied
rails new blog

2. Change into the directory you just created, the blog Rails app:

Copied
cd blog

3. Next, add the mysql2 gem to your Gemfile:

Copied
gem "mysql2"

4. Then run bundle install

At this point, we have accomplished two things: we've created a Rails project called blog and installed the libraries that we'll need to connect to our PlanetScale database. Now it’s time to create a PlanetScale database.

You can also create passwords in the PlanetScale application as documented here.

1. Using the pscale CLI, create a new database also named blog:

Copied
pscale database create blog

2. Using the pscale CLI, create a new database password for the main branch of your database named blog:

Copied
pscale password create blog main development-password

3. Take note of the values it returns to you.

Copied
Please save the values below as they will not be shown again
  NAME                  BRANCH   USERNAME       ACCESS HOST URL                     ROLE     ROLE DESCRIPTION   PASSWORD
 --------------------- -------- -------------- ----------------------------------- -------- ------------------ -------------------------------------------------------
  development-password  main     c8ys5g3bbcdk   0ie08slztxki.us-east-3.psdb.cloud   writer   Can Read & Write   pscale_pw_wpSDL94q7HfBGa99Fev45tTjI5bqUxcqFKqAdUw3lFc

Let's set up our Rails application to talk to the new database.

1. Open config/database.yml and configure the development database settings with your new credentials:

Copied
development:
  <<: *default
  adapter: mysql2
  database: blog
  username: <USERNAME>
  host: <ACCESS HOST URL>
  password: <PASSWORD>
  ssl_mode: :verify_identity
  sslca: "/etc/ssl/cert.pem"

The correct sslca path depends on your operating system and distribution. See CA root configuration for more information.

Because this is a Rails app, we can also enable Automatic Rails migrations from the database's settings page.

Here comes the fun stuff! Now that your application is configured to talk to PlanetScale, we can create our first migration.

1. Create a Rails migration and call it CreateUsers:

Copied
rails generate migration CreateUsers

This rails command begins the migration for our table that is currently empty and generates a Ruby file that’ll be named something like this: db/migrate/20211014210422_create_users.rb

2. We can fill in the body of this skeleton file with a few more relevant details, such as a user's name and email.

Copied
class CreateUsers < ActiveRecord::Migration[6.1]
  def change
    create_table :users do |t|
      t.string :name
      t.string :email
      t.timestamps
    end
  end
end

3. Now let's run our migration:

Copied
bin/rails db:migrate

4. Now give it a whirl to make sure we can query the new table with our pscale CLI:

Copied
pscale shell blog main

Copied
blog/main> show tables;
+----------------------+
| Tables_in_blog       |
+----------------------+
| ar_internal_metadata |
| schema_migrations    |
| users                |
+----------------------+
blog/main> describe users;
+------------+--------------+------+-----+---------+----------------+
| Field      | Type         | Null | Key | Default | Extra          |
+------------+--------------+------+-----+---------+----------------+
| id         | bigint       | NO   | PRI | NULL    | auto_increment |
| name       | varchar(255) | YES  |     | NULL    |                |
| email      | varchar(255) | YES  |     | NULL    |                |
| created_at | datetime(6)  | NO   |     | NULL    |                |
| updated_at | datetime(6)  | NO   |     | NULL    |                |
+------------+--------------+------+-----+---------+----------------+

A production branch is a highly available, protected database branch. Direct schema changes (CREATE, ALTER, and DELETE) are not allowed on production branches to prevent accidental data loss and must be applied via deploy requests.

Copied
pscale branch promote blog main

Congratulations! You're ready to develop your Rails application against PlanetScale.

In this tutorial, we created a simple Rails application named blog and connected it to a PlanetScale database.

If you're interested in learning how to secure your application's connection to PlanetScale, please read Connecting to PlanetScale securely.

Now that you've successfully connected your Rails app to PlanetScale, it's time to make more schema changes to your tables! Learn more about how PlanetScale allows you to make non-blocking schema changes to your database, or how to keep your schema_migrations table up-to-date between development and production branches with automatic schema migrations.

Get help from PlanetScale's support team, or join our GitHub Discussion board to see how others are using PlanetScale.