Add support for unique constraints (PostgreSQL-only).

```ruby
add_unique_key :sections, [:position], deferrable: :deferred, name: "unique_section_position"
remove_unique_key :sections, name: "unique_section_position"
```

See PostgreSQL's [Unique Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS) documentation for more on unique constraints.

By default, unique constraints in PostgreSQL are checked after each statement.
This works for most use cases, but becomes a major limitation when replacing
records with unique column by using multiple statements.

An example of swapping unique columns between records.

```ruby
old_item = Item.create!(position: 1)
new_item = Item.create!(position: 2)

Item.transaction do
  old_item.update!(position: 2)
  new_item.update!(position: 1)
end
```

Using the default behavior, the transaction would fail when executing the
first `UPDATE` statement.

By passing the `:deferrable` option to the `add_unique_key` statement in
migrations, it's possible to defer this check.

```ruby
add_unique_key :items, [:position], deferrable: :immediate
```

Passing `deferrable: :immediate` does not change the behaviour of the previous example,
but allows manually deferring the check using `SET CONSTRAINTS ALL DEFERRED` within a transaction.
This will cause the unique constraints to be checked after the transaction.

It's also possible to adjust the default behavior from an immediate
check (after the statement), to a deferred check (after the transaction):

```ruby
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.

*Hiroyuki Ishii*

Author: alpaca-tc

activerecord/CHANGELOG.md

@@ -1,3 +1,58 @@
+*   Add support for unique constraints (PostgreSQL-only).
+
+    ```ruby
+    add_unique_key :sections, [:position], deferrable: :deferred, name: "unique_section_position"
+    remove_unique_key :sections, name: "unique_section_position"
+    ```
+
+    See PostgreSQL's [Unique Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS) documentation for more on unique constraints.
+
+    By default, unique constraints in PostgreSQL are checked after each statement.
+    This works for most use cases, but becomes a major limitation when replacing
+    records with unique column by using multiple statements.
+
+    An example of swapping unique columns between records.
+
+    ```ruby
+    # position is unique column
+    old_item = Item.create!(position: 1)
+    new_item = Item.create!(position: 2)
+
+    Item.transaction do
+      old_item.update!(position: 2)
+      new_item.update!(position: 1)
+    end
+    ```
+
+    Using the default behavior, the transaction would fail when executing the
+    first `UPDATE` statement.
+
+    By passing the `:deferrable` option to the `add_unique_key` statement in
+    migrations, it's possible to defer this check.
+
+    ```ruby
+    add_unique_key :items, [:position], deferrable: :immediate
+    ```
+
+    Passing `deferrable: :immediate` does not change the behaviour of the previous example,
+    but allows manually deferring the check using `SET CONSTRAINTS ALL DEFERRED` within a transaction.
+    This will cause the unique constraints to be checked after the transaction.
+
+    It's also possible to adjust the default behavior from an immediate
+    check (after the statement), to a deferred check (after the transaction):
+
+    ```ruby
+    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.
+
+    *Hiroyuki Ishii*
+
 *   Remove deprecated `Tasks::DatabaseTasks.schema_file_type`.
 
     *Rafael Mendonça França*

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

@@ -16,7 +16,8 @@ def accept(o)
       delegate :quote_column_name, :quote_table_name, :quote_default_expression, :type_to_sql,
         :options_include_default?, :supports_indexes_in_create?, :use_foreign_keys?,
         :quoted_columns_for_index, :supports_partial_index?, :supports_check_constraints?,
-        :supports_index_include?, :supports_exclusion_constraints?, to: :@conn, private: true
+        :supports_index_include?, :supports_exclusion_constraints?, :supports_unique_keys?,
+        to: :@conn, private: true
 
       private
         def visit_AlterTable(o)
@@ -63,6 +64,10 @@ def visit_TableDefinition(o)
             statements.concat(o.exclusion_constraints.map { |exc| accept exc })
           end
 
+          if supports_unique_keys?
+            statements.concat(o.unique_keys.map { |exc| accept exc })
+          end
+
           create_sql << "(#{statements.join(', ')})" if statements.present?
           add_table_options!(create_sql, o)
           create_sql << " AS #{to_sql(o.as)}" if o.as

activerecord/lib/active_record/connection_adapters/abstract_adapter.rb

@@ -500,6 +500,11 @@ def supports_exclusion_constraints?
         false
       end
 
+      # Does this adapter support creating unique constraints?
+      def supports_unique_keys?
+        false
+      end
+
       # Does this adapter support views?
       def supports_views?
         false

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

@@ -12,6 +12,8 @@ def visit_AlterTable(o)
             sql << o.constraint_validations.map { |fk| visit_ValidateConstraint fk }.join(" ")
             sql << o.exclusion_constraint_adds.map { |con| visit_AddExclusionConstraint con }.join(" ")
             sql << o.exclusion_constraint_drops.map { |con| visit_DropExclusionConstraint con }.join(" ")
+            sql << o.unique_key_adds.map { |con| visit_AddUniqueKey con }.join(" ")
+            sql << o.unique_key_drops.map { |con| visit_DropUniqueKey con }.join(" ")
           end
 
           def visit_AddForeignKey(o)
@@ -44,6 +46,21 @@ def visit_ExclusionConstraintDefinition(o)
             sql.join(" ")
           end
 
