build-a-ruby-app-with-cockroachdb-activerecord.md

title	summary	toc	twitter
Build a Ruby App with CockroachDB and ActiveRecord	Learn how to use CockroachDB from a simple Ruby application with the ActiveRecord ORM.	true	false

Use pg Use ActiveRecord

This tutorial shows you how build a simple Ruby application with CockroachDB and the ActiveRecord ORM.

We have tested the ActiveRecord ORM enough to claim beta-level support in CockroachDB v19.2. If you encounter problems, please open an issue with details to help us make progress toward full support.

{{site.data.alerts.callout_success}} For a more realistic use of ActiveRecord with CockroachDB, see our examples-orms repository. {{site.data.alerts.end}}

Before you begin

{% include {{page.version.version}}/app/before-you-begin.md %}

Step 1. Install the ActiveRecord ORM

To install ActiveRecord as well as the pg driver and a CockroachDB Ruby package that accounts for some minor differences between CockroachDB and PostgreSQL, run the following command:

{% include copy-clipboard.html %}

$ gem install activerecord pg activerecord-cockroachdb-adapter

{{site.data.alerts.callout_info}} The exact command above will vary depending on the desired version of ActiveRecord. Specifically, version 4.2.x of ActiveRecord requires version 0.1.x of the adapter; version 5.1.x of ActiveRecord requires version 0.2.x of the adapter; version 5.2.x of ActiveRecord requires version 5.2.x of the adapter. {{site.data.alerts.end}}

Step 2. Create the maxroach user and bank database

{% include {{page.version.version}}/app/create-maxroach-user-and-bank-database.md %}

Step 3. Generate a certificate for the maxroach user

Create a certificate and key for the maxroach user by running the following command. The code samples will run as this user.

{% include copy-clipboard.html %}

$ cockroach cert create-client maxroach --certs-dir=certs --ca-key=my-safe-directory/ca.key

Step 4. Run the Ruby code

The following code uses the ActiveRecord ORM to map Ruby-specific objects to SQL operations. Specifically, Schema.new.change() creates an accounts table based on the Account model (or drops and recreates the table if it already exists), Account.create() inserts rows into the table, and Account.all selects from the table so that balances can be printed.

Copy the code or download it directly.

{% include copy-clipboard.html %}

{% include {{page.version.version}}/app/activerecord-basic-sample.rb %}

Then run the code:

{% include copy-clipboard.html %}

$ ruby activerecord-basic-sample.rb

The output should be:

-- create_table(:accounts, {:force=>true})
   -> 0.0361s
1 1000
2 250

To verify that the table and rows were created successfully, start the built-in SQL client:

{% include copy-clipboard.html %}

$ cockroach sql --certs-dir=certs --database=bank

Then, issue the following statement:

{% include copy-clipboard.html %}

> SELECT id, balance FROM accounts;

+----+---------+
| id | balance |
+----+---------+
|  1 |    1000 |
|  2 |     250 |
+----+---------+
(2 rows)

Step 2. Create the maxroach user and bank database

{% include {{page.version.version}}/app/insecure/create-maxroach-user-and-bank-database.md %}

Step 3. Run the Ruby code

The following code uses the ActiveRecord ORM to map Ruby-specific objects to SQL operations. Specifically, Schema.new.change() creates an accounts table based on the Account model (or drops and recreates the table if it already exists), Account.create() inserts rows into the table, and Account.all selects from the table so that balances can be printed.

Copy the code or download it directly.

{% include copy-clipboard.html %}

{% include {{page.version.version}}/app/insecure/activerecord-basic-sample.rb %}

Then run the code:

{% include copy-clipboard.html %}

$ ruby activerecord-basic-sample.rb

The output should be:

-- create_table(:accounts, {:force=>true})
   -> 0.0361s
1 1000
2 250

To verify that the table and rows were created successfully, start the built-in SQL client:

{% include copy-clipboard.html %}

$ cockroach sql --insecure --database=bank

Then, issue the following statement:

{% include copy-clipboard.html %}

> SELECT id, balance FROM accounts;

+----+---------+
| id | balance |
+----+---------+
|  1 |    1000 |
|  2 |     250 |
+----+---------+
(2 rows)

What's next?

Read more about using the ActiveRecord ORM, or check out a more realistic implementation of ActiveRecord with CockroachDB in our examples-orms repository.

{% include {{page.version.version}}/app/see-also-links.md %}