From 3aa7120591117c08f5a07c8f1398eaf1ba65003a Mon Sep 17 00:00:00 2001 From: Bharath Rupireddy Date: Mon, 14 Sep 2026 18:43:45 +0000 Subject: [PATCH v1 2/3] doc: Describe how to change the chunk_id type of a TOAST table. This commit documents the steps to change the chunk_id type of an existing table, which takes a dump and restore rather than an ALTER TABLE on its own. A note covers the change back to oid, which reports no error even for a table whose chunk identifiers did not fit in an oid, and limits the table to 2^32 out-of-line values again. Author: Bharath Rupireddy Discussion: https://postgr.es/m/aqd_gYs35v--sVlR%40paquier.xyz --- doc/src/sgml/storage.sgml | 65 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index 83de016eaa5..6b8fc2ed24a 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -595,6 +595,71 @@ tuple would otherwise be too big. + + Changing the <structfield>chunk_id</structfield> Type of a TOAST Relation + + +To change the chunk_id type of an existing table to +oid8, set +toast_value_type +and then dump and restore the table: + +ALTER TABLE mytable SET (toast_value_type = 'oid8'); + + +pg_dump -Fc -t mytable mydb > mytable.dump +pg_restore -d mynewdb mytable.dump + +The ALTER TABLE only records the new value, which is +consulted when a TOAST relation is created. The restore is +what creates one and therefore applies it, so it has to be the command that +creates the table. Restoring over a table that still exists leaves its +TOAST relation alone, so drop the original first when +changing a table in place. + + + +A table that has no TOAST relation yet takes no dump and +restore, as the value recorded now is applied when a wide column added later +causes one to be created. + + + +A table rewrite such as CLUSTER, +REPACK or VACUUM FULL preserves the +type already in use, and so does a pg_upgrade, +which carries the existing TOAST relation over to the new +cluster. The only way to recreate the TOAST relation of a +table is to dump and restore it. + + + +The type in use by the TOAST relation of a table can be +checked with: + +SELECT a.atttypid::regtype + FROM pg_class c, pg_attribute a + WHERE c.oid = 'mytable'::regclass AND + a.attrelid = c.reltoastrelid AND a.attname = 'chunk_id'; + + + + + +To change the chunk_id type of a table back to +oid, set toast_value_type to +oid and then dump and restore the table the same way. The +chunk identifiers are assigned afresh during the restore, so the ones that did +not fit in an oid are replaced by ones that do, and no error or +warning is reported. Such a table is however limited again to 2^32 +out-of-line values, and as the OID space fills up, finding an OID that is +still free when inserting into the TOAST relation can +become expensive. The server log reports still searching for an unused +OID in relation when that happens. + + + + -- 2.47.3