+          def visit_UniqueKeyDefinition(o)
+            column_name = Array(o.columns).map { |column| quote_column_name(column) }.join(", ")
+
+            sql = ["CONSTRAINT"]
+            sql << quote_column_name(o.name)
+            sql << "UNIQUE"
+            sql << "(#{column_name})"
+
+            if o.deferrable
+              sql << "DEFERRABLE INITIALLY #{o.deferrable.to_s.upcase}"
+            end
+
+            sql.join(" ")
+          end
+
           def visit_AddExclusionConstraint(o)
             "ADD #{accept(o)}"
           end
@@ -52,6 +69,14 @@ def visit_DropExclusionConstraint(name)
             "DROP CONSTRAINT #{quote_column_name(name)}"
           end
 
+          def visit_AddUniqueKey(o)
+            "ADD #{accept(o)}"
+          end
+
+          def visit_DropUniqueKey(name)
+            "DROP CONSTRAINT #{quote_column_name(name)}"
+          end
+
           def visit_ChangeColumnDefinition(o)
             column = o.column
             column.sql_type = type_to_sql(column.type, **column.options)

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

@@ -207,26 +207,50 @@ def export_name_on_schema_dump?
         end
       end
 
+      UniqueKeyDefinition = Struct.new(:table_name, :columns, :options) do
+        def name
+          options[:name]
+        end
+
+        def deferrable
+          options[:deferrable]
+        end
+
+        def export_name_on_schema_dump?
+          !ActiveRecord::SchemaDumper.unique_ignore_pattern.match?(name) if name
+        end
+      end
+
       class TableDefinition < ActiveRecord::ConnectionAdapters::TableDefinition
         include ColumnMethods
 
-        attr_reader :exclusion_constraints, :unlogged
+        attr_reader :exclusion_constraints, :unique_keys, :unlogged
 
         def initialize(*, **)
           super
           @exclusion_constraints = []
+          @unique_keys = []
           @unlogged = ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.create_unlogged_tables
         end
 
         def exclusion_constraint(expression, **options)
           exclusion_constraints << new_exclusion_constraint_definition(expression, options)
         end
 
+        def unique_key(column_name, **options)
+          unique_keys << new_unique_key_definition(column_name, options)
+        end
+
         def new_exclusion_constraint_definition(expression, options) # :nodoc:
           options = @conn.exclusion_constraint_options(name, expression, options)
           ExclusionConstraintDefinition.new(name, expression, options)
         end
 
+        def new_unique_key_definition(column_name, options) # :nodoc:
+          options = @conn.unique_key_options(name, column_name, options)
+          UniqueKeyDefinition.new(name, column_name, options)
+        end
+
         def new_column_definition(name, type, **options) # :nodoc:
           case type
           when :virtual
@@ -274,16 +298,36 @@ def exclusion_constraint(*args)
         def remove_exclusion_constraint(*args)
           @base.remove_exclusion_constraint(name, *args)
         end
+
+        # Adds an unique constraint.
+        #
+        #  t.unique_key(:position, name: 'unique_position', deferrable: :deferred)
+        #
+        # See {connection.add_unique_key}[rdoc-ref:SchemaStatements#add_unique_key]
+        def unique_key(*args)
+          @base.add_unique_key(name, *args)
+        end
+
+        # Removes the given unique constraint from the table.
+        #
+        #  t.remove_unique_key(name: "unique_position")
+        #
+        # See {connection.remove_unique_key}[rdoc-ref:SchemaStatements#remove_unique_key]
+        def remove_unique_key(*args)
+          @base.remove_unique_key(name, *args)
+        end
       end
 
       class AlterTable < ActiveRecord::ConnectionAdapters::AlterTable
-        attr_reader :constraint_validations, :exclusion_constraint_adds, :exclusion_constraint_drops
+        attr_reader :constraint_validations, :exclusion_constraint_adds, :exclusion_constraint_drops, :unique_key_adds, :unique_key_drops
 
         def initialize(td)
           super
           @constraint_validations = []
           @exclusion_constraint_adds = []
           @exclusion_constraint_drops = []
+          @unique_key_adds = []
+          @unique_key_drops = []
         end
 
         def validate_constraint(name)
@@ -297,6 +341,14 @@ def add_exclusion_constraint(expression, options)
         def drop_exclusion_constraint(constraint_name)
           @exclusion_constraint_drops << constraint_name
         end
+
+        def add_unique_key(column_name, options)
+          @unique_key_adds << @td.new_unique_key_definition(column_name, options)
+        end
+
+        def drop_unique_key(unique_key_name)
+          @unique_key_drops << unique_key_name
+        end
       end
     end
   end

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

@@ -49,6 +49,26 @@ def exclusion_constraints_in_create(table, stream)
             end
           end
 
+          def unique_keys_in_create(table, stream)
+            if (unique_keys = @connection.unique_keys(table)).any?
+              add_unique_key_statements = unique_keys.map do |unique_key|
+                parts = [
+                  "t.unique_key #{unique_key.columns.inspect}"
+                ]
+
+                parts << "deferrable: #{unique_key.deferrable.inspect}" if unique_key.deferrable
+
+                if unique_key.export_name_on_schema_dump?
+                  parts << "name: #{unique_key.name.inspect}"
+                end
+
+                "    #{parts.join(', ')}"
+              end
+
+              stream.puts add_unique_key_statements.sort.join("\n")
+            end
+          end
+
           def prepare_column_options(column)
             spec = super
             spec[:array] = "true" if column.array?