From 64d50145f69faa53199e2f6d967e14c79a5cfba7 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. Previously, there was no documented way to change the chunk_id type of an existing table. This commit documents the steps, which take 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..437d467d3fb 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 Table + + +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 table 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 table alone, so drop the original first when +changing a table in place. + + + +A table that has no TOAST table 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 table over to the new +cluster. The only way to recreate the TOAST table of a +table is to dump and restore it. + + + +The type in use by the TOAST table 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 table can +become expensive. The server log reports still searching for an unused +OID in relation when that happens. + + + + -- 2.47.3