pg_power 1.0.1 → 1.1.0

data/README.markdown

@@ -10,6 +10,7 @@ ActiveRecord extension to get more from PostgreSQL:
 * Set/remove comments on columns and tables.
 * Use foreign keys.
 * Use partial indexes.
+* Run index creation concurrently.
 
 ## Environment notes
 
@@ -166,9 +167,30 @@ expressions are supported.
 ### Examples
 
 Add an index to a column with a function
+
+```ruby
+    add_index(:comments, "lower(text)")
+```
+
+## Concurrent index creation
+
+PostgreSQL supports concurent index creation. We added that feature to migration
+DSL on index and foreign keys creation.
+
+### Examples
+
+Add an index concurrently to a table
+
 ```ruby
-add_index(:comments, "lower(text)")
+    add_index :table, :column_id, :concurrently => true
 ```
+
+Add an index concurrently along with foreign key
+
+```ruby
+    add_foreign_key :table1, :table2, :column => :column_id, :concurrent_index => true
+```
+
 ## Tools
 
 PgPower::Tools provides number of useful methods:
@@ -206,10 +228,10 @@ Support for JRuby:
 
 ## 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
+* 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.
 

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

@@ -9,13 +9,37 @@ module ActiveRecord
       # an Array of Symbols.
       #
       # ====== Creating a partial index
-      #  add_index(:accounts, [:branch_id, :party_id], :unique => true, :where => "active")
+      #  add_index(:accounts, [:branch_id, :party_id],
+      #   :unique => true, :concurrently => true, :where => 'active')
       # generates
-      #  CREATE UNIQUE INDEX index_accounts_on_branch_id_and_party_id ON accounts(branch_id, party_id) WHERE active
+      #  CREATE UNIQUE INDEX CONCURRENTLY
+      #   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}"
+        name, type, creation_method, columns, opts = add_index_options(table_name, column_name, options)
+
+        # GOTCHA:
+        #   It ensures that there is no existing index only for the case when the index
+        #   is created concurrently to avoid changing the error behavior for default
+        #   index creation.
+        #   -- zekefast 2012-09-25
+        # GOTCHA:
+        #   This check prevents invalid index creation, so after migration failed
+        #   here there is no need to go to database and clean it from invalid
+        #   indexes. But note that this handles only one of the cases when index
+        #   creation can fail!!! All other case should be procesed manually.
+        #   -- zekefast 2012-09-25
+        if options.has_key?(:concurrently) && index_exists?(table_name, column_name, options)
+          raise ::PgPower::IndexExistsError, "Index #{name} for `#{table_name}.#{column_name}` " \
+            "column can not be created concurrently, because such index already exists."
+        end
+
+        execute "CREATE #{type} INDEX #{creation_method} #{quote_column_name(name)} " \
+          "ON #{quote_table_name(table_name)} (#{columns})#{opts}"
       end
 
       # Checks to see if an index exists on a table for a given index definition.
@@ -24,7 +48,7 @@ module ActiveRecord
       #  # 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
+      #  # 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
       #
@@ -88,14 +112,16 @@ module ActiveRecord
       # 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)
+        column_names          = Array(column_name)
+        index_name            = index_name(table_name, :column => column_names)
+        index_creation_method = nil
 
         if Hash === options # legacy support, since this param was a string
-          index_type = options[:unique] ? "UNIQUE" : ""
+          index_type = options[:unique] ? 'UNIQUE' : ''
+          index_creation_method = options[:concurrently] ? 'CONCURRENTLY' : ''
           index_name = options[:name].to_s if options.key?(:name)
           if supports_partial_index?
-            index_options = options[:where] ? " WHERE #{options[:where]}" : ""
+            index_options = options[:where] ? " WHERE #{options[:where]}" : ''
           end
         else
           index_type = options
@@ -107,9 +133,9 @@ module ActiveRecord
         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_columns = quoted_columns_for_index(column_names, options).join(', ')
 
-        [index_name, index_type, index_columns, index_options]
+        [index_name, index_type, index_creation_method, index_columns, index_options]
       end
       protected :add_index_options
 

data/lib/pg_power.rb

@@ -1,4 +1,5 @@
 require "pg_power/engine"
+require "pg_power/errors"
 
 # Rails engine which allows to use some PostgreSQL features:
 # * Schemas.
