From 0b2717f70e45899d43049f16cb74c8381ab9e2ec Mon Sep 17 00:00:00 2001
From: Mikhail Nikalayeu <mihailnikalayeu@gmail.com>
Date: Tue, 28 Oct 2025 01:16:13 +0100
Subject: [PATCH v1] doc: Document potential failure scenarios for concurrent
 `INSERT ... ON CONFLICT` during CONCURRENTLY index operation on the same
 table.

Author: Mikhail Nikalayeu <mihailnikalayeu@gmail.com>
Reviewed-by: Noah Misch <noah@leadboat.com>
Discussion: https://postgr.es/m/CANtu0ojXmqjmEzp-=aJSxjsdE76iAsRgHBoK0QtYHimb_mEfsg@mail.gmail.com
---
 doc/src/sgml/ref/create_index.sgml | 10 ++++++++++
 doc/src/sgml/ref/insert.sgml       | 17 +++++++++++++++++
 doc/src/sgml/ref/reindex.sgml      | 11 +++++++++++
 3 files changed, 38 insertions(+)

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index b9c679c41e8..5ae7f1a1520 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -707,6 +707,16 @@ Indexes:
     partitioned index is a metadata only operation.
    </para>
 
+   <warning>
+     <para>
+       While <command>CREATE INDEX CONCURRENTLY</command> is running on a unique
+       index, concurrent <command>INSERT ... ON CONFLICT</command> statement on
+       the same table that uses an index compatible with the index being built
+       may unexpectedly fail with duplicate key constraint violation error.
+       See <xref linkend="sql-on-conflict"/> for more details.
+     </para>
+   </warning>
+
   </refsect2>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 3f139917790..dc4b341ca3e 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -594,6 +594,23 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
     </para>
    </tip>
 
+   <warning>
+    <para>
+      If <command>CREATE INDEX CONCURRENTLY</command> or <command>REINDEX
+      CONCURRENTLY</command> is running on a unique index (or on a table
+      containing unique indexes), concurrent <command>INSERT ... ON CONFLICT</command>
+      statements on the same table may unexpectedly fail with duplicate key
+      constraint violation errors. This can occur when the statement uses an
+      index that is either compatible with the index being built or rebuilt,
+      or is itself being reindexed. Both <literal>DO UPDATE</literal> and
+      <literal>DO NOTHING</literal> conflict actions are affected.
+    </para>
+    <para>
+      These failures only occur during a brief window when the system catalogs
+      are being modified, not throughout the entire index build or rebuild process.
+    </para>
+   </warning>
+
   </refsect2>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index c4055397146..9b65b81615e 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -513,6 +513,17 @@ Indexes:
     in the <structname>pg_stat_progress_create_index</structname> view. See
     <xref linkend="create-index-progress-reporting"/> for details.
   </para>
+
+  <warning>
+    <para>
+      While <command>REINDEX CONCURRENTLY</command> is running on a unique
+      index or on a table containing unique indexes, concurrent
+      <command>INSERT ... ON CONFLICT</command> statement on the same table
+      that uses an index compatible with any of the indexes being rebuilt
+      may unexpectedly fail with duplicate key constraint violation errors.
+      See <xref linkend="sql-on-conflict"/> for more details.
+    </para>
+   </warning>
   </refsect2>
  </refsect1>
 
-- 
2.43.0