Upgrading from 0.9.x to 1.0.0

New View DSL

In 0.9.x relation views were defined using a simple header (which was an array with symbols), but in 1.0.0 views are based on schemas:

class Users < ROM::Relation[:sql]
  schema(infer: true)

  # rom-sql 0.9.x
  view(:listing) do
    header { [:id, :name] }
    relation { order(:name) }
  end

  # rom-sql 1.0.0
  view(:listing) do
    schema { project(:id, :name) }
    relation { order(:name) }
  end

  # a list of attribute names as the second parameter works the same as in 0.9.x
  # this is the equivalent of the above:
  view(:listing, %i[id name]) do
    order(:name)
  end
end

In views schema block is executed in the context of the canonical relation schema, which means that you can use Schema API to specify a view schema in a concise way. Columns will be selected for you automatically.

All relations have schemas

Relation schemas are now inferred by default even when you don't specify it in a relation class. This means that all commands use schemas for processing input, it may happen that some of your tests will start to fail if you somehow relied on the lack of command input processing.

If you still use custom input processors, they will be called prior calling schema-based processors, ie:

class CreatePost < ROM::Commands::Create[:sql]
  relation :posts
  register_as :create
  
  # Under the hood this will happen: `Posts#schema_hash.call(CreatePost#input.call(tuple))`
  input -> tuple { tuple.merge(uuid: SecureRandom.uuid) }
end

In many cases defining custom schema types will do the trick, so there shouldn't be any need for custom command input processors. In example the same thing can be achieved with a schema:

class Posts < ROM::Relation[:sql]
  schema(infer: true) do
    attribute :uuid, Types::PG::UUID.default(&SecureRandom.method(:uuid))
  end
end

Enhanced Query DSL

There are 3 extensions in query DSL that are built on top of Sequel and provide additional features based on Schema APIs. This is a backward incompatible change as using symbols with underscores for qualifying/renaming columns no longer works.

Legacy Sequel API

If you have a lot of relations that rely on sequel-specific syntax, which means:

• qualifying or renaming columns using underscores in symbols like users__user_name___name
• using blocks with select, select_append, where and order

And you don't feel like changing that now, you can include legacy API in your relations and things will continue to work the same as in rom-sql 0.9.x:

class Users < ROM::Relation[:sql]
  include ROM::SQL::Relation::SequelAPI

  def list
    # this will continue to work
    select(:users__id, :users__name)
  end
end

Notice that this API will be deprecated in 1.1.0 and removed in 2.0.0 so please upgrade soon :)

Projection with blocks

class Users < ROM::Relation[:sql]
  schema(infer: true)

  # 0.9.x
  def list
    select(:users__id, :users__name).order(:users__id)
  end

  # 1.0.0
  def list
    # shortcut
    qualified.order { id.qualified }

    # or explicit with blocks
    select { [id.qualifed, name.qualified] }.order { id.qualified }
  end

  # using SQL functions in 0.9.x
  def list_with_count
    select { [count(id).as(:count)] }
  end

  # using SQL functions in 1.0.0
  def list_with_count
    select { [int::count(id).as(:count)] }
  end
end

PG types & extensions

All PG types and extensions are automatically loaded now. So if you still require those manually and see errors like this:

LoadError: cannot load such file -- rom/sql/types/pg

...then simply remove requires.

Frozen datasets

Sequel 5.0.0 will use frozen datasets by default, in 4.42 there's :freeze_datasets extension and rom-sql 1.0.0 enables it by default.

If you rely on datasets mutations, it will no longer work