Use an ORM

Active Record is an Object Relational Mapping (ORM) tool for Ruby applications.

YugabyteDB YSQL API has full compatibility with Active Record ORM for data persistence in Ruby applications.

To start building your application, make sure you have met the prerequisites.

CRUD operations

This page provides details for getting started with Active Record ORM for connecting to YugabyteDB using the orm-examples repository.

This repository has a Ruby on Rails example that implements a basic REST API server. The scenario is that of an e-commerce application. Database access in this application is managed through Active Record ORM. It consists of the following.

  • The users of the e-commerce site are stored in the users table.
  • The products table contains a list of products the e-commerce site sells.
  • The orders placed by the users are populated in the orders table. An order can consist of multiple line items, each of these are inserted in the orderline table.

The source for the above application can be found in the repository. There are options that can be customized in the properties file located at config/database.yml.

Clone the orm-examples repository

$ git clone https://github.com/YugabyteDB-Samples/orm-examples.git

Build and run the application

To install the dependencies specified in your project Gemfile, do the following:

$ cd ./orm-examples/ruby/ror/

$ ./bin/bundle install

Create a database using the following command:

$ bin/rails db:create

You should see output similar to the following:

Created database 'ysql_active_record'

Perform migration to create tables and add columns using the following command:

$ bin/rails db:migrate

Start the rails server using the following command:

$ bin/rails server

Send requests to the application

Send requests to the application from another terminal as follows:

Create 2 users.

$ curl --data '{ "firstName" : "John", "lastName" : "Smith", "email" : "jsmith@example.com" }' \
   -v -X POST -H 'Content-Type:application/json' http://localhost:8080/users

$ curl --data '{ "firstName" : "Tom", "lastName" : "Stewart", "email" : "tstewart@example.com" }' \
   -v -X POST -H 'Content-Type:application/json' http://localhost:8080/users

Create 2 products.

$ curl \
  --data '{ "productName": "Notebook", "description": "200 page notebook", "price": 7.50 }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/products

$ curl \
  --data '{ "productName": "Pencil", "description": "Mechanical pencil", "price": 2.50 }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/products

Create 2 orders.

$ curl \
  --data '{ "userId": "2", "products": [ { "productId": 1, "units": 2 } ] }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/orders

$ curl \
  --data '{ "userId": "2", "products": [ { "productId": 1, "units": 2 }, { "productId": 2, "units": 4 } ] }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/orders

Query results

Using the YSQL shell

$ ./bin/ysqlsh

ysqlsh (11.2)
Type "help" for help.

yugabyte=#

Connect to the database mentioned in config/database.yml file. Default is ysql_active_record.

yugabyte=# \c ysql_active_record

ysql_active_record=# SELECT count(*) FROM users;

 count
-------
     2
(1 row)

ysql_active_record=# SELECT count(*) FROM products;

 count
-------
     2
(1 row)

ysql_active_record=# SELECT count(*) FROM orders;

 count
-------
     2
(1 row)

Using the REST API

$ curl http://localhost:8080/users

{
  "content": [
    {
      "userId": 2,
      "firstName": "Tom",
      "lastName": "Stewart",
      "email": "tstewart@example.com"
    },
    {
      "userId": 1,
      "firstName": "John",
      "lastName": "Smith",
      "email": "jsmith@example.com"
    }
  ],
  ...
}

$ curl http://localhost:8080/products

{
  "content": [
    {
      "productId": 2,
      "productName": "Pencil",
      "description": "Mechanical pencil",
      "price": 2.5
    },
    {
      "productId": 1,
      "productName": "Notebook",
      "description": "200 page notebook",
      "price": 7.5
    }
  ],
  ...
}

$ curl http://localhost:8080/orders

{
  "content": [
    {
      "orderTime": "2019-05-10T04:26:54.590+0000",
      "orderId": "999ae272-f2f4-46a1-bede-5ab765bb27fe",
      "userId": 2,
      "orderTotal": 25,
      "products": []
    },
    {
      "orderTime": "2019-05-10T04:26:48.074+0000",
      "orderId": "1598c8d4-1857-4725-a9ab-14deb089ab4e",
      "userId": 2,
      "orderTotal": 15,
      "products": []
    }
  ],
  ...
}

Learn more