4.0 Upgrade Guide

Upgrading 3.x => 4.0

MRI >= 2.3 only

We've dropped support for MRI < 2.3, which obviously means that the prerequisite is to upgrade your Ruby, if you're on < 2.3.

Fix deprecation warnings

First step is to upgrade all rom gems from the previous release and fix all deprecation warnings, first upgrade these gems:

• rom 3.3.1
• rom-repository 1.4.0
• rom-sql 1.3.4

Gemfile

In 4.0 rom gem is a meta-gem which depends on latest rom-core, rom-mapper, rom-repository and rom-changeset, to upgrade tweak your Gemfile:

1. Set gem "rom", "~> 4.0"
2. Remove rom-repository
3. Remove rom-mapper
4. (optional) if you're using dry-validation, bump it to ~> 0.11.1

Inferring relations from database schema is gone

Before 4.0, relations without explicit classes or definitions in the setup DSL, would be inferred based on information in the database schema. This feature, despite being useful in some rare cases, caused a lot of confusion for many people, and in case of large schemas caused performance problems. Because of this, the feature was removed.

This means you need to define which relations you want to use via explicit relation classes or using setup DSL.

Ad-hoc combine/wrap is gone

Starting with 4.0, composing relations require associations. This means Relation#combine and Relation#wrap will only work if you have associations defined in relation classes.

# in 3.x this works
users.combine(many: { tasks: [tasks.for_users, task_id: :id] })

# in 4.x you must define an association, ie:
class Users < ROM::Relation[:sql]
  schema(infer: true) do
    associations { has_many :tasks }
  end
end

# then just:
users.combine(:tasks)

Notice that you can still provide custom query logic for associations via new :override option in association DSL.

Repositories

In repositories you no longer need to declare which relations a repo will use:

# 3.x
class UserRepo < ROM::Repository[:users]
  relations :tasks, :posts
end

# 4.x
class UserRepo < ROM::Repository[:users]
end

Changesets

Repository#changeset was removed in favor of Relation#changeset, but the method has a different signature now:

1. :create

# 3.x
user_repo.changeset(:create, name: "Jane").commit

# in 4.0
users.changeset(:create, name: "Jane").commit

2. :update

# 3.x
user_repo.changeset(:update, 1, name: "Jane").commit

# in 4.0
users.by_pk(1).changeset(:update, name: "Jane").commit

3. :delete

# 3.x
user_repo.changeset(:delete, 1).commit

# in 4.0
users.by_pk(1).changeset(:delete).commit

For more information see Changeset docs.

rom-sql 2.0

1. Command#transaction is gone, use Relation#transaction instead. See Transaction docs
2. PG::JSONArray, PG::JSONBArray, PG::JSONHash, and PG::JSONBHash types are gone, use PG::JSON and PG::JSONB instead
3. The pg_hstore extension isn't loaded automatically now, use the :extension option in configuration, to load it on demand