The SQL Language part of the docs has a brief page on unique indexes.
It doesn't mention the new NULLS NOT DISTINCT functionality on unique
indexes and this is a good place to mention it, as it already warns
the user about the old/default behavior.
--
David Gilman
:DG<
From 5cb84716462611b84e6b2fbdb35172ec43b52db8 Mon Sep 17 00:00:00 2001
From: David Gilman <davidgilm...@gmail.com>
Date: Wed, 12 Apr 2023 10:28:09 -0400
Subject: [PATCH] Note NULLS NOT DISTINCT on unique index tutorial
---
doc/src/sgml/indices.sgml | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 0c3fcfd62f8e..0a67e66f5065 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -671,9 +671,11 @@ CREATE UNIQUE INDEX <replaceable>name</replaceable> ON
<replaceable>table</repla
<para>
When an index is declared unique, multiple table rows with equal
- indexed values are not allowed. Null values are not considered
- equal. A multicolumn unique index will only reject cases where all
- indexed columns are equal in multiple rows.
+ indexed values are not allowed. By default, null values in a unique column
+ are not considered equal, allowing multiple nulls in the column.
+ Use <literal>NULLS NOT DISTINCT</literal> to treat column nulls as equal,
+ allowing only a single null value in an indexed column. A multicolumn
unique index
+ will only reject cases where all indexed columns are equal in multiple rows.
</para>
<para>
