Empact-sexy_pg_constraints 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,12 @@
+=== 0.1.3 - 01.19.2009
+
+* Bugfix: positive constraint fixed from >0 to >=0. Deconstrain and constrain to reapply.
+
+=== 0.1.2 - 11.30.2008
+
+* New constraints: even, odd, format
+
+=== 0.1.1 - 11.30.2008
+
+* Added foreign key constraints support.
+* Added multi-column constraints support.

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+gem "activerecord", ">= 3.0.0"
+gem "pg"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,37 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.7)
+      activesupport (= 3.0.7)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.7)
+      activemodel (= 3.0.7)
+      activesupport (= 3.0.7)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.7)
+    arel (2.0.9)
+    builder (2.1.2)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    pg (0.11.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+    tzinfo (0.3.26)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (>= 3.0.0)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  pg
+  rcov
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Maxim Chernyak
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,123 @@
+= Sexy PG Constraints
+
+If you're on PostgreSQL and see the importance of data-layer constraints - this gem/plugin is for you. It integrates constraints into PostgreSQL adapter so you can add/remove them in your migrations. You get two simple methods for adding/removing constraints, as well as a pack of pre-made constraints.
+
+== Install
+As a gem
+  gem install maxim-sexy_pg_constraints --source http://gems.github.com
+or as a plugin
+  script/plugin install git://github.com/maxim/sexy_pg_constraints.git
+	
+
+One more thing. Make sure that in your environment.rb file you have the following line uncommented.
+
+  config.active_record.schema_format = :sql
+
+Otherwise your test database will not have these constraints replicated.
+
+== Usage
+
+=== Single-column constraints
+Say you have a table "books" and you want your Postgres DB to ensure that their title is not-blank, alphanumeric, and its length is between 3 and 50 chars. You also want to make sure that their isbn is unique. In addition you want to blacklist a few isbn numbers from ever being in your database. You can tell all that to your Postgres in no time. Generate a migration and write the following.
+
+  class AddConstraintsToBooks < ActiveRecord::Migration
+    def self.up
+      constrain :books do |t|
+        t.title :not_blank => true, :alphanumeric => true, :length_within => 3..50
+        t.isbn :unique => true, :blacklist => %w(badbook1 badbook2)
+      end
+    end
+
+    def self.down
+      deconstrain :books do |t|
+        t.title :not_blank, :alphanumeric, :length_within
+        t.isbn :unique, :blacklist
+      end
+    end
+  end
+
+This will add all the necessary constraints to the database on the next migration, and remove them on rollback.
+
+There's also a syntax for when you don't need to work with multiple columns at once.
+
+  constrain :books, :title, :not_blank => true, :length_within => 3..50
+
+The above line works exactly the same as this block
+
+  constrain :books do |t|
+    t.title :not_blank => true, :length_within => 3..50
+  end
+	
+Same applies to deconstrain.
+
+=== Multi-column constraints
+Say you have the same table "books" only now you want to tell your Postgres to make sure that you should never have the same title + author_id combination. It means that you want to apply uniqueness to two columns, not just one. There is a special syntax for working with multicolumn constraints.
+
+  class AddConstraintsToBooks < ActiveRecord::Migration
+    def self.up
+      constrain :books do |t|
+        t[:title, :author_id].all :unique => true # Notice how multiple columns are listed in brackets.
+      end
+    end
+
+    def self.down
+      deconstrain :books do |t|
+        t[:title, :author_id].all :unique
+      end
+    end
+  end
+
+It's important to note that you shouldn't mix multicolumn constraints with regular ones in one line. This may cause unexpected behavior.
+
+=== Foreign key constrants
+In our table "books" we have column "author_id" which should reference the "id" column in the "authors" table. Here's the very simple syntax for setting up foreign key constraint that will tell Postgres to enforce this relationship.
+
+  class AddConstraintsToBooks < ActiveRecord::Migration
+    def self.up
+      constrain :books do |t|
+        t.author_id :reference => {:authors => :id, :on_delete => :cascade} # :on_delete is optional
+      end
+    end
+
+    def self.down
+      deconstrain :books do |t|
+        t.author_id :reference
+      end
+    end
+  end
+
+In this example we're telling Postgres to enforce the connection of author_id to the column "id" in table "authors". However, we're also telling it to cascade on delete. This means that when an author is deleted - every book that referred to that author will be deleted as well.
+
+== Available constraints
+
+Below is the list of constraints available and tested so far.
+
+* whitelist
+* blacklist
+* not_blank
+* within
+* length_within
+* email
+* alphanumeric
+* positive
+* unique
+* exact_length
+* reference
+* even
+* odd
+* format
+* lowercase
+* xor
+
+== Extensibility
+
+All constraints are located in the lib/constraints.rb. Extending this module with more methods will automatically make constraints available in migrations. All methods in the Constraints module are under module_function directive. Each method is supposed to return a piece of SQL that is inserted "alter table foo add constraint bar #{RIGHT HERE};."
+
+== TODO
+
+* Add support for Rails schema.rb
+* Create better API for adding constraints
+
+== Contributors
+* Empact[http://github.com/Empact] (Big thanks for lots of work. Better flexibility, more tests, organizing code, bug fixes.)
+* look[http://github.com/look] (Extra constraints: lowercase and xor.)

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = 'Empact-sexy_pg_constraints'
+  gem.homepage = "http://github.com/maxim/sexy_pg_constraints"
+  gem.description = "Use migrations and simple syntax to manage constraints in PostgreSQL DB."
+  gem.email = "ben.woosley@gmail.com"
+  gem.authors = ["Maxim Chernyak", "Ben Woosley"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "test #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/init.rb

@@ -0,0 +1 @@
+require 'sexy_pg_constraints'

data/lib/sexy_pg_constraints.rb

@@ -0,0 +1,23 @@
+require 'sexy_pg_constraints/initializer'
+require "sexy_pg_constraints/helpers"
+require "sexy_pg_constraints/constrainer"
+require "sexy_pg_constraints/deconstrainer"
+require "sexy_pg_constraints/constraints"
+
+module SexyPgConstraints
+  def constrain(*args)
+    if block_given?
+      yield SexyPgConstraints::Constrainer.new(args[0].to_s)
+    else
+      SexyPgConstraints::Constrainer::add_constraints(*args)
+    end
+  end
+
+  def deconstrain(*args)
+    if block_given?
+      yield SexyPgConstraints::DeConstrainer.new(args[0])
+    else
+      SexyPgConstraints::DeConstrainer::drop_constraints(*args)
+    end
+  end
+end

data/lib/sexy_pg_constraints/constrainer.rb

@@ -0,0 +1,34 @@
+module SexyPgConstraints
+  class Constrainer
+    include SexyPgConstraints::Helpers
+    
+    def initialize(table, columns = [])
+      @table = table.to_s
+      @columns = columns
+    end
+
+    def method_missing(column, constraints)
+      self.class.add_constraints(@table, column.to_s, constraints)
+    end
+    
+    def [](*columns)
+      @columns = columns.map{|c| c.to_s}
+      self
+    end
+    
+    def all(constraints)
+      self.class.add_constraints(@table, @columns, constraints)
+    end
+    
+    class << self
+      def add_constraints(table, column, constraints)
+        constraints.each_pair do |type, options|
+          sql = "alter table #{table} add constraint #{make_title(table, column, type)} " + 
+            SexyPgConstraints::Constraints.send(type, table, column, options) + ';'
+          
+          execute sql
+        end
+      end
+    end
+  end
+end

data/lib/sexy_pg_constraints/constraints.rb

@@ -0,0 +1,179 @@
+module SexyPgConstraints
+  module Constraints
+    module_function
+
+    ##
+    # Only allow listed values.
+    #
+    # Example:
+    #   constrain :books, :variation, :whitelist => %w(hardcover softcover)
+    #
+    def whitelist(table, column, options)
+      "check (#{table}.#{column} in (#{ options.collect{|v| "'#{v}'"}.join(',')  }))"
+    end
+
+    ##
+    # Prohibit listed values.
+    #
+    # Example:
+    #   constrain :books, :isbn, :blacklist => %w(invalid_isbn1 invalid_isbn2)
+    #
+    def blacklist(table, column, options)
+      "check (#{table}.#{column} not in (#{ options.collect{|v| "'#{v}'"}.join(',') }))"
+    end
+
+    ##
+    # The value must have at least 1 non-space character.
+    #
+    # Example:
+    #   constrain :books, :title, :not_blank => true
+    #
+    def not_blank(table, column, options)
+      "check ( length(trim(both from #{table}.#{column})) > 0 )"
+    end
+
+    ##
+    # The numeric value must be within given range.
+    #
+    # Example:
+    #   constrain :books, :year, :within => 1980..2008
+    #   constrain :books, :year, :within => 1980...2009
+    # (the two lines above do the same thing)
+    #
+    def within(table, column, options)
+      column_ref = column.to_s.include?('.') ? column : "#{table}.#{column}"
+      "check (#{column_ref} >= #{options.begin} and #{column_ref} #{options.exclude_end? ? ' < ' : ' <= '} #{options.end})"
+    end
+
+    ##
+    # Check the length of strings/text to be within the range.
+    #
+    # Example:
+    #   constrain :books, :author, :length_within => 4..50
+    #
+    def length_within(table, column, options)
+      within(table, "length(#{table}.#{column})", options)
+    end
+
+    ##
+    # Allow only valid email format.
+    #
+    # Example:
+    #   constrain :books, :author, :email => true
+    #
+    def email(table, column, options)
+      "check (((#{table}.#{column})::text ~ E'^([-a-z0-9]+)@([-a-z0-9]+[.]+[a-z]{2,4})$'::text))"
+    end
+
+    ##
+    # Allow only alphanumeric values.
+    #
+    # Example:
+    #   constrain :books, :author, :alphanumeric => true
+    #
+    def alphanumeric(table, column, options)
+      "check (((#{table}.#{column})::text ~* '^[a-z0-9]+$'::text))"
+    end
+
+    ##
+    # Allow only lower case values.
+    #
+    # Example:
+    #   constrain :books, :author, :lowercase => true
+    #
+    def lowercase(table, column, options)
+      "check (#{table}.#{column} = lower(#{table}.#{column}))"
+    end
+
+    ##
+    # Allow only positive values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :positive => true
+    #
+    def positive(table, column, options)
+      "check (#{table}.#{column} >= 0)"
+    end
+
+    ##
+    # Allow only odd values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :odd => true
+    #
+    def odd(table, column, options)
+      "check (mod(#{table}.#{column}, 2) != 0)"
+    end
+
+    ##
+    # Allow only even values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :even => true
+    #
+    def even(table, column, options)
+      "check (mod(#{table}.#{column}, 2) = 0)"
+    end
+
+    ##
+    # Make sure every entry in the column is unique.
+    #
+    # Example:
+    #   constrain :books, :isbn, :unique => true
+    #
+    def unique(table, column, options)
+      column = Array(column).map {|c| %{"#{c}"} }.join(', ')
+      "unique (#{column})"
+    end
+
+    ##
+    # Allow only one of the values in the given columns to be true.
+    # Only reasonable with more than one column.
+    # See Enterprise Rails, Chapter 10 for details.
+    #
+    # Example:
+    #   constrain :books, [], :xor => true
+    #
+    def xor(table, column, options)
+      addition = Array(column).map {|c| %{("#{c}" is not null)::integer} }.join(' + ')
+
+      "check (#{addition} = 1)"
+    end
+
+    ##
+    # Allow only text/strings of the exact length specified, no more, no less.
+    #
+    # Example:
+    #   constrain :books, :hash, :exact_length => 32
+    #
+    def exact_length(table, column, options)
+      "check ( length(trim(both from #{table}.#{column})) = #{options} )"
+    end
+
+    ##
+    # Allow only values that match the regular expression.
+    #
+    # Example:
+    #   constrain :orders, :visa, :format => /^([4]{1})([0-9]{12,15})$/
+    #
+    def format(table, column, options)
+      "check (((#{table}.#{column})::text #{options.casefold? ? '~*' : '~'}  E'#{options.source}'::text ))"
+    end
+
+    ##
+    # Add foreign key constraint.
+    #
+    # Example:
+    #   constrain :books, :author_id, :reference => {:authors => :id, :on_delete => :cascade}
+    #
+    def reference(table, column, options)
+      on_delete = options.delete(:on_delete)
+      fk_table = options.keys.first
+      fk_column = options[fk_table]
+
+      on_delete = "on delete #{on_delete}" if on_delete
+
+      %{foreign key ("#{column}") references #{fk_table} (#{fk_column}) #{on_delete}}
+    end
+  end
+end