Rein

Data integrity is a good thing. Constraining the values allowed by your application at the database-level, rather than at the application-level, is a more robust way of ensuring your data stays sane.

Unfortunately, ActiveRecord doesn't encourage (or even allow) you to use database integrity without resorting to hand-crafted SQL. Rein (pronounced "rain") adds a handful of methods to your ActiveRecord migrations so that you can easily tame the data in your database.

Table of contents

Getting started

Install the gem:

gem install rein

Constraint types

Foreign key constraints

A foreign key constraint specifies that the values in a column must match the values appearing in some row of another table.

For example, let's say that we want to constrain the author_id column in the books table to one of the id values in the authors table:

add_foreign_key_constraint :books, :authors

Rein will automatically infer the column names for the tables, but if we need to be explicit we can using the referenced and referencing options:

add_foreign_key_constraint :books, :authors, referencing: :author_id, referenced: :id

We can also specify the behaviour when one of the referenced rows is updated or deleted:

add_foreign_key_constraint :books, :authors, on_delete: :cascade, on_update: :cascade

Here's all the options for specifying the delete/update behaviour:

  • no_action: if any referencing rows still exist when the constraint is checked, an error is raised; this is the default behavior if you do not specify anything.
  • cascade: when a referenced row is deleted, row(s) referencing it should be automatically deleted as well.
  • set_null: sets the referencing columns to be nulls when the referenced row is deleted.
  • set_default: sets the referencing columns to its default values when the referenced row is deleted.
  • restrict: prevents deletion of a referenced row.

To remove a foreign key constraint:

remove_foreign_key_constraint :books, :authors

Inclusion constraints

(PostgreSQL only)

An inclusion constraint specifies the possible values that a column value can take.

For example, we can ensure that state column values can only ever be available or on_loan:

add_inclusion_constraint :books, :state, in: %w(available on_loan)

To remove an inclusion constraint:

remove_inclusion_constraint :books, :state

Numericality constraints

(PostgreSQL only)

A numericality constraint specifies the range of values that a numeric column value can take.

For example, we can ensure that the publication_month can only ever be a value between 1 and 12:

add_numericality_constraint :books, :publication_month,
  greater_than_or_equal_to: 1,
  less_than_or_equal_to: 12

Here's all the options for constraining the values:

  • equal_to
  • not_equal_to
  • less_than
  • less_than_or_equal_to
  • greater_than
  • greater_than_or_equal_to

You may also include an if option to enforce the constraint only under certain conditions, like so:

add_numericality_constraint :books, :publication_month,
  greater_than_or_equal_to: 1,
  less_than_or_equal_to: 12,
  if: "status = 'published'"

To remove a numericality constraint:

remove_numericality_constraint :books, :publication_month

Presence constraints

(PostgreSQL only)

A presence constraint ensures that a string column value is non-empty.

A NOT NULL constraint will be satisfied by an empty string, but sometimes may you want to ensure that there is an actual value for a string:

add_presence_constraint :books, :title

If you only want to enforce the constraint under certain conditions, you can pass an optional if option:

add_presence_constraint :books, :isbn, if: "status = 'published'"

To remove a presence constraint:

remove_presence_constraint :books, :title

Data types

Enumerated types

(PostgreSQL only)

An enum is a data type that represents a static, ordered set of values.

create_enum_type :book_type, ['paperback', 'hardcover']

To drop an enum type from the database:

drop_enum_type :book_type

Views

A view is a named query that you can refer to just like an ordinary table. You can even create ActiveRecord models that are backed by views in your database.

For example, we can define an available_books view that returns only the books which are currently available:

create_view(:available_books, "SELECT * FROM books WHERE state = 'available'")

To drop a view from the database:

drop_view(:available_books)

Example

Let's have a look at constraining database values for this simple library application.

Here we have a table of authors:

create_table :authors do |t|
  t.string :name, null: false
  t.timestamps, null: false
end

# An author must have a name.
add_presence_constraint :authors, :name

We also have a table of books:

create_table :books do |t|
  t.belongs_to :author, null: false
  t.string :title, null: false
  t.string :state, null: false
  t.integer :published_year, null: false
  t.integer :published_month, null: false
  t.timestamps, null: false
end

# A book should always belong to an author. The database should prevent us from
# deleteing an author who has books.
add_foreign_key_constraint :books, :authors, on_delete: :restrict

# A book must have a non-empty title.
add_presence_constraint :books, :title

# State is always either "available" or "on_loan".
add_inclusion_constraint :books, :state, in: %w(available on_loan)

# Our library doesn't deal in classics.
add_numericality_constraint :books, :published_year,
  greater_than_or_equal_to: 1980

# Month is always between 1 and 12.
add_numericality_constraint :books, :published_month,
  greater_than_or_equal_to: 1,
  less_than_or_equal_to: 12

License

Rein is licensed under the MIT License.