rein 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '059c6905ac22b82e4b73c05511b549eec26803f6'
-  data.tar.gz: c77740f464a4d9b203dffabc4afb67a764416206
+  metadata.gz: 5c374a01203d81386e0d12d076ad23d4b07715f8
+  data.tar.gz: 9059371da28496cdd1bd84f37dffddbdbdf4a21f
 SHA512:
-  metadata.gz: 8ae2b21f190d38839fbe44a28bea29ab3188ef9411f11c0e691e89a67d1646e31c77489cc8b36dd5560d977791116d57076317bed24467cee6feab554a5badff
-  data.tar.gz: e8c19eb0e51beb7d11a47198a26564692418bf65256e8382bfc87f6aa079f1ec568aacd4c050326455e5a7ac1245e1c28cdd161cc8bd521b6d5bad4bd51e2eaa
+  metadata.gz: 83a4fbf3978a81f1f2ecbdda5966a3ae493543ab4a9777cc5086fd4eefbb557571cd27a910d4ecc492e8985319ca9d8f890692bb747570642d706557a390cbf8
+  data.tar.gz: 0e4c36f501367e281afac4ac0828232b0b33b7550127c4fdb3fd77ad963c9a406cc010c8b1604678ee3d81d6d6a1ef637de5811e45ebf6ff87656eed90345f29

data/README.md

@@ -1,75 +1,176 @@
 # Rein
 
-Database constraints made easy for ActiveRecord. Rein currently supports
-PostgreSQL and MySQL (foreign keys only).
+[Data integrity](http://en.wikipedia.org/wiki/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.
 
-## Introduction
+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.
 
-[Database integrity](http://en.wikipedia.org/wiki/Database_integrity) is a
-"good thing". Constraining the allowed values in your database at the
-database-level (rather than solely at the application-level) is a much more
-robust way of ensuring your data stays sane.
+## Table of contents
 
-Unfortunately, ActiveRecord doesn't encourage (or even allow) you to use
-database integrity without resorting to hand-crafted SQL. Rein adds a handful
-of methods to your ActiveRecord migrations so that you can easily tame your
-database.
+* [Rein](#rein)
+  * [Table of contents](#table-of-contents)
+  * [Getting started](#getting-started)
+  * [Constraint types](#constraint-types)
+    * [Foreign key constraints](#foreign-key-constraints)
+    * [Inclusion constraints](#inclusion-constraints)
+    * [Numericality constraints](#numericality-constraints)
+    * [Presence constraints](#presence-constraints)
+  * [Example](#example)
+  * [License](#license)
 
-## Quick Start
+## Getting started
 
 Install the gem:
 
     gem install rein
 
-Add a foreign key constraint:
+## 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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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.
+
+### 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`:
+
+```ruby
+add_inclusion_constraint :books, :state, in: %w(available on_loan)
+```
+
+### 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:
+
+```ruby
+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`
 
-    add_foreign_key_constraint :books, :authors
+### Presence constraints
 
-Add a numericality constraint (PostgreSQL only):
+*(PostgreSQL only)*
 
-    add_numericality_constraint :books, :publication_month, :greater_than_or_equal_to => 1, :less_than_or_equal_to => 12
+A presence constraint ensures that a string column value is non-empty.
 
-Add an inclusion constraint (PostgreSQL only):
+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_inclusion_constraint :books, :state, :in => %w(available on_loan)
+```ruby
+add_presence_constraint :books, :title
+```
 
 ## Example
 
-Let's look at constraining values for this simple library application.
+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
+```ruby
+create_table :authors do |t|
+  t.string :name, null: false
+  t.timestamps, null: false
+end
 
-      t.timestamps
-    end
+# An author must have a name.
+add_presence_constraint :authors, :name
+```
 
-And here we have a table of books:
+We also have a table of books:
 
-    create_table :books do |t|
-      t.belongs_to :author,          :null => false
-      t.string     :name,            :null => false
-      t.string     :state,           :null => false
-      t.integer    :published_year,  :null => false
-      t.integer    :published_month, :null => false
+```ruby
+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
 
-      t.timestamps
-    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 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
 
-    # Our library doesn't deal in classics.
-    add_numericality_constraint :books, :published_year, :greater_than => 1980
+# State is always either "available" or "on_loan".
+add_inclusion_constraint :books, :state, in: %w(available on_loan)
 
-    # 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
+# Our library doesn't deal in classics.
+add_numericality_constraint :books, :published_year,
+  greater_than_or_equal_to: 1980
 
-    # State is always either "available" or "on_loan".
-    add_inclusion_constraint :books, :state, :in => %w(available on_loan)
+# 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
 
-This project is licensed under the [MIT License](/LICENSE).
+Rein is licensed under the [MIT License](/LICENSE).

data/lib/rein/constraint/foreign_key.rb

@@ -45,8 +45,8 @@ module Rein
         when :no_action then "NO ACTION"
         when :cascade then "CASCADE"
         when :restrict then "RESTRICT"
-        when :nullify then "SET NULL"
-        when :default then "SET DEFAULT"
+        when :set_null, :nullify then "SET NULL"
+        when :set_default, :default then "SET DEFAULT"
         else
           raise "Unknown referential action '#{action}'"
         end

data/lib/rein/version.rb

@@ -1,3 +1,3 @@
 module Rein
-  VERSION = "1.0.0".freeze
+  VERSION = "1.1.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rein
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Joshua Bassett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-14 00:00:00.000000000 Z
+date: 2017-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Database constraints made easy for ActiveRecord.