pg_power 1.0.0

data/README.markdown

@@ -0,0 +1,212 @@
+# PgPower
+
+ActiveRecord extension to get more from PostgreSQL:
+
+* Create/drop schemas.
+* Set/remove comments on columns and tables.
+* Use foreign keys.
+* Use partial indexes.
+
+## Environment notes
+
+It was tested with Rails 3.1.x and 3.2.x, Ruby 1.8.7 REE and 1.9.3.
+
+
+## Schemas
+
+### Create schema
+
+In migrations you can use `create_schema` and `drop_schema` methods like this:
+
+    class ReplaceDemographySchemaWithPolitics < ActiveRecord::Migration
+      def change
+        drop_schema 'demography'
+        create_schema 'politics'
+      end
+    end
+
+### Create table
+
+Use schema `:schema` option to specify schema name:
+
+    create_table "countries", :schema => "demography" do |t|
+      # columns goes here
+    end
+
+### Move table to another schema
+
+Move table `countries` from `demography` schema to `public`:
+
+    move_table_to_schema 'demography.countries', :public
+
+## Table and column comments
+
+Provides the following methods to manage comments:
+
+* set\_table\_comment(table\_name, comment)
+* remove\_table\_comment(table\_name)
+* set\_column\_comment(table\_name, column\_name, comment)
+* remove\_column\_comment(table\_name, column\_name, comment)
+* set\_column\_comments(table\_name, comments)
+* remove\_column\_comments(table\_name, *comments)
+
+
+### Examples
+
+Set a comment on the given table.
+
+    set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'
+
+Sets a comment on a given column of a given table.
+
+    set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+
+Removes any comment from the given table.
+
+    remove_table_comment :phone_numbers
+
+Removes any comment from the given column of a given table.
+
+    remove_column_comment :phone_numbers, :npa
+
+Set comments on multiple columns in the table.
+
+    set_column_comments :phone_numbers, :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
+                                        :nxx => 'Central Office Number'
+
+Remove comments from multiple columns in the table.
+
+    remove_column_comments :phone_numbers, :npa, :nxx
+
+PgPower also adds extra methods to change_table.
+
+Set comments:
+
+    change_table :phone_numbers do |t|
+        t.set_table_comment 'This table stores phone numbers that conform to the North American Numbering Plan.'
+        t.set_column_comment :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+    end
+
+    change_table :phone_numbers do |t|
+        t.set_column_comments :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
+                              :nxx => 'Central Office Number'
+    end
+
+Remove comments:
+
+    change_table :phone_numbers do |t|
+        t.remove_table_comment
+        t.remove_column_comment :npa
+    end
+
+    change_table :phone_numbers do |t|
+      t.remove_column_comments :npa, :nxx
+    end
+
+## Foreign keys
+
+We imported some code of [foreigner](https://github.com/matthuhiggins/foreigner)
+gem and patched it to be schema-aware. We also added support for index auto-generation.
+
+You should disable `foreigner` in your Gemfile if you want to use `pg_power`.
+
+If you do not want to generate an index, pass the :exclude_index => true option.
+
+The syntax is compatible with `foreigner`:
+
+
+Add foreign key from `comments` to `posts` using `post_id` column as key by default:
+    add_foreign_key(:comments, :posts)
+
+Specify key explicitly:
+    add_foreign_key(:comments, :posts, :column => :blog_post_id)
+
+Specify name of foreign key constraint:
+    add_foreign_key(:comments, :posts, :name => "comments_posts_fk")
+
+It works with schemas as expected:
+    add_foreign_key('blog.comments', 'blog.posts')
+
+Adds the index 'index_comments_on_post_id':
+    add_foreign_key(:comments, :posts)
+
+Does not add an index:
+    add_foreign_key(:comments, :posts, :exclude_index => true)
+
+## Partial Indexes
+
+We used a Rails 4.x [pull request](https://github.com/rails/rails/pull/4956) as a
+starting point, backported to Rails 3.1.x and patched it to be schema-aware.
+
+### Examples
+
+Add a partial index to a table
+
+    add_index(:comments, [:country_id, :user_id], :where => 'active')
+
+Add a partial index to a schema table
+
+    add_index('blog.comments', :user_id, :where => 'active')
+
+## Indexes on Expressions
+
+PostgreSQL supports indexes on expressions. Right now, only basic functional
+expressions are supported.
+
+### Examples
+
+Add an index to a column with a function
+
+    add_index(:comments, "lower(text)")
+
+## Tools
+
+PgPower::Tools provides number of useful methods:
+
+    PgPower::Tools.create_schema "services"                 # => create new PG schema "services"
+    PgPower::Tools.create_schema "nets"                     # => create new PG schema "nets"
+    PgPower::Tools.drop_schema "services"                   # => remove the PG schema "services"
+    PgPower::Tools.schemas                                  # => ["public", "information_schema", "nets"]
+    PgPower::Tools.index_exists?(table, columns, options)   # => returns true if an index exists for the given params
+
+## Running tests:
+
+* Configure `spec/dummy/config/database.yml` for development and test environments.
+* Run `rake spec`.
+* Make sure migrations don't raise exceptions and all specs pass.
+
+## TODO:
+
+Add next syntax to create table:
+
+    create_table "table_name", :schema => "schema_name" do |t|
+      # columns goes here
+    end
+
+Support for JRuby:
+
+* Jdbc driver provides its own `create_schema(schema, user)` method - solve conflicts.
+
+## Credits
+
+* [Potapov Sergey](https://github.com/greyblake) - schema support
+* [Arthur Shagall](https://github.com/albertosaurus) - thanks for [pg_comment](https://github.com/albertosaurus/pg_comment)
+* [Matthew Higgins](https://github.com/matthuhiggins) - thanks for [foreigner](https://github.com/matthuhiggins/foreigner), which was used as a base for the foreign key support
+* [Marcelo Silveira](https://github.com/mhfs) - thanks for rails partial index support that was backported into this gem
+
+## Copyright and License
+
+Copyright (c) 2012 TMX Credit.
+Initial foreign key code taken from foreigner, Copyright (c) 2009 Matthew Higgins
+pg_comment Copyright (c) 2011 Arthur Shagall
+Partial index Copyright (c) 2012 Marcelo Silveira
+
+Released under the MIT License.  See the MIT-LICENSE file for more details.
+
+## Contributing
+
+Contributions are welcome.  However, before issuing a pull request, please make sure of the following:
+
+* All specs are passing (under both ree and 1.9.3)
+* Any new features have test coverage.
+* Anything that breaks backward compatibility has a very good reason for doing so.

data/lib/core_ext/active_record/connection_adapters/abstract/schema_statements.rb

@@ -0,0 +1,139 @@
+module ActiveRecord
+  module ConnectionAdapters # :nodoc:
+    module SchemaStatements # :nodoc:
+      # Regexp used to find the function name and function argument of a
+      # function call
+      FUNCTIONAL_INDEX_REGEXP = /(\w+)\((\w+)\)/
+
+      # Adds a new index to the table.  +column_name+ can be a single Symbol, or
+      # an Array of Symbols.
+      #
+      # ====== Creating a partial index
+      #  add_index(:accounts, [:branch_id, :party_id], :unique => true, :where => "active")
+      # generates
+      #  CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id) WHERE active
+      #
+      def add_index(table_name, column_name, options = {})
+        index_name, index_type, index_columns, index_options = add_index_options(table_name, column_name, options)
+        execute "CREATE #{index_type} INDEX #{quote_column_name(index_name)} ON #{quote_table_name(table_name)} (#{index_columns})#{index_options}"
+      end
+
+      # Checks to see if an index exists on a table for a given index definition.
+      #
+      # === Examples
+      #  # Check that a partial index exists
+      #  index_exists?(:suppliers, :company_id, :where => 'active')
+      #
+      #  # GIVEN: "index_suppliers_on_company_id" UNIQUE, btree (company_id) WHERE active
+      #  index_exists?(:suppliers, :company_id, :unique => true, :where => 'active') => true
+      #  index_exists?(:suppliers, :company_id, :unique => true) => false
+      #
+      def index_exists?(table_name, column_name, options = {})
+        column_names = Array.wrap(column_name)
+        index_name = options.key?(:name) ? options[:name].to_s : index_name(table_name, :column => column_names)
+
+        # Always compare the index name
+        default_comparator = lambda { |index| index.name == index_name }
+        comparators = [default_comparator]
+
+        # Add a comparator for each index option that is part of the query
+        index_options = [:unique, :where]
+        index_options.each do |index_option|
+          comparators << if options.key?(index_option)
+            lambda do |index|
+              pg_where_clause = index.send(index_option)
+              # pg does nothing to boolean clauses, e.g. 'where active' => 'where active'
+              if pg_where_clause.is_a?(TrueClass) or pg_where_clause.is_a?(FalseClass)
+                pg_where_clause == options[index_option]
+              else
+                # pg adds parentheses around non-boolean clauses, e.g. 'where color IS NULL' => 'where (color is NULL)'
+                pg_where_clause.gsub!(/[()]/,'')
+                # pg casts string comparison ::text. e.g. "where color = 'black'" => "where ((color)::text = 'black'::text)"
+                pg_where_clause.gsub!(/::text/,'')
+                # prevent case from impacting the comparison
+                pg_where_clause.downcase == options[index_option].downcase
+              end
+            end
+          else
+            # If the given index_option is not an argument to the index_exists? query,
+            # select only those pg indexes that do not have the component
+            lambda { |index| index.send(index_option).blank? }
+          end
+        end
+
+        # Search all indexes for any that match all comparators
+        indexes(table_name).any? do |index|
+          comparators.inject(true) { |ret, comparator| ret && comparator.call(index) }
+        end
+      end
+
+      # Derives the name of the index from the given table name and options hash.
+      def index_name(table_name, options) #:nodoc:
+        if Hash === options # legacy support
+          if options[:column]
+            column_names = Array.wrap(options[:column]).map {|c| expression_index_name(c)}
+            "index_#{table_name}_on_#{column_names * '_and_'}"
+          elsif options[:name]
+            options[:name]
+          else
+            raise ArgumentError, "You must specify the index name"
+          end
+        else
+          index_name(table_name, :column => options)
+        end
+      end
+
+      # Returns options used to build out index SQL
+      #
+      # Added support for partial indexes implemented using the :where option
+      #
+      def add_index_options(table_name, column_name, options = {})
+        column_names = Array(column_name)
+        index_name   = index_name(table_name, :column => column_names)
+
+        if Hash === options # legacy support, since this param was a string
+          index_type = options[:unique] ? "UNIQUE" : ""
+          index_name = options[:name].to_s if options.key?(:name)
+          if supports_partial_index?
+            index_options = options[:where] ? " WHERE #{options[:where]}" : ""
+          end
+        else
+          index_type = options
+        end
+
+        if index_name.length > index_name_length
+          raise ArgumentError, "Index name '#{index_name}' on table '#{table_name}' is too long; the limit is #{index_name_length} characters"
+        end
+        if index_name_exists?(table_name, index_name, false)
+          raise ArgumentError, "Index name '#{index_name}' on table '#{table_name}' already exists"
+        end
+        index_columns = quoted_columns_for_index(column_names, options).join(", ")
+
+        [index_name, index_type, index_columns, index_options]
+      end
+      protected :add_index_options
+
+      # Override super method to provide support for expression column names
+      def quoted_columns_for_index(column_names, options = {})
+        column_names.map do |name|
+          if name =~ FUNCTIONAL_INDEX_REGEXP
+            "#{$1}(#{quote_column_name($2)})"
+          else
+            quote_column_name(name)
+          end
+        end
+      end
+      protected :quoted_columns_for_index
+
+      # Map an expression to a name appropriate for an index
+      def expression_index_name(column_name)
+        if column_name =~ FUNCTIONAL_INDEX_REGEXP
+          "#{$1.downcase}_#{$2}"
+        else
+          column_name
+        end
+      end
+      private :expression_index_name
+    end
+  end
+end

data/lib/core_ext/active_record/connection_adapters/postgresql_adapter.rb

@@ -0,0 +1,135 @@
+module ActiveRecord # :nodoc:
+  module ConnectionAdapters # :nodoc:
+    # Patched version:  3.1.3
+    # Patched methods::
+    #   * indexes
+    class PostgreSQLAdapter
+      # In Rails3.2 method #extract_schema_and_table is moved into Utils module.
+      # In Rails3.1 it's implemented right in PostgreSQLAdapter class.
+      # So it's Rails3.2 we include the module into PostgreSQLAdapter in order to make
+      # it compatible to Rails3.1
+      # -- sergey.potapov 2012-06-25
+      if ActiveRecord::VERSION::STRING =~ /^3\.2/
+        include self::Utils
+      end
+
+      # Regex to find columns used in index statements
+      INDEX_COLUMN_EXPRESSION = /ON \w+(?: USING \w+ )?\((.+)\)/
+      # Regex to find where clause in index statements
+      INDEX_WHERE_EXPRESION = /WHERE (.+)$/
+
+      # Returns an array of indexes for the given table.
+      #
+      # == Patch 1 reason:
+      # Since {ActiveRecord::SchemaDumper#tables} is patched to process tables
+      # with a schema prefix, the {#indexes} method receives table_name as
+      # "<schema>.<table>". This patch allows it to handle table names with
+      # a schema prefix.
+      #
+      # == Patch 1:
+      # Search using provided schema if table_name includes schema name.
+      #
+      # == Patch 2 reason:
+      # {ActiveRecord::ConnectionAdapters::PostgreSQLAdapter#indexes} is patched
+      # to support partial indexes using :where clause.
+      #
+      # == Patch 2:
+      # Search the postgres indexdef for the where clause and pass the output to
+      # the custom {PgPower::ConnectionAdapters::IndexDefinition}
+      #
+      def indexes(table_name, name = nil)
+        schema, table = extract_schema_and_table(table_name)
+        schemas = schema ? "ARRAY['#{schema}']" : 'current_schemas(false)'
+
+        result = query(<<-SQL, name)
+          SELECT distinct i.relname, d.indisunique, d.indkey,  pg_get_indexdef(d.indexrelid), t.oid
+          FROM pg_class t
+          INNER JOIN pg_index d ON t.oid = d.indrelid
+          INNER JOIN pg_class i ON d.indexrelid = i.oid
+          WHERE i.relkind = 'i'
+            AND d.indisprimary = 'f'
+            AND t.relname = '#{table}'
+            AND i.relnamespace IN (SELECT oid FROM pg_namespace WHERE nspname = ANY (#{schemas}) )
+         ORDER BY i.relname
+        SQL
+
+        result.map do |row|
+          index = {
+            :name       => row[0],
+            :unique     => row[1] == 't',
+            :keys       => row[2].split(" "),
+            :definition => row[3],
+            :id         => row[4]
+          }
+
+          column_names = find_column_names(table_name, index)
+
+          unless column_names.empty?
+            where   = find_where_statement(index)
+            lengths = find_lengths(index)
+
+            PgPower::ConnectionAdapters::IndexDefinition.new(table_name, index[:name], index[:unique], column_names, lengths, where)
+          end
+        end.compact
+      end
+
+      # Find column names from index attributes. If the columns are virtual (ie
+      # this is an expression index) then it will try to return the functions
+      # that represent each column
+      #
+      # @param [String] table_name the name of the table
+      # @param [Hash] index index attributes
+      # @return [Array]
+      def find_column_names(table_name, index)
+        columns = Hash[query(<<-SQL, "Columns for index #{index[:name]} on #{table_name}")]
+          SELECT a.attnum, a.attname
+          FROM pg_attribute a
+          WHERE a.attrelid = #{index[:id]}
+          AND a.attnum IN (#{index[:keys].join(",")})
+        SQL
+
+        column_names = columns.values_at(*index[:keys]).compact
+
+        if column_names.empty?
+          definition = index[:definition].sub(INDEX_WHERE_EXPRESION, '')
+          if column_expression = definition.match(INDEX_COLUMN_EXPRESSION)[1]
+            column_names = column_expression.split(',').map do |functional_name|
+              remove_type(functional_name)
+            end
+          end
+        end
+
+        column_names
+      end
+
+      # Find where statement from index definition
+      #
+      # @param [Hash] index index attributes
+      # @return [String] where statement
+      def find_where_statement(index)
+        index[:definition].scan(INDEX_WHERE_EXPRESION).flatten[0]
+      end
+
+      # Find length of index
+      # TODO Update lengths once we merge in ActiveRecord code that supports it. -dresselm 20120305
+      #
+      # @param [Hash] index index attributes
+      # @return [Array]
+      def find_lengths(index)
+        []
+      end
+
+      # Remove type specification from stored Postgres index definitions
+      #
+      # @param [String] column_with_type the name of the column with type
+      # @return [String]
+      #
+      # @example
+      #   remove_type("((col)::text")
+      #   => "col"
+      def remove_type(column_with_type)
+        column_with_type.sub(/\((\w+)\)::\w+/, '\1')
+      end
+    end
+  end
+end