From 6313ebe09f3fe0e68ee5cb9f3eb25a23ad28a621 Mon Sep 17 00:00:00 2001
From: Rui Zhao <zhaorui126@gmail.com>
Date: Fri, 11 Sep 2026 00:35:47 +0800
Subject: [PATCH] Document two things about toast_value_type = oid8

A partitioned table rejects the parameter like any other storage
parameter, and a partition does not inherit it from its parent; say so
next to the parameter.

An oid8 TOAST table takes the OID counter's value without checking the
index, so a counter moved below a chunk_id in use makes inserts fail.
Say so under pg_resetwal -o, with the way to find a safe value.
---
 doc/src/sgml/ref/create_table.sgml |  7 +++++++
 doc/src/sgml/ref/pg_resetwal.sgml  | 12 ++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 6f9a87ef44..3de92ffeed 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1679,6 +1679,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       hand, recreates the <acronym>TOAST</acronym> relation and therefore
       applies the current value of this parameter.
      </para>
+     <para>
+      As with any storage parameter, this cannot be set on a partitioned
+      table, and a partition does not inherit it from its parent: a
+      partition created without it gets a <acronym>TOAST</acronym> relation
+      with an <type>oid</type> <literal>chunk_id</literal>.  Specify it on
+      each partition that needs it.
+     </para>
     </listitem>
    </varlistentry>
 
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index d34aa26413..02678eb56f 100644
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -300,6 +300,18 @@ PostgreSQL documentation
       backwards. The counter is 8 bytes wide and never wraps around during
       the life of a cluster.
      </para>
+
+     <para>
+      Tables with <xref linkend="reloption-toast-value-type"/> set to
+      <literal>oid8</literal> are the exception: their
+      <acronym>TOAST</acronym> values take the counter's value as is, so a
+      counter set below a <structfield>chunk_id</structfield> already in use
+      makes inserts into such a table fail with duplicate key errors, and
+      each failure moves the counter forward by only one.  For these tables
+      the largest value in use is easy to find, with
+      <literal>SELECT max(chunk_id)</literal> on each of their
+      <acronym>TOAST</acronym> tables; set the next OID above it.
+     </para>
     </listitem>
    </varlistentry>
 
-- 
2.43.7