@@ -13,4 +14,5 @@ module PgPower
   autoload :Tools
   autoload :Migration
   autoload :ConnectionAdapters
+  autoload :CreateIndexConcurrently
 end

data/lib/pg_power/connection_adapters/postgresql_adapter/foreigner_methods.rb

@@ -1,8 +1,4 @@
 module PgPower # :nodoc:
-  # Raised when an unexpected index exists
-  class IndexExistsError < StandardError
-  end
-
   # Provides methods to extend {ActiveRecord::ConnectionAdapters::PostgreSQLAdapter}
   # to support foreign keys feature.
   module ConnectionAdapters::PostgreSQLAdapter::ForeignerMethods
@@ -70,30 +66,51 @@ module PgPower # :nodoc:
     #
     # Ensures that an index is created for the foreign key, unless :exclude_index is true.
     #
-    # Raises a [PgPower::IndexExistsError] when :exclude_index is true, but the index already exists.
-    #
     # == Options:
     # * :column
     # * :primary_key
     # * :dependent
-    # * :exclude_index [Boolean]
+    # * :exclude_index    [Boolean]
+    # * :concurrent_index [Boolean]
     #
-    # @param [String, Symbol] from_table
-    # @param [String, Symbol] to_table
-    # @param [Hash] options
+    # @param [String, Symbol]          from_table
+    # @param [String, Symbol]          to_table
+    # @param [Hash]                    options
+    # @option options [String, Symbol] :column
+    # @option options [String, Symbol] :primary_key
+    # @option options [Hash]           :dependent
+    # @option options [Boolean]        :exclude_index
+    # @option options [Boolean]        :concurrent_index
     #
+    # @raise [PgPower::IndexExistsError] when :exclude_index is true, but the index already exists
     def add_foreign_key(from_table, to_table, options = {})
-      options[:column] ||= id_column_name_from_table_name(to_table)
-      options[:exclude_index] ||= false
+      options[:column]             ||= id_column_name_from_table_name(to_table)
+      options[:exclude_index]      ||= false
 
-      if index_exists?(from_table, options[:column]) and !options[:exclude_index]
-        raise PgPower::IndexExistsError, "The index, #{index_name(from_table, options[:column])}, already exists.  Use :exclude_index => true when adding the foreign key."
+      if index_exists?(from_table, options[:column]) && !options[:exclude_index]
+        raise PgPower::IndexExistsError,
+          "The index, #{index_name(from_table, options[:column])}, already exists." \
+          "  Use :exclude_index => true when adding the foreign key."
       end
 
       sql = "ALTER TABLE #{quote_table_name(from_table)} #{add_foreign_key_sql(from_table, to_table, options)}"
       execute(sql)
 
-      add_index(from_table, options[:column]) unless options[:exclude_index]
+      # GOTCHA:
+      #   Index can not be created concurrently inside transaction in PostgreSQL.
+      #   So, in case of concurrently created index with foreign key only
+      #   foreign key will be created inside migration transaction and after
+      #   closing transaction queries for index creation will be send to database.
+      #   That's why I prevent here normal index creation in case of
+      #   `concurrent_index` option is given.
+      #   NOTE: Index creation after closing migration transaction could lead
+      #   to weird effects when transaction moves smoothly, but index
+      #   creation with error. In that case transaction will not be rolled back.
+      #   As it was closed before even index was attempted to create.
+      #   -- zekefast 2012-09-12
+      unless options[:exclude_index] || options[:concurrent_index]
+        add_index(from_table, options[:column])
+      end
     end
 
     # Returns chunk of SQL to add foreign key based on table names and options.
@@ -130,13 +147,13 @@ module PgPower # :nodoc:
     #
     def remove_foreign_key(from_table, to_table_or_options_hash, options={})
       if Hash === to_table_or_options_hash
-        options = to_table_or_options_hash
-        column = options[:column]
-        foreign_key_name = foreign_key_name(from_table, column, options)
-        column ||= id_column_name_from_foreign_key_metadata(from_table, foreign_key_name)
+        options          =   to_table_or_options_hash
+        column           =   options[:column]
+        foreign_key_name =   foreign_key_name(from_table, column, options)
+        column           ||= id_column_name_from_foreign_key_metadata(from_table, foreign_key_name)
       else
