sexy_pg_constraints 0.1.2

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/Manifest

@@ -0,0 +1,14 @@
+CHANGELOG.rdoc
+Manifest
+README.rdoc
+Rakefile
+init.rb
+lib/constrainer.rb
+lib/constraints.rb
+lib/deconstrainer.rb
+lib/helpers.rb
+lib/sexy_pg_constraints.rb
+sexy_pg_constraints.gemspec
+test/postgresql_adapter.rb
+test/sexy_pg_constraints_test.rb
+test/test_helper.rb

data/README.rdoc

@@ -0,0 +1,139 @@
+= 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
+
+== 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
+
+* Create better API for adding constraints
+
+== License
+
+Copyright (c) 2008 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/Rakefile

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('sexy_pg_constraints', '0.1.2') do |p|
+  p.description     = "Use migrations and simple syntax to manage constraints in PostgreSQL DB."
+  p.summary         = "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."
+  p.url             = "http://github.com/maxim/sexy_pg_constraints"
+  p.author          = "Maxim Chernyak"
+  p.email           = "max@bitsonnet.com"
+  p.ignore_pattern  = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/init.rb

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

data/lib/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, column, options) + ';'
+          
+          execute sql
+        end
+      end
+    end
+  end
+end

data/lib/constraints.rb

@@ -0,0 +1,154 @@
+module SexyPgConstraints
+  module Constraints
+    module_function
+    
+    ##
+    # Only allow listed values.
+    #
+    # Example: 
+    #   constrain :books, :variation, :whitelist => %w(hardcover softcover)
+    #
+    def whitelist(column, options)
+      "check (#{column} in (#{ options.collect{|v| "'#{v}'"}.join(',')  }))"
+    end
+  
+    ## 
+    # Prohibit listed values.
+    #
+    # Example: 
+    #   constrain :books, :isbn, :blacklist => %w(invalid_isbn1 invalid_isbn2)
+    #
+    def blacklist(column, options)
+      "check (#{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(column, options)
+      "check ( length(trim(both from #{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(column, options)
+      "check (#{column} >= #{options.begin} and #{column} #{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(column, options)
+      within("length(#{column})", options)
+    end
+    
+    ## 
+    # Allow only valid email format.
+    #
+    # Example:
+    #   constrain :books, :author, :email => true
+    #
+    def email(column, options)
+      "check (((#{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(column, options)
+      "check (((#{column})::text ~* '^[a-z0-9]+$'::text))"
+    end
+    
+    ## 
+    # Allow only positive values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :positive => true
+    #
+    def positive(column, options)
+      "check (#{column} >= 0)"
+    end
+    
+    ## 
+    # Allow only odd values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :odd => true
+    #
+    def odd(column, options)
+      "check (mod(#{column}, 2) != 0)"
+    end
+
+    ## 
+    # Allow only even values.
+    #
+    # Example:
+    #   constrain :books, :quantity, :even => true
+    #
+    def even(column, options)
+      "check (mod(#{column}, 2) = 0)"
+    end
+
+    ## 
+    # Make sure every entry in the column is unique.
+    #
+    # Example:
+    #   constrain :books, :isbn, :unique => true
+    #
+    def unique(column, options)
+      column = column.join(', ') if column.respond_to?(:join)
+      "unique (#{column})"
+    end
+    
+    ## 
+    # Allow only text/strings of the exact length specified, no more, no less.
+    #
+    # Example:
+    #   constrain :books, :hash, :exact_length => 32
+    #
+    def exact_length(column, options)
+      "check ( length(trim(both from #{column})) = #{options} )"
+    end
+    
+    ## 
+    # Allow only values that match the regular expression.
+    #
+    # Example:
+    #   constrain :orders, :visa, :format => /^([4]{1})([0-9]{12,15})$/
+    #
+    def format(column, options)
+      "check (((#{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(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

data/lib/deconstrainer.rb

@@ -0,0 +1,31 @@
+module SexyPgConstraints
+  class DeConstrainer
+    include SexyPgConstraints::Helpers
+  
+    def initialize(table, columns = [])
+      @table = table.to_s
+      @columns = columns
+    end
+  
+    def method_missing(column, *constraints)
+      self.class.drop_constraints(@table, column.to_s, *constraints)
+    end
+    
+    def [](*columns)
+      @columns = columns.map{|c| c.to_s}
+      self
+    end
+    
+    def all(*constraints)
+      self.class.drop_constraints(@table, @columns, *constraints)
+    end
+  
+    class << self
+      def drop_constraints(table, column, *constraints)
+        constraints.each do |type|
+          execute "alter table #{table} drop constraint #{make_title(table, column, type)};"
+        end
+      end
+    end
+  end
+end

data/lib/helpers.rb

@@ -0,0 +1,19 @@
+module SexyPgConstraints
+  module Helpers
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      def make_title(table, column, type)
+        column = column.join('_') if column.respond_to?(:join)
+        
+        "#{table}_#{column}_#{type}"
+      end
+      
+      def execute(*args)
+        ActiveRecord::Base.connection.execute(*args)
+      end
+    end
+  end
+end

data/lib/sexy_pg_constraints.rb

@@ -0,0 +1,24 @@
+require "helpers"
+require "constrainer"
+require "deconstrainer"
+require "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
+
+ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.send(:include, SexyPgConstraints)

data/sexy_pg_constraints.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sexy_pg_constraints}
+  s.version = "0.1.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Maxim Chernyak"]
+  s.date = %q{2009-10-04}
+  s.description = %q{Use migrations and simple syntax to manage constraints in PostgreSQL DB.}
+  s.email = %q{max@bitsonnet.com}
+  s.extra_rdoc_files = ["CHANGELOG.rdoc", "README.rdoc", "lib/constrainer.rb", "lib/constraints.rb", "lib/deconstrainer.rb", "lib/helpers.rb", "lib/sexy_pg_constraints.rb"]
+  s.files = ["CHANGELOG.rdoc", "Manifest", "README.rdoc", "Rakefile", "init.rb", "lib/constrainer.rb", "lib/constraints.rb", "lib/deconstrainer.rb", "lib/helpers.rb", "lib/sexy_pg_constraints.rb", "sexy_pg_constraints.gemspec", "test/postgresql_adapter.rb", "test/sexy_pg_constraints_test.rb", "test/test_helper.rb"]
+  s.homepage = %q{http://github.com/maxim/sexy_pg_constraints}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Sexy_pg_constraints", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{sexy_pg_constraints}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{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.}
+  s.test_files = ["test/sexy_pg_constraints_test.rb", "test/test_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end