Add nulls_distinct option for unique indexes (#439)

Author: dsimon-dev

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Enhancements
 
   * [migrations] Support `primary_key` configuration options in `table`
+  * [migrations] Add `:nulls_distinct` option for unique indexes
   * [postgres] Support the use of advisory locks for migrations
   * [sql] Add `dump_cmd` to `postgrex` and `myxql` adapters
   * [sql] Log human-readable UUIDs by using pre-dumped query parameters
@@ -22,7 +23,7 @@
 ### Bug fixes
 
   * [postgres] Fix possible breaking change on `json_extract_path` for boolean values introduced in v3.8.0
-  * [sql] Colorize stacktrace and use `:` before printing line number 
+  * [sql] Colorize stacktrace and use `:` before printing line number
 
 ## v3.8.1 (2022-04-29)
 

lib/ecto/adapters/myxql/connection.ex

@@ -773,6 +773,10 @@ if Code.ensure_loaded?(MyXQL) do
         error!(nil, "MySQL adapter does not support where in indexes")
       end
 
+      if index.nulls_distinct == false do
+        error!(nil, "MySQL adapter does not support nulls_distinct set to false in indexes")
+      end
+
       [["CREATE", if_do(index.unique, " UNIQUE"), " INDEX ",
         quote_name(index.name),
         " ON ",

lib/ecto/adapters/postgres/connection.ex

@@ -908,6 +908,13 @@ if Code.ensure_loaded?(Postgrex) do
       fields = intersperse_map(index.columns, ", ", &index_expr/1)
       include_fields = intersperse_map(index.include, ", ", &index_expr/1)
 
+      maybe_nulls_distinct =
+        case index.nulls_distinct do
+          nil -> []
+          true -> " NULLS DISTINCT"
+          false -> " NULLS NOT DISTINCT"
+        end
+
       queries = [["CREATE ",
                   if_do(index.unique, "UNIQUE "),
                   "INDEX ",
@@ -919,6 +926,7 @@ if Code.ensure_loaded?(Postgrex) do
                   if_do(index.using, [" USING " , to_string(index.using)]),
                   ?\s, ?(, fields, ?),
                   if_do(include_fields != [], [" INCLUDE ", ?(, include_fields, ?)]),
+                  maybe_nulls_distinct,
                   if_do(index.where, [" WHERE ", to_string(index.where)])]]
 
       queries ++ comments_on("INDEX", quote_table(index.prefix, index.name), index.comment)

lib/ecto/adapters/tds/connection.ex

@@ -1069,6 +1069,10 @@ if Code.ensure_loaded?(Tds) do
         error!(nil, "MSSQL does not support `using` in indexes")
       end
 
+      if index.nulls_distinct == true do
+        error!(nil, "MSSQL does not support nulls_distinct set to true in indexes")
+      end
+
       with_options =
         if index.concurrently or index.options != nil do
           [

lib/ecto/migration.ex

@@ -366,6 +366,7 @@ defmodule Ecto.Migration do
               concurrently: false,
               using: nil,
               include: [],
+              nulls_distinct: nil,
               where: nil,
               comment: nil,
               options: nil
@@ -379,6 +380,7 @@ defmodule Ecto.Migration do
       concurrently: boolean,
       using: atom | String.t,
       include: [atom | String.t],
+      nulls_distinct: boolean | nil,
       where: atom | String.t,
       comment: String.t | nil,
       options: String.t
@@ -705,6 +707,12 @@ defmodule Ecto.Migration do
     * `:include` - specify fields for a covering index. This is not supported
       by all databases. For more information on PostgreSQL support, please
       [read the official docs](https://www.postgresql.org/docs/current/indexes-index-only-scans.html).
+    * `:nulls_distinct` - specify whether null values should be considered
+      distinct for a unique index. Defaults to `nil`, which will not add the
+      parameter to the generated SQL and thus use the database default.
+      This option is currently only supported by PostgreSQL 15+.
+      For MySQL, it is always false. For MSSQL, it is always true.
+      See the dedicated section on this option for more information.
     * `:comment` - adds a comment to the index.
 
   ## Adding/dropping indexes concurrently
@@ -763,6 +771,29 @@ defmodule Ecto.Migration do
   More information on partial indexes can be found in the [PostgreSQL
   docs](http://www.postgresql.org/docs/current/indexes-partial.html).
 
+  ## The `:nulls_distinct` option
+
+  A unique index does not prevent multiple null values by default in most databases.
+
+  For example, imagine we have a "products" table and need to guarantee that
+  sku's are unique within their category, but the category is optional.
+  Creating a regular unique index over the sku and category_id fields with:
+
+      create index("products", [:sku, :category_id], unique: true)
+
+  will allow products with the same sku to be inserted if their category_id is `nil`.
+  The `:nulls_distinct` option can be used to change this behavior by considering
+  null values as equal, i.e. not distinct:
+
+      create index("products", [:sku, :category_id], unique: true, nulls_distinct: false)
+
+  This option is currently only supported by PostgreSQL 15+.
+  As a workaround for older PostgreSQL versions and other databases, an
+  additional partial unique index for the sku can be created:
+
+      create index("products", [:sku, :category_id], unique: true)
+      create index("products", [:sku], unique: true, where: "category_id IS NULL")
+
   ## Examples
 
       # With no name provided, the name of the below index defaults to
@@ -1343,6 +1374,10 @@ defmodule Ecto.Migration do
   end
 
   defp validate_index_opts!(opts) when is_list(opts) do
+    if opts[:nulls_distinct] != nil and opts[:unique] != true do
+      raise ArgumentError, "the `nulls_distinct` option can only be used with unique indexes"
+    end
+
     case Keyword.get_values(opts, :where) do
       [_, _ | _] ->
         raise ArgumentError,

test/ecto/adapters/postgres_test.exs

@@ -1779,6 +1779,20 @@ defmodule Ecto.Adapters.PostgresTest do
       [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") INCLUDE ("public") WHERE public IS TRUE|]
   end
 
+  test "create unique index with nulls_distinct option" do
+    create = {:create, index(:posts, [:permalink], unique: true, nulls_distinct: true)}
+    assert execute_ddl(create) ==
+      [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") NULLS DISTINCT|]
+
+    create = {:create, index(:posts, [:permalink], unique: true, nulls_distinct: false)}
+    assert execute_ddl(create) ==
+      [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") NULLS NOT DISTINCT|]
+
+    create = {:create, index(:posts, [:permalink], unique: true, nulls_distinct: false, include: [:public], where: "public IS TRUE")}
+    assert execute_ddl(create) ==
+      [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") INCLUDE ("public") NULLS NOT DISTINCT WHERE public IS TRUE|]
+  end
+
   test "create index concurrently" do
     index = index(:posts, [:permalink])
     create = {:create, %{index | concurrently: true}}

test/ecto/migration_test.exs

@@ -70,6 +70,15 @@ defmodule Ecto.MigrationTest do
            %Index{table: "table_one__table_two", unique: true, name: :table_one__table_two_title_index, columns: [:title]}
   end
 
+  test "raises if nulls_distinct is set for a non-unique index" do
+    assert_raise ArgumentError, fn ->
+      index(:posts, [:title], unique: false, nulls_distinct: false)
+    end
+    assert_raise ArgumentError, fn ->
+      index(:posts, [:title], unique: false, nulls_distinct: true)
+    end
+  end
+
   test "raises if given multiple 'where' clauses for an index" do
     assert_raise ArgumentError, fn ->
       index(:posts, [:title], where: "status = 'published'", where: "deleted = 'false'")