-        column = id_column_name_from_table_name(to_table_or_options_hash)
-        foreign_key_name = foreign_key_name(from_table, column)
+        column           =   id_column_name_from_table_name(to_table_or_options_hash)
+        foreign_key_name =   foreign_key_name(from_table, column)
       end
 
       execute "ALTER TABLE #{quote_table_name(from_table)} #{remove_foreign_key_sql(foreign_key_name)}"
@@ -154,7 +171,6 @@ module PgPower # :nodoc:
     def id_column_name_from_table_name(table)
       "#{table.to_s.split('.').last.singularize}_id"
     end
-    private :id_column_name_from_table_name
 
     # Extracts the foreign key column id from the foreign key metadata
     # @param [String, Symbol] from_table
@@ -165,7 +181,7 @@ module PgPower # :nodoc:
       this_key.options[:column]
     end
     private :id_column_name_from_foreign_key_metadata
-    
+
     # Builds default name for constraint
     def foreign_key_name(table, column, options = {})
       if options[:name]

data/lib/pg_power/create_index_concurrently.rb

@@ -0,0 +1,221 @@
+# Adds ability to configure in migration how index will be created.
+# See more details how to create index concurrently in PostgreSQL at
+# (see http://www.postgresql.org/docs/9.2/static/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY).
+#
+# There are several things you should be aware when use option to create index
+# concurrently.
+# Index can not be created concurrently inside transaction and such indexes
+# creation will be postponed till migration transaction will be closed.
+# In case of migration failure and transaction was rolled back indexes will not
+# be created concurrently. But if indexes which should be created concurrently
+# run with errors migration's transaction won't be rolled back. Error in that
+# case will be raised and migration process will be stoped.
+#
+# Migrations can not ensure that all indexes that tend to be created
+# concurrently were created even if the query for such index creation run
+# without errors. Such indexes creation are deferred because of its nature.
+# So, it's up to you to ensure that indexes was really created or remove
+# partially created invalid indexes.
+#
+# :concurrent_index option conflicts with :exclude_index option in method
+# `add_foreign_key`. So, if you put them together exception will be raised.
+#
+# @example
+#
+#   class AddIndexToNameForUsers < ActiveRecord::Migration
+#     def change
+#       add_index :users, :name, :concurrently => true
+#     end
+#   end
+#
+#   # or with foreign key
+#
+#   class AddForeignKeyToRoleIdForUsers < ActiveRecord::Migration
+#     def change
+#       add_foreign_key :users, :roles, :concurrent_index => true
+#     end
+#   end
+#
+module PgPower::CreateIndexConcurrently
+  # Provides ability to postpone index creation queries in migrations.
+  #
+  # Overrides `add_index` and `add_foreign_key` methods for migration to be
+  # able to prevent indexes creation inside scope of transaction if they have to
+  # be created concurrently.
+  # Allows to run creation of postponed indexes.
+  #
+  # This module included into ActiveRecord::Migration class to extend it with
+  # new features.
+  #
+  # All postponed index creation queries are stored inside migration instance.
+  module Migration
+    # @attribute postponed_queries
+    #   @return [Array] list of arguments to call `add_index` method.
+    # @private
+    attr_accessor :postponed_queries
+    private :postponed_queries, :postponed_queries=
+
+
+    # Adds a new index to the table.  +column_name+ can be a single Symbol, or
+    # an Array of Symbols.
+    #
+    # @param [Symbol, String]                        table_name
+    # @param [Symbol, String, Array<Symbol, String>] column_name
+    # @param [optional, Hash]                        options
+    # @option options [Boolean] :unique
+    # @option options [Boolean] :concurrently
+    # @option options [String]  :where
+    #
+    # @return [nil]
+    #
+    # @see ActiveRecord::ConnectionAdapters::SchemaStatements.add_index in pg_power gem
+    def add_index(table_name, column_name, options = {}, &block)
+      table_name = ::ActiveRecord::Migrator.proper_table_name(table_name)
+      # GOTCHA:
+      #   checks if index should be created concurretnly then put it into
+      #   the queue to wait till queue processing will be called (should be
+      #   happended after closing transaction).
+      #   Otherwise just delegate call to PgPower's `add_index`.
+      #   Block is given for future compatibility.
+      #   -- zekefast 2012-09-12
+      unless options[:concurrently]
+        return connection.add_index(table_name, column_name, options, &block)
+      end
+
+      enque(table_name, column_name, options, &block)
+      nil
+    end
+
+    # Adds foreign key.
+    #
+    # == Options:
+    # * :column
+    # * :primary_key
+    # * :dependent
+    # * :exclude_index    [Boolean]
+    # * :concurrent_index [Boolean]
+    #
+    # @param [String, Symbol]          from_table
+    # @param [String, Symbol]          to_table
+    # @param [Hash]                    options
+    # @option options [String, Symbol] :column
+    # @option options [String, Symbol] :primary_key
+    # @option options [Hash]           :dependent
+    # @option options [Boolean]        :exclude_index
+    # @option options [Boolean]        :concurrent_index
+    #
+    # @raise [ArgumentError] in case of conflicted option were set
+    #
+    # @see ::PgPower::ConnectionAdapters::PostgreSQLAdapter::ForeignerMethods.add_foreign_key
+    def add_foreign_key(from_table, to_table, options = {}, &block)
+      from_table = ::ActiveRecord::Migrator.proper_table_name(from_table)
+      if options[:concurrent_index]
+        if options[:exclude_index]
+          raise ArgumentError, 'Conflicted options(exclude_index, concurrent_index) was found, both are set to true.'
+        end
+
+        options[:column] ||= connection.id_column_name_from_table_name(to_table)
+        options = options.merge(:concurrently => options[:concurrent_index])
+        enque(from_table, options[:column], options)
+      end
+
+      # GOTCHA:
+      #   proceed foreign key creation, but giving :concurrent_index => true
+      #   prevent normal index creation in PgPower's `add_foreign_key`.
+      #   So, postponed creation could be done after transaction.
+      #   -- zekefast 2012-09-12
+      connection.add_foreign_key(from_table, to_table, options, &block)
+    end
+
+    # Execute all postponed index creation.
+    #
+    # @return [::PgPower::CreateIndexConcurrently::Migration]
+    def process_postponed_queries
+      Array(@postponed_queries).each do |arguments, block|
+        connection.add_index(*arguments, &block)
+      end
+
+      clear_queue
+
+      self
+    end
+
+    # Clean postponed queries' queue.
+    #
+    # @return [::PgPower::CreateIndexConcurrently::Migration] migration
+    def clear_queue
+      @postponed_queries = []
+
+      self
+    end
+    private :clear_queue
+
+    # Add to the queue add_index call parameters to be able execute call later.
+    #
+    # @param [Array] arguments
+    # @param [Proc]  block
+    #
+    # @return [::PgPower::CreateIndexConcurrently::Migration]
+    def enque(*arguments, &block)
+      @postponed_queries ||= []
+      @postponed_queries << [arguments, block]
+
+      self
+    end
+    private :enque
+  end
+
+  # Allows to call `process_postponed_queries` on MigrationProxy instances.
+  # So, (see ::PgPower::CreateIndexConcurrently::Migrator) could run index
+  # creation concurrently.
+  #
+  # Default delegation in (see ActiveRecord::MigrationProxy) allows to call
+  # only several methods.
+  module MigrationProxy
+    def self.included(klass)
+      klass.delegate :process_postponed_queries, :to => :migration
+    end
+  end
+
+  # Runs posponed index creation for each migration.
+  #
+  # This module included into (see ::ActiveRecord::Migrator) class to make possible
+  # to execute queries for postponed index creation after closing migration's
+  # transaction.
+  #
+  # @see ::ActiveRecord::Migrator.migrate
+  # @see ::ActiveRecord::Migrator.ddl_transaction
+  module Migrator
+    extend ActiveSupport::Concern
+
+    def self.included(klass)
+      klass.alias_method_chain :ddl_transaction, :postponed_queries
+    end
+
+    # Override (see ::ActiveRecord::Migrator.ddl_transaction) to call
+    # (see ::PgPower::CreateIndexConcurrently::Migration.process_postponed_queries)
+    # immediately after transaction.
+    #
+    # @see ::ActiveRecord::Migrator.ddl_transaction
+    def ddl_transaction_with_postponed_queries(*args, &block)
+      ddl_transaction_without_postponed_queries(*args, &block)
+
+      # GOTCHA:
+      #   This might be a bit tricky, but I've decided that this is the best
+      #   way to retrieve migration instance after closing transaction.
+      #   The problem that (see ::ActiveRecord::Migrator) doesn't provide any
+      #   access to recently launched migration. All logic to iterate through
+      #   set of migrations incapsulated in (see ::ActiveRecord::Migrator.migrate)
+      #   method.
+      #   So, to get access to migration you need to override `migrate` method
+      #   and duplicated all logic inside it, plus add call to
+      #   `process_postponed_queries`.
+      #   I've decided this is less forward compatible then retrieving
+      #   value of `migration` variable in context where block
+      #   given to `ddl_transaction` method was created.
+      #   -- zekefast 2012-09-12
+      migration = block.binding.eval('migration')
+      migration.process_postponed_queries
+    end
+  end
+end

