Introduction
In this tutorial, you’re going to create a simple Rails application named blog and connect it to a PlanetScale database. You’ll perform the initial migration from your local Rails application, and set up the database for future development.
Prerequisites
- Install Ruby and the Rails gem.
- Install the PlanetScale CLI.
- Authenticate the CLI with the following command:
pscale auth login
Create a Rails project
To connect a Rails application to a PlanetScale database, you'll first create a sample Rails project named blog and install the libraries needed to connect to your PlanetScale database.
Open the command line and follow these steps:
Create a Rails app named blog by running the following command:
rails new blog
Change into the directory you just created, the
blog
Rails app:cd blog
Next, add the
mysql2
gem to your Gemfile:gem "mysql2"
Then run
bundle install
At this point, you have accomplished two things: you've created a Rails project called blog and installed the libraries that you'll need to connect to your PlanetScale database. Now, it’s time to create a PlanetScale database.
Create a PlanetScale database and password
Note: You can also create passwords in the PlanetScale dashboard, as documented in our Creating a password documentation.
Using the CLI to create a connection string
Using the
pscale
CLI, create a new database also named blog:pscale database create blog
Using the
pscale
CLI, create a new database password for themain
branch of your database named blog:pscale password create blog main <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 to you, as they will not be shown again.
NAME BRANCH USERNAME ACCESS HOST URL ROLE ROLE DESCRIPTION PASSWORD --------------------- -------- -------------- ----------------------------------- -------- ------------------ ------------------------------------------------------- development-password main xxxxxxxx xxxxxxxxxx.us-east-3.psdb.cloud writer Can Read & Write pscale_pw_xxxxxxxxxxxxxxxxxxxxx
Configure Rails and PlanetScale
Let's set up the Rails application to talk to the new database.
Open config/database.yml
and configure the development
database settings with your new credentials from the output in the previous step:
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, you can also enable Automatic Rails migrations from the database's settings page. Select your database, click on the main
branch, click "Settings", check the "Automatically copy migration data" box, and select "Rails" from the dropdown.
Migrate your database
Here comes the fun stuff! Now that your application is configured to talk to PlanetScale, you can create your first migration.
Create a Rails migration and call it
CreateUsers
:rails generate migration CreateUsers
This rails command begins the migration for your table that is currently empty and generates a Ruby file that’ll be named something like this:
db/migrate/20211014210422_create_users.rb
Fill in the body of this skeleton file with a few more relevant details, such as a user's name and email.
class CreateUsers < ActiveRecord::Migration[6.1] def change create_table :users do |t| t.string :name t.string :email t.timestamps end end end
Run your migration:
bin/rails db:migrate
Now, give it a whirl to make sure you can query the new table with the
pscale
CLI:pscale shell blog main
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 | | +------------+--------------+------+-----+---------+----------------+
Promote your main branch to a production branch
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.
pscale branch promote blog main
Congratulations! You're ready to develop your Rails application against PlanetScale.
Summary
In this tutorial, you created a simple Rails application named blog and connected it to a PlanetScale database.
Further reading
If you're interested in learning how to secure your application's connection to PlanetScale, please read Connecting to PlanetScale securely.
What's next?
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.