Repositories » Quick Start

This documentation uses rom-sql as an example. For in-depth information see documentation for specific databases.

Creating a schema

You can quickly create a schema inside the setup block. Let's configure our SQL gateway and create a :users table:

require 'rom'

rom = ROM.container(:sql, 'sqlite::memory') do |conf|
  conf.default.create_table(:users) do
    primary_key :id
    column :name, String, null: false
    column :email, String, null: false


A Repository ("Repo") object provides a lot of conveniences for reading data with relations. Every repo can access one or more relations, depending on how you set it up.

To set up a repo to work with our :users relation simply define a class like this:

require 'rom-repository'

class UserRepo < ROM::Repository[:users]

Repositories must be instantiated with a rom container passed to the constructor, this gives access to all components within the container:

user_repo =

Let's see how Create, Update and Delete commands work with repositories.


A repo can be configured to provide access to Create commands:

require 'rom-repository'

class UserRepo < ROM::Repository[:users]
  commands :create

The commands macro defines a UserRepo#create method for us:

user_repo.create(name: "Jane", email: "")
# => #<ROM::Struct[User] id=1 name="Jane" email="">

By default, repos return simple ROM::Struct objects. You'll learn more about them in reading section.

Update and Delete

Update and Delete commands require restricting relations so that ROM knows exactly which records to modify. Provide :update and :delete with the symbol name of the method to call to get that restricted relation.

The most popular adapter, rom-sql, automatically defines a method, by_pk, that restricts by the primary key. In projects with rom-sql, we would use it to define update and delete commands in a repo:

require 'rom-repository'

class UserRepo < ROM::Repository[:users]
  commands :create, update: :by_pk, delete: :by_pk

Now we have a full CRUD setup, we can create, update and delete user data:

user = user_repo.create(name: "Jane", email: "")
# => #<ROM::Struct[User] id=1 name="Jane" email="">

# let's update the user
updated_user = user_repo.update(, name: "Jane Doe")
# => #<ROM::Struct[User] id=1 name="Jane Doe" email="">

# and now let's delete the user


Now that you know how to create tables and define repositories with full CRUD support, you can proceed to reading section.