data/lib/pg_power/engine.rb

@@ -9,12 +9,10 @@ module PgPower
          'errors',
          'connection_adapters/postgresql_adapter',
          'connection_adapters/abstract/schema_statements'].each do |path|
-          require PgPower::Engine.root + 'lib/core_ext/active_record/' + path
+          require ::PgPower::Engine.root + 'lib/core_ext/active_record/' + path
         end
 
-        ActiveRecord::SchemaDumper.class_eval do
-          include PgPower::SchemaDumper
-        end
+        ActiveRecord::SchemaDumper.class_eval { include ::PgPower::SchemaDumper }
 
         if defined?(ActiveRecord::Migration::CommandRecorder)
           ActiveRecord::Migration::CommandRecorder.class_eval do
@@ -22,12 +20,24 @@ module PgPower
           end
         end
 
+        # Follow three include statements add support for concurrently
+        #   index creation in migrations.
+        ActiveRecord::Migration.class_eval do
+          include ::PgPower::CreateIndexConcurrently::Migration
+        end
+        ActiveRecord::Migrator.class_eval do
+          include ::PgPower::CreateIndexConcurrently::Migrator
+        end
+        ActiveRecord::MigrationProxy.class_eval do
+          include ::PgPower::CreateIndexConcurrently::MigrationProxy
+        end
+
         ActiveRecord::ConnectionAdapters::Table.module_eval do
