Merge pull request rails#46192 from alpaca-tc/support_unique_constraints

Add support for unique constraints (PostgreSQL-only).

Author: yahonda

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?