Subject: [PATCH] doc: explain database-wide impact of old xmin on VACUUM

Add a note to the "Recovering Disk Space" section explaining that=

VACUUM uses the oldest xmin across backends in the current database

to decide which tuples are dead, so a long-running transaction on any

table can prevent space reclamation for rows newer than that

transaction in any table of the same database. Rows older than the

oldest active transaction can still be reclaimed normally. Also

mention that stale replication slots and prepared transactions have

the same effect.

For shared system catalogs, backends in all databases are considered.

---

Source verification: the database-wide (not cluster-wide) behavior

is implemented in ComputeXidHorizons() in procarray.c, which only

includes backends where proc->databaseId =3D=3D MyDatabaseId for the

data_oldest_nonremovable horizon.

doc/src/sgml/maintenance.sgml | 18 ++++++++++++++++++

1 file changed, 18 insertions(+)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml<= /div>

index 4a21bdb..5963ba1 100644

--- a/doc/src/sgml/maintenance.sgml

+++ b/doc/src/sgml/maintenance.sgml

@@ -165,6 +165,24 @@

space requirements. This is done by running <command= >VACUUM</command>.

</para>

+ <note>

+ <para>

+ To decide which row versions can be removed,

+ <command>VACUUM</command> considers the oldest = active transaction

+ ID (<firstterm>xmin</firstterm>) across backend= s in the current

+ database. Because of this, a long-running transaction on on= e table

+ can prevent <command>VACUUM</command> from recl= aiming space

+ occupied by rows that are newer than that transaction in

+ <emphasis>any</emphasis> table in the same data= base. For rows

+ older than the oldest active transaction,

+ <command>VACUUM</command> can still reclaim the= m normally. Stale

+ replication slots and abandoned prepared transactions have = the

+ same effect, since they also hold old xmin values that bloc= k

+ cleanup. Note that for shared system catalogs, backends in = all

+ databases are considered. For troubleshooting, see

+ <xref linkend=3D"vacuum-for-wraparound"/>.<= /div>

+ </para>

+ </note>

<para>

The standard form of <command>VACUUM</command&= gt; removes dead row

versions in tables and indexes and marks the space avai= lable for

Best regards,

Zhilong Liu