-          include PgPower::ConnectionAdapters::Table
+          include ::PgPower::ConnectionAdapters::Table
         end
 
         ActiveRecord::ConnectionAdapters::AbstractAdapter.module_eval do
-          include PgPower::ConnectionAdapters::AbstractAdapter
+          include ::PgPower::ConnectionAdapters::AbstractAdapter
         end
 
         if defined?(ActiveRecord::ConnectionAdapters::JdbcAdapter)
@@ -37,7 +47,7 @@ module PgPower
         end
 
         sql_adapter_class.class_eval do
-          include PgPower::ConnectionAdapters::PostgreSQLAdapter
+          include ::PgPower::ConnectionAdapters::PostgreSQLAdapter
         end
 
       end

data/lib/pg_power/errors.rb

@@ -0,0 +1,6 @@
+module PgPower # :nodoc:
+
+  # Raised when an unexpected index exists
+  class IndexExistsError < StandardError; end
+
+end

data/lib/pg_power/tools.rb

@@ -38,7 +38,7 @@ module PgPower
 
 
 
-    # Return databas connections
+    # Return database connections
     def connection
       ActiveRecord::Base.connection
     end

data/lib/pg_power/version.rb

@@ -1,4 +1,4 @@
 module PgPower
   # Version of pg_power gem.
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_power
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-12 00:00:00.000000000 Z
+date: 2012-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -173,7 +173,9 @@ files:
 - lib/pg_power/connection_adapters/table.rb
 - lib/pg_power/connection_adapters/table/comment_methods.rb
 - lib/pg_power/connection_adapters/table/foreigner_methods.rb
+- lib/pg_power/create_index_concurrently.rb
 - lib/pg_power/engine.rb
+- lib/pg_power/errors.rb
 - lib/pg_power/migration.rb
 - lib/pg_power/migration/command_recorder.rb
 - lib/pg_power/migration/command_recorder/comment_methods.rb
@@ -200,7 +202,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3609710966930791506
+      hash: -621483421206137072
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: