# Source: https://planetscale.com/docs/vitess/tutorials/connect-rails-app.md

# Connect a Rails application to PlanetScale

## 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.

<Tip>
  Already have a Rails application and just want to connect to PlanetScale? Check out the [Rails quick connect repo](https://github.com/planetscale/connection-examples/tree/main/ruby).
</Tip>

## Prerequisites

* Install [Ruby and the Rails gem](https://guides.rubyonrails.org/getting_started.html#creating-a-new-rails-project-installing-rails).
* Install the [PlanetScale CLI](https://github.com/planetscale/cli).
* Authenticate the CLI with the following command:

```bash  theme={null}
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:

<Steps>
  <Step>
    Create a Rails app named *blog* by running the following command:

    ```bash  theme={null}
    rails new blog
    ```
  </Step>

  <Step>
    Change into the directory you just created, the `blog` Rails app:

    ```bash  theme={null}
    cd blog
    ```
  </Step>

  <Step>
    Next, add the `trilogy` gem to your *Gemfile*:

    ```ruby  theme={null}
    gem "trilogy"
    ```
  </Step>

  <Step>
    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.
  </Step>
</Steps>

## Create a PlanetScale database and password

Now you'll need to create credentials for your Rails application to use.

### Using the CLI to create a connection string

<Steps>
  <Step>
    Using the `pscale` CLI, create a new database also named *blog*:

    ```bash  theme={null}
    pscale database create blog
    ```
  </Step>

  <Step>
    Using the `pscale` CLI, create a new database password for the `main` branch of your database named *blog*:

    ```bash  theme={null}
    pscale password create blog main <PASSWORD_NAME>
    ```

    <Note>
      The `PASSWORD_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 dashboard page, click "Settings", and then click "Passwords".
    </Note>
  </Step>

  <Step>
    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
    ```
  </Step>
</Steps>

<Note>
  You can also create passwords in the PlanetScale dashboard, as documented [in our Creating a password documentation](/docs/vitess/connecting/connection-strings#creating-a-password).
</Note>

## 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:

```yaml  theme={null}
development:
  <<: *default
  adapter: trilogy
  database: blog
  username: <USERNAME>
  host: <ACCESS HOST URL>
  password: <PASSWORD>
  ssl_mode: <%= Trilogy::SSL_VERIFY_IDENTITY %>
```

For `database` (database name), you can use your PlanetScale database name directly if you have a *single unsharded keyspace*. If you have a sharded keyspace, you'll need to use `@primary`. This will automatically direct incoming queries to the correct keyspace/shard. For more information, see the [Targeting the correct keyspace documentation](/docs/vitess/sharding/targeting-correct-keyspace).

The correct `sslca` path depends on your operating system and distribution. See [CA root configuration](/docs/vitess/connecting/secure-connections#ca-root-configuration) for more information.

<Note>
  You're configuring the **development** Rails environment here for the sake of expedience. In actual use, the **main** database branch would typically serve the **production** environment.
</Note>

Because this is a Rails app, you can also enable [Automatic Rails migrations](/docs/vitess/tutorials/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.

<Steps>
  <Step>
    Create a Rails migration and call it `CreateUsers`:

    ```bash  theme={null}
    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**.

    ```ruby  theme={null}
    class CreateUsers < ActiveRecord::Migration[6.1]
      def change
        create_table :users do |t|
          t.string :name
          t.string :email
          t.timestamps
        end
      end
    end
    ```
  </Step>

  <Step>
    Run your migration:

    ```bash  theme={null}
    bin/rails db:migrate
    ```
  </Step>

  <Step>
    Now, give it a whirl to make sure you can query the new table with the `pscale` CLI:

    ```bash  theme={null}
    pscale shell blog main
    ```

    ```sql expandable theme={null}
    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    |                |
    +------------+--------------+------+-----+---------+----------------+
    ```
  </Step>
</Steps>

## Enable safe migrations

[Safe migrations](/docs/vitess/schema-changes/safe-migrations) is an optional but highly recommended feature for branches on PlanetScale. With safe migrations enabled, 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](/docs/vitess/best-practices).

```bash  theme={null}
pscale branch safe-migrations enable 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](/docs/vitess/connecting/secure-connections).

## 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](/docs/vitess/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](/docs/vitess/tutorials/automatic-rails-migrations).

## Need help?

Get help from [the PlanetScale Support team](https://support.planetscale.com/), or join our [GitHub discussion board](https://github.com/planetscale/discussion/discussions) to see how others are using PlanetScale.


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://planetscale.com/llms.txt