--_000_OS3PR01MB8553C5907830DE25A8A4986ED9152OS3PR01MB8553jpnp_-- --_004_OS3PR01MB8553C5907830DE25A8A4986ED9152OS3PR01MB8553jpnp_ Content-Type: application/octet-stream; name="0001-doc-explain-database-wide-impact-of-old-xmin-on-VACU.patch" Content-Description: 0001-doc-explain-database-wide-impact-of-old-xmin-on-VACU.patch Content-Disposition: attachment; filename="0001-doc-explain-database-wide-impact-of-old-xmin-on-VACU.patch"; size=2513; creation-date="Mon, 01 Jun 2026 03:50:38 GMT"; modification-date="Mon, 01 Jun 2026 03:50:38 GMT" Content-Transfer-Encoding: base64 RnJvbSAxYTJiM2M0ZDVlNmY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyIE1vbiBTZXAgMTcg MDA6MDA6MDAgMjAwMQpGcm9tOiBaaGlsb25nIExpdSA8bGl1emhpbG9uZzYyQG91dGxvb2suY29t PgpEYXRlOiBUaHUsIDI4IE1heSAyMDI2IDE3OjUyOjQxICswODAwClN1YmplY3Q6IFtQQVRDSF0g ZG9jOiBleHBsYWluIGRhdGFiYXNlLXdpZGUgaW1wYWN0IG9mIG9sZCB4bWluIG9uIFZBQ1VVTQoK QWRkIGEgbm90ZSB0byB0aGUgIlJlY292ZXJpbmcgRGlzayBTcGFjZSIgc2VjdGlvbiBleHBsYWlu aW5nIHRoYXQKVkFDVVVNIHVzZXMgdGhlIG9sZGVzdCB4bWluIGFjcm9zcyBiYWNrZW5kcyBpbiB0 aGUgY3VycmVudCBkYXRhYmFzZQp0byBkZWNpZGUgd2hpY2ggdHVwbGVzIGFyZSBkZWFkLCBzbyBh IGxvbmctcnVubmluZyB0cmFuc2FjdGlvbiBvbiBhbnkKdGFibGUgY2FuIHByZXZlbnQgc3BhY2Ug cmVjbGFtYXRpb24gZm9yIHJvd3MgbmV3ZXIgdGhhbiB0aGF0CnRyYW5zYWN0aW9uIGluIGFueSB0 YWJsZSBvZiB0aGUgc2FtZSBkYXRhYmFzZS4gUm93cyBvbGRlciB0aGFuIHRoZQpvbGRlc3QgYWN0 aXZlIHRyYW5zYWN0aW9uIGNhbiBzdGlsbCBiZSByZWNsYWltZWQgbm9ybWFsbHkuIEFsc28KbWVu dGlvbiB0aGF0IHN0YWxlIHJlcGxpY2F0aW9uIHNsb3RzIGFuZCBwcmVwYXJlZCB0cmFuc2FjdGlv bnMgaGF2ZQp0aGUgc2FtZSBlZmZlY3QuCgpGb3Igc2hhcmVkIHN5c3RlbSBjYXRhbG9ncywgYmFj a2VuZHMgaW4gYWxsIGRhdGFiYXNlcyBhcmUgY29uc2lkZXJlZC4KLS0tClNvdXJjZSB2ZXJpZmlj YXRpb246IHRoZSBkYXRhYmFzZS13aWRlIChub3QgY2x1c3Rlci13aWRlKSBiZWhhdmlvcgppcyBp bXBsZW1lbnRlZCBpbiBDb21wdXRlWGlkSG9yaXpvbnMoKSBpbiBwcm9jYXJyYXkuYywgd2hpY2gg b25seQppbmNsdWRlcyBiYWNrZW5kcyB3aGVyZSBwcm9jLT5kYXRhYmFzZUlkID09IE15RGF0YWJh c2VJZCBmb3IgdGhlCmRhdGFfb2xkZXN0X25vbnJlbW92YWJsZSBob3Jpem9uLgoKIGRvYy9zcmMv c2dtbC9tYWludGVuYW5jZS5zZ21sIHwgMTggKysrKysrKysrKysrKysrKysrCiAxIGZpbGUgY2hh bmdlZCwgMTggaW5zZXJ0aW9ucygrKQoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9tYWludGVu YW5jZS5zZ21sIGIvZG9jL3NyYy9zZ21sL21haW50ZW5hbmNlLnNnbWwKaW5kZXggNGEyMWJkYi4u NTk2M2JhMSAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL21haW50ZW5hbmNlLnNnbWwKKysrIGIv ZG9jL3NyYy9zZ21sL21haW50ZW5hbmNlLnNnbWwKQEAgLTE2NSw2ICsxNjUsMjQgQEAKICAgICBz cGFjZSByZXF1aXJlbWVudHMuIFRoaXMgaXMgZG9uZSBieSBydW5uaW5nIDxjb21tYW5kPlZBQ1VV TTwvY29tbWFuZD4uCiAgICA8L3BhcmE+CiAKKyAgIDxub3RlPgorICAgIDxwYXJhPgorICAgICBU byBkZWNpZGUgd2hpY2ggcm93IHZlcnNpb25zIGNhbiBiZSByZW1vdmVkLAorICAgICA8Y29tbWFu ZD5WQUNVVU08L2NvbW1hbmQ+IGNvbnNpZGVycyB0aGUgb2xkZXN0IGFjdGl2ZSB0cmFuc2FjdGlv bgorICAgICBJRCAoPGZpcnN0dGVybT54bWluPC9maXJzdHRlcm0+KSBhY3Jvc3MgYmFja2VuZHMg aW4gdGhlIGN1cnJlbnQKKyAgICAgZGF0YWJhc2UuIEJlY2F1c2Ugb2YgdGhpcywgYSBsb25nLXJ1 bm5pbmcgdHJhbnNhY3Rpb24gb24gb25lIHRhYmxlCisgICAgIGNhbiBwcmV2ZW50IDxjb21tYW5k PlZBQ1VVTTwvY29tbWFuZD4gZnJvbSByZWNsYWltaW5nIHNwYWNlCisgICAgIG9jY3VwaWVkIGJ5 IHJvd3MgdGhhdCBhcmUgbmV3ZXIgdGhhbiB0aGF0IHRyYW5zYWN0aW9uIGluCisgICAgIDxlbXBo YXNpcz5hbnk8L2VtcGhhc2lzPiB0YWJsZSBpbiB0aGUgc2FtZSBkYXRhYmFzZS4gRm9yIHJvd3MK KyAgICAgb2xkZXIgdGhhbiB0aGUgb2xkZXN0IGFjdGl2ZSB0cmFuc2FjdGlvbiwKKyAgICAgPGNv bW1hbmQ+VkFDVVVNPC9jb21tYW5kPiBjYW4gc3RpbGwgcmVjbGFpbSB0aGVtIG5vcm1hbGx5LiBT dGFsZQorICAgICByZXBsaWNhdGlvbiBzbG90cyBhbmQgYWJhbmRvbmVkIHByZXBhcmVkIHRyYW5z YWN0aW9ucyBoYXZlIHRoZQorICAgICBzYW1lIGVmZmVjdCwgc2luY2UgdGhleSBhbHNvIGhvbGQg b2xkIHhtaW4gdmFsdWVzIHRoYXQgYmxvY2sKKyAgICAgY2xlYW51cC4gTm90ZSB0aGF0IGZvciBz aGFyZWQgc3lzdGVtIGNhdGFsb2dzLCBiYWNrZW5kcyBpbiBhbGwKKyAgICAgZGF0YWJhc2VzIGFy ZSBjb25zaWRlcmVkLiBGb3IgdHJvdWJsZXNob290aW5nLCBzZWUKKyAgICAgPHhyZWYgbGlua2Vu ZD0idmFjdXVtLWZvci13cmFwYXJvdW5kIi8+LgorICAgIDwvcGFyYT4KKyAgIDwvbm90ZT4KKwog ICAgPHBhcmE+CiAgICAgVGhlIHN0YW5kYXJkIGZvcm0gb2YgPGNvbW1hbmQ+VkFDVVVNPC9jb21t YW5kPiByZW1vdmVzIGRlYWQgcm93CiAgICAgdmVyc2lvbnMgaW4gdGFibGVzIGFuZCBpbmRleGVz IGFuZCBtYXJrcyB0aGUgc3BhY2UgYXZhaWxhYmxlIGZvcgotLSAKMi4zOS41IChBcHBsZSBHaXQt MTU0KQo= --_004_OS3PR01MB8553C5907830DE25A8A4986ED9152OS3PR01MB8553jpnp_--