Adds support USING INDEX for unique constraints in PostgreSQL.

Adds `:using_index` option to use an existing index when defining a unique constraint.
If you want to change an existing unique index to deferrable, you can use :using_index to create deferrable unique constraints.

```ruby
add_unique_key :users, deferrable: :immediate, using_index: 'unique_index_name'
```

A unique constraint internally constructs a unique index.
If an existing unique index has already been created, the unique constraint
can be created much faster, since there is no need to create the unique index
when generating the constraint.

Author: alpaca-tc

activerecord/CHANGELOG.md

@@ -228,11 +228,12 @@
     add_unique_key :items, [:position], deferrable: :deferred
     ```
 
-    PostgreSQL allows users to create a unique constraints on top of the unique
-    index that cannot be deferred. In this case, even if users creates deferrable
-    unique constraint, the existing unique index does not allow users to violate uniqueness
-    within the transaction. If you want to change existing unique index to deferrable,
-    you need execute `remove_index` before creating deferrable unique constraints.
+    If you want to change an existing unique index to deferrable, you can use :using_index
+    to create deferrable unique constraints.
+
+    ```ruby
+    add_unique_key :items, deferrable: :deferred, using_index: "index_items_on_position"
+    ```
 
     *Hiroyuki Ishii*
 

activerecord/lib/active_record/connection_adapters/postgresql/schema_creation.rb

@@ -53,7 +53,12 @@ def visit_UniqueKeyDefinition(o)
             sql = ["CONSTRAINT"]
             sql << quote_column_name(o.name)
             sql << "UNIQUE"
-            sql << "(#{column_name})"
+
+            if o.using_index
+              sql << "USING INDEX #{quote_column_name(o.using_index)}"
+            else
+              sql << "(#{column_name})"
+            end
 
             if o.deferrable
               sql << "DEFERRABLE INITIALLY #{o.deferrable.to_s.upcase}"

activerecord/lib/active_record/connection_adapters/postgresql/schema_definitions.rb

@@ -220,6 +220,10 @@ def deferrable
           options[:deferrable]
         end
 
+        def using_index
+          options[:using_index]
+        end
+
         def export_name_on_schema_dump?
           !ActiveRecord::SchemaDumper.unique_ignore_pattern.match?(name) if name
         end

activerecord/lib/active_record/connection_adapters/postgresql/schema_statements.rb

@@ -700,24 +700,24 @@ def remove_exclusion_constraint(table_name, expression = nil, **options)
 
         # Adds a new unique constraint to the table.
         #
-        # PostgreSQL allows users to create a unique constraints on top of the unique index
-        # that cannot be deferred. In this case, even if users creates deferrable unique constraint,
-        # the existing unique index does not allow users to violate uniqueness within the transaction.
-        # If you want to change existing unique index to deferrable, you need execute `remove_index`
-        # before creating deferrable unique constraints.
-        #
         #   add_unique_key :sections, [:position], deferrable: :deferred, name: "unique_position"
         #
         # generates:
         #
         #   ALTER TABLE "sections" ADD CONSTRAINT unique_position UNIQUE (position) DEFERRABLE INITIALLY DEFERRED
         #
+        # If you want to change an existing unique index to deferrable, you can use :using_index to create deferrable unique constraints.
+        #
+        #   add_unique_key :sections, deferrable: :deferred, name: "unique_position", using_index: "index_sections_on_position"
+        #
         # The +options+ hash can include the following keys:
         # [<tt>:name</tt>]
         #   The constraint name. Defaults to <tt>uniq_rails_<identifier></tt>.
         # [<tt>:deferrable</tt>]
         #   Specify whether or not the unique constraint should be deferrable. Valid values are +false+ or +:immediate+ or +:deferred+ to specify the default behavior. Defaults to +false+.
-        def add_unique_key(table_name, column_name, **options)
+        # [<tt>:using_index</tt>]
+        #   To specify an existing unique index name. Defaults to +nil+.
+        def add_unique_key(table_name, column_name = nil, **options)
           options = unique_key_options(table_name, column_name, options)
           at = create_alter_table(table_name)
           at.add_unique_key(column_name, options)
@@ -728,6 +728,10 @@ def add_unique_key(table_name, column_name, **options)
         def unique_key_options(table_name, column_name, options) # :nodoc:
           assert_valid_deferrable(options[:deferrable])
 
+          if column_name && options[:using_index]
+            raise ArgumentError, "Cannot specify both column_name and :using_index options."
+          end
+
           options = options.dup
           options[:name] ||= unique_key_name(table_name, column_name: column_name, **options)
           options
@@ -1016,8 +1020,8 @@ def exclusion_constraint_for!(table_name, expression: nil, **options)
 
           def unique_key_name(table_name, **options)
             options.fetch(:name) do
-              column_name = options.fetch(:column_name)
-              identifier = "#{table_name}_#{column_name}_unique"
+              column_name_or_index_name = options.fetch(:column_name) || options[:using_index]
+              identifier = "#{table_name}_#{column_name_or_index_name}_unique"
               hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
 
               "uniq_rails_#{hashed_identifier}"

activerecord/lib/active_record/migration/command_recorder.rb

@@ -318,6 +318,13 @@ def invert_remove_exclusion_constraint(args)
           super
         end
 
+        def invert_add_unique_key(args)
+          options = args.dup.extract_options!
+
+          raise ActiveRecord::IrreversibleMigration, "add_unique_key is not reversible if given an using_index." if options[:using_index]
+          super
+        end
+
         def invert_remove_unique_key(args)
           _table, columns = args.dup.tap(&:extract_options!)
 

activerecord/test/cases/migration/command_recorder_test.rb

@@ -471,6 +471,12 @@ def test_invert_remove_check_constraint_without_expression
         end
       end
 
+      def test_invert_add_unique_key_constraint_with_using_index
+        assert_raises(ActiveRecord::IrreversibleMigration) do
+          @recorder.inverse_of :add_unique_key, [:dogs, using_index: "unique_index"]
+        end
+      end
+
       def test_invert_remove_unique_key_constraint
         enable = @recorder.inverse_of :remove_unique_key, [:dogs, ["speed"], deferrable: :deferred, name: "uniq_speed"]
         assert_equal [:add_unique_key, [:dogs, ["speed"], deferrable: :deferred, name: "uniq_speed"], nil], enable

activerecord/test/cases/migration/unique_key_test.rb

@@ -147,6 +147,42 @@ def test_added_deferrable_initially_immediate_unique_key
           end
         end
 
+        def test_add_unique_key_with_name_and_using_index
+          @connection.add_index :sections, [:position], name: "unique_index", unique: true
+          @connection.add_unique_key :sections, name: "unique_constraint", deferrable: :immediate, using_index: "unique_index"
+
+          unique_keys = @connection.unique_keys("sections")
+          assert_equal 1, unique_keys.size
+
+          constraint = unique_keys.first
+          assert_equal "sections", constraint.table_name
+          assert_equal "unique_constraint", constraint.name
+          assert_equal ["position"], constraint.columns
+          assert_equal :immediate, constraint.deferrable
+        end
+
+        def test_add_unique_key_with_only_using_index
+          @connection.add_index :sections, [:position], name: "unique_index", unique: true
+          @connection.add_unique_key :sections, using_index: "unique_index"
+
+          unique_keys = @connection.unique_keys("sections")
+          assert_equal 1, unique_keys.size
+
+          constraint = unique_keys.first
+          assert_equal "sections", constraint.table_name
+          assert_equal "uniq_rails_79b901ffb4", constraint.name
+          assert_equal ["position"], constraint.columns
+          assert_equal false, constraint.deferrable
+        end
+
+        def test_add_unique_key_with_columns_and_using_index
+          @connection.add_index :sections, [:position], name: "unique_index", unique: true
+
+          assert_raises(ArgumentError) do
+            @connection.add_unique_key :sections, [:position], using_index: "unique_index"
+          end
+        end
+
         def test_remove_unique_key
           assert_equal 0, @connection.unique_keys("sections").size