From 3fc3b4eb84dbdbe58eb283c3322ff6cf16d9a1d0 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" Date: Wed, 7 Jan 2026 14:50:36 -0700 Subject: [PATCH 1/2] docs Clarify ALTER TABLE --- doc/src/sgml/ref/alter_table.sgml | 309 +++++++++++++++++++++++++----- 1 file changed, 257 insertions(+), 52 deletions(-) diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 1bd479c917a..b1190fae968 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -171,6 +171,12 @@ WITH ( MODULUS numeric_literal, REM is specified and a column already exists with this name, no error is thrown. + + When applied to a partitioned table, the column is added to the + partitioned table definition and is implicitly present in all + partitions. Specifying ONLY is not allowed, and + this command cannot be used on individual partitions. + @@ -190,6 +196,12 @@ WITH ( MODULUS numeric_literal, REM does not exist, no error is thrown. In this case a notice is issued instead. + + When applied to a partitioned table, the column is removed from the + partitioned table definition and is implicitly removed from all + partitions. Specifying ONLY is not allowed, and + this command cannot be used on individual partitions. + @@ -211,7 +223,6 @@ WITH ( MODULUS numeric_literal, REM clause must be provided if there is no implicit or assignment cast from old to new type. - When this form is used, the column's statistics are removed, so running ANALYZE @@ -219,6 +230,12 @@ WITH ( MODULUS numeric_literal, REM For a virtual generated column, ANALYZE is not necessary because such columns never have statistics. + + When applied to a partitioned table, the data type change is applied + to the partitioned table definition and affects all partitions. + Specifying ONLY is not allowed, and this command + cannot be used on individual partitions. + @@ -232,6 +249,13 @@ WITH ( MODULUS numeric_literal, REM or UPDATE commands; it does not cause rows already in the table to change. + + When applied to a partitioned table, the default value is propagated + to all existing partitions unless ONLY is specified. + New partitions created afterwards inherit the default from the + partitioned table, but individual partitions may define a different + default. + @@ -242,7 +266,6 @@ WITH ( MODULUS numeric_literal, REM These forms change whether a column is marked to allow null values or to reject null values. - SET NOT NULL may only be applied to a column provided none of the records in the table contain a @@ -255,18 +278,19 @@ WITH ( MODULUS numeric_literal, REM If a column has an invalid not-null constraint, SET NOT NULL validates it. - - If this table is a partition, one cannot perform DROP NOT NULL - on a column if it is marked NOT NULL in the parent - table. To drop the NOT NULL constraint from all the - partitions, perform DROP NOT NULL on the parent - table. Even if there is no NOT NULL constraint on the - parent, such a constraint can still be added to individual partitions, - if desired; that is, the children can disallow nulls even if the parent - allows them, but not the other way around. It is also possible to drop - the NOT NULL constraint from ONLY - the parent table, which does not remove it from the children. + If this table is a partition, one cannot perform + DROP NOT NULL on a column if it is marked + NOT NULL in the parent table. To drop the + NOT NULL constraint from all partitions, perform + DROP NOT NULL on the parent table. Even if there is + no NOT NULL constraint on the parent, such a + constraint can still be added to individual partitions; that is, the + children can disallow nulls even if the parent allows them, but not + the other way around. It is also possible to apply + SET NOT NULL or DROP NOT NULL to + ONLY the parent table, which does not affect the + children. @@ -279,7 +303,6 @@ WITH ( MODULUS numeric_literal, REM in a stored generated column is rewritten and all the future changes will apply the new generation expression. - When this form is used on a stored generated column, its statistics are removed, so running @@ -288,6 +311,13 @@ WITH ( MODULUS numeric_literal, REM For a virtual generated column, ANALYZE is not necessary because such columns never have statistics. + + When applied to a partitioned table, the generation expression is + propagated to all existing partitions unless ONLY + is specified. New partitions created afterwards inherit the + expression from the partitioned table, while individual partitions + may define a different expression. + @@ -299,17 +329,21 @@ WITH ( MODULUS numeric_literal, REM Existing data in the columns is retained, but future changes will no longer apply the generation expression. - This form is currently only supported for stored generated columns (not virtual ones). - If DROP EXPRESSION IF EXISTS is specified and the column is not a generated column, no error is thrown. In this case a notice is issued instead. + + When applied to a partitioned table, the generation expression is + dropped from the partitioned table definition and from all + partitions. Specifying ONLY is not allowed, and + this command cannot be used on individual partitions. + @@ -327,12 +361,17 @@ WITH ( MODULUS numeric_literal, REM and UPDATE commands; they do not cause rows already in the table to change. - If DROP IDENTITY IF EXISTS is specified and the column is not an identity column, no error is thrown. In this case a notice is issued instead. + + When applied to a partitioned table, the identity property is defined + on the partitioned table definition and applies to all partitions. + Specifying ONLY is not allowed, and these forms + cannot be used on individual partitions. + @@ -346,6 +385,13 @@ WITH ( MODULUS numeric_literal, REM supported by ALTER SEQUENCE such as INCREMENT BY. + + When applied to a partitioned table, these forms alter the sequence + associated with the identity column on the partitioned table + definition and affect all partitions. Specifying ONLY + is not allowed, and these forms cannot be used on individual + partitions. + @@ -369,6 +415,12 @@ WITH ( MODULUS numeric_literal, REM SET STATISTICS acquires a SHARE UPDATE EXCLUSIVE lock. + + For partitioned tables, this action applies to the partitioned table + and all of its partitions unless ONLY is specified. + Partitions created afterwards do not inherit the statistics target + from the partitioned table. + @@ -403,6 +455,13 @@ WITH ( MODULUS numeric_literal, REM Changing per-attribute options acquires a SHARE UPDATE EXCLUSIVE lock. + + For partitioned tables, these forms can be applied independently to + the partitioned table and to individual partitions. Changes made to + the partitioned table do not propagate to existing partitions, and + partitions created afterwards do not inherit the setting. + Specifying ONLY is allowed but has no effect. + @@ -437,6 +496,13 @@ WITH ( MODULUS numeric_literal, REM during future table updates. See for more information. + + When applied to a partitioned table, the storage setting is propagated + to all existing partitions unless ONLY is specified. + New partitions created afterwards inherit the setting from the + partitioned table, while individual partitions may use a different + storage setting. + @@ -467,6 +533,14 @@ WITH ( MODULUS numeric_literal, REM consulting the setting at the time of data insertion to determine the method to use. + + When applied to a partitioned table, the compression setting is applied + to the partitioned table definition and does not propagate to existing + partitions. New partitions created afterwards inherit the setting from + the partitioned table, while individual partitions may use a different + compression method. Specifying ONLY is allowed but has + no effect. + @@ -479,7 +553,6 @@ WITH ( MODULUS numeric_literal, REM VALID, which is currently only allowed for foreign-key, CHECK, and not-null constraints. - Normally, this form will cause a scan of the table to verify that all existing rows in the table satisfy the new constraint. But if @@ -495,7 +568,6 @@ WITH ( MODULUS numeric_literal, REM See below for more information about using the NOT VALID option. - Although most forms of ADD table_constraint @@ -506,12 +578,16 @@ WITH ( MODULUS numeric_literal, REM referenced table, in addition to the lock on the table on which the constraint is declared. - Additional restrictions apply when unique or primary key constraints are added to partitioned tables; see CREATE TABLE. - + + When applied to a partitioned table, the constraint is added to the + partitioned table and is automatically applied to all partitions. + Specifying ONLY is not allowed. New partitions + created afterwards inherit the constraint from the partitioned table. + @@ -523,7 +599,6 @@ WITH ( MODULUS numeric_literal, REM constraint to a table based on an existing unique index. All the columns of the index will be included in the constraint. - The index cannot have expression columns nor be a partial index. Also, it must be a b-tree index with default sort ordering. These @@ -531,7 +606,6 @@ WITH ( MODULUS numeric_literal, REM built by a regular ADD PRIMARY KEY or ADD UNIQUE command. - If PRIMARY KEY is specified, and the index's columns are not already marked NOT NULL, then this command will attempt to @@ -539,13 +613,11 @@ WITH ( MODULUS numeric_literal, REM That requires a full table scan to verify the column(s) contain no nulls. In all other cases, this is a fast operation. - If a constraint name is provided then the index will be renamed to match the constraint name. Otherwise the constraint will be named the same as the index. - After this command is executed, the index is owned by the constraint, in the same way as if the index had been built by @@ -553,11 +625,10 @@ WITH ( MODULUS numeric_literal, REM command. In particular, dropping the constraint will make the index disappear too. - - This form is not currently supported on partitioned tables. + This form is not supported on partitioned tables, but can be used on + individual (leaf) partitions. - Adding a constraint using an existing index can be helpful in @@ -578,6 +649,12 @@ WITH ( MODULUS numeric_literal, REM created. Currently only foreign key constraints may be altered in this fashion, but see below. + + When applied to a partitioned table, the constraint is altered on the + partitioned table definition and the change applies to all partitions. + Specifying ONLY is not allowed, and this command + cannot be used on individual partitions. + @@ -596,7 +673,11 @@ WITH ( MODULUS numeric_literal, REM non-inheritable on a table with children, then the corresponding constraint on children will be marked as no longer inherited, but not removed. - + + + These forms are not supported on partitioned tables, but can be used + on individual (leaf) partitions. + @@ -615,6 +696,12 @@ WITH ( MODULUS numeric_literal, REM This command acquires a SHARE UPDATE EXCLUSIVE lock. + + When applied to a partitioned table, the constraint is validated on the + partitioned table and on all partitions. Unlike most constraint-related + sub-commands, individual partitions may validate the constraint + independently of the partitioned table. + @@ -627,6 +714,13 @@ WITH ( MODULUS numeric_literal, REM If IF EXISTS is specified and the constraint does not exist, no error is thrown. In this case a notice is issued instead. + + When applied to a partitioned table, the constraint is dropped from + all existing partitions unless ONLY is specified. + New partitions created afterwards do not include the dropped + constraint, while individual partitions may drop the constraint + independently of the partitioned table. + @@ -648,7 +742,6 @@ WITH ( MODULUS numeric_literal, REM of course the integrity of the constraint cannot be guaranteed if the triggers are not executed. - The trigger firing mechanism is also affected by the configuration variable . Simply enabled @@ -658,7 +751,6 @@ WITH ( MODULUS numeric_literal, REM mode, and triggers configured as ENABLE ALWAYS will fire regardless of the current replication role. - The effect of this mechanism is that in the default configuration, triggers do not fire on replicas. This is useful because if a trigger @@ -670,13 +762,14 @@ WITH ( MODULUS numeric_literal, REM to ENABLE ALWAYS so that it is also fired on replicas. - When this command is applied to a partitioned table, the states of - corresponding clone triggers in the partitions are updated too, - unless ONLY is specified. + corresponding clone triggers in existing partitions are updated too, + unless ONLY is specified. Triggers in partitions + created afterwards inherit the trigger state from the partitioned + table, while individual partitions may configure trigger states + independently. - This command acquires a SHARE ROW EXCLUSIVE lock. @@ -694,12 +787,18 @@ WITH ( MODULUS numeric_literal, REM are always applied in order to keep views working even if the current session is in a non-default replication role. - The rule firing mechanism is also affected by the configuration variable , analogous to triggers as described above. + + For partitioned tables, these forms can be applied independently to + the partitioned table and to individual partitions. Changes made to + the partitioned table do not propagate to existing partitions, and + partitions created afterwards do not inherit the setting. + Specifying ONLY is allowed but has no effect. + @@ -715,6 +814,13 @@ WITH ( MODULUS numeric_literal, REM See also CREATE POLICY. + + For partitioned tables, these forms can be applied independently to + the partitioned table and to individual partitions. Changes made to + the partitioned table do not propagate to existing partitions, and + partitions created afterwards do not inherit the setting. + Specifying ONLY is allowed but has no effect. + @@ -730,6 +836,13 @@ WITH ( MODULUS numeric_literal, REM See also CREATE POLICY. + + For partitioned tables, these forms can be applied independently to + the partitioned table and to individual partitions. Changes made to + the partitioned table do not propagate to existing partitions, and + partitions created afterwards do not inherit the setting. + Specifying ONLY is allowed but has no effect. + @@ -744,6 +857,10 @@ WITH ( MODULUS numeric_literal, REM Changing cluster options acquires a SHARE UPDATE EXCLUSIVE lock. + + This form is not supported on partitioned tables, but can be used on + individual (leaf) partitions. + @@ -759,6 +876,10 @@ WITH ( MODULUS numeric_literal, REM Changing cluster options acquires a SHARE UPDATE EXCLUSIVE lock. + + This form is not supported on partitioned tables, but can be used on + individual (leaf) partitions. + @@ -770,6 +891,12 @@ WITH ( MODULUS numeric_literal, REM system column. As oid system columns cannot be added anymore, this never has an effect. + + For partitioned tables, this form behaves the same as for regular + tables; it has no effect on either the partitioned table or its + partitions. Specifying ONLY is allowed but has no + effect. + @@ -785,12 +912,15 @@ WITH ( MODULUS numeric_literal, REM See for more information. - When applied to a partitioned table, there is no data to rewrite, - but partitions created afterwards will default to the given access - method unless overridden by a USING clause. - Specifying DEFAULT removes a previous value, - causing future partitions to default to - default_table_access_method. + When applied to a partitioned table, there is no data to rewrite. + Partitions created afterwards will use the access method specified + on the partitioned table, if any, unless overridden by a + USING clause; otherwise they default to + default_table_access_method. Specifying + DEFAULT removes a previously set access method, + causing future partitions to use + default_table_access_method. Specifying + ONLY is allowed but has no effect. @@ -803,12 +933,12 @@ WITH ( MODULUS numeric_literal, REM moves the data file(s) associated with the table to the new tablespace. Indexes on the table, if any, are not moved; but they can be moved separately with additional SET TABLESPACE commands. - When applied to a partitioned table, nothing is moved, but any - partitions created afterwards with - CREATE TABLE PARTITION OF will use that tablespace, - unless overridden by a TABLESPACE clause. + When applied to a partitioned table, no data is moved. Existing + partitions are not affected, but partitions created afterwards with + CREATE TABLE PARTITION OF will use the specified + tablespace unless overridden by a TABLESPACE clause. + Specifying ONLY is allowed but has no effect. - All tables in the current database in a tablespace can be moved by using the ALL IN TABLESPACE form, which will lock all tables @@ -835,15 +965,14 @@ WITH ( MODULUS numeric_literal, REM (see ). It cannot be applied to a temporary table. - This also changes the persistence of any sequences linked to the table (for identity or serial columns). However, it is also possible to change the persistence of such sequences separately. - - This form is not supported for partitioned tables. + This form is not supported on partitioned tables, but can be used on + individual (leaf) partitions. @@ -865,12 +994,15 @@ WITH ( MODULUS numeric_literal, REM time the table is locked so currently executing queries will not be affected. - SHARE UPDATE EXCLUSIVE lock will be taken for fillfactor, TOAST and autovacuum storage parameters, as well as the planner parameter parallel_workers. + + This form is not supported on partitioned tables, but can be used on + individual (leaf) partitions. + @@ -882,6 +1014,11 @@ WITH ( MODULUS numeric_literal, REM defaults. As with SET, a table rewrite might be needed to update the table entirely. + + When applied to a partitioned table, this form is accepted but has no + effect. It can be used on individual (leaf) partitions, where it + behaves as for a regular table. + @@ -895,7 +1032,6 @@ WITH ( MODULUS numeric_literal, REM already contain all the same columns as the parent (it could have additional columns, too). The columns must have matching data types. - In addition, all CHECK and NOT NULL constraints on the parent must also exist on the child, except those @@ -907,6 +1043,10 @@ WITH ( MODULUS numeric_literal, REM FOREIGN KEY constraints are not considered, but this might change in the future. + + This form does not support partitioned tables; it cannot be applied to + either a partitioned table or its partitions. + @@ -919,6 +1059,10 @@ WITH ( MODULUS numeric_literal, REM Queries against the parent table will no longer include records drawn from the target table. + + This form does not support partitioned tables; it cannot be applied to + either a partitioned table or its partitions. + @@ -933,6 +1077,12 @@ WITH ( MODULUS numeric_literal, REM that CREATE TABLE OF would permit an equivalent table definition. + + When applied to a partitioned table, this form affects only the + partitioned table itself. Specifying ONLY is + allowed but has no effect, and this form cannot be used on individual + partitions. + @@ -942,6 +1092,12 @@ WITH ( MODULUS numeric_literal, REM This form dissociates a typed table from its type. + + When applied to a partitioned table, this form affects only the + partitioned table itself. Specifying ONLY is + allowed but has no effect, and this form cannot be used on individual + partitions. + @@ -952,6 +1108,13 @@ WITH ( MODULUS numeric_literal, REM This form changes the owner of the table, sequence, view, materialized view, or foreign table to the specified user. + + For partitioned tables, this form can be applied independently to the + partitioned table and to individual partitions. Changing the owner of + the partitioned table does not affect existing partitions, and + partitions created afterwards do not inherit the new owner. + Specifying ONLY is allowed but has no effect. + @@ -1008,6 +1171,14 @@ WITH ( MODULUS numeric_literal, REM + + + For partitioned tables, this form can be applied independently to the + partitioned table and to individual partitions. Changing the replica + identity of the partitioned table does not affect existing partitions, + and partitions created afterwards do not inherit the setting. + Specifying ONLY is allowed but has no effect. + @@ -1022,6 +1193,12 @@ WITH ( MODULUS numeric_literal, REM the index is renamed as well. There is no effect on the stored data. + + For partitioned tables, this form behaves the same as for regular + tables. Renaming a partitioned table, column, or constraint does not + propagate to partitions, and ONLY can be specified + but has no effect. + @@ -1032,6 +1209,13 @@ WITH ( MODULUS numeric_literal, REM This form moves the table into another schema. Associated indexes, constraints, and sequences owned by table columns are moved as well. + + For partitioned tables, this form can be applied independently to the + partitioned table and to individual partitions. Moving the partitioned + table to another schema does not affect existing partitions, and + partitions created afterwards do not inherit the new schema. + Specifying ONLY is allowed but has no effect. + @@ -1410,6 +1594,27 @@ WITH ( MODULUS numeric_literal, REM * can be specified after the table name to explicitly indicate that descendant tables are included. + + + For a table that uses table inheritance, descendant tables are those + that inherit from the named table, directly or indirectly. + For a partitioned table, descendant tables are its partitions. + + + + Note that for partitioned tables, ONLY does not control + recursion for all ALTER TABLE actions. Some actions + apply only to the partitioned table itself, regardless of whether + ONLY is specified, while others are propagated to + partitions. The exact behavior depends on the specific action being + performed. + + + + Users should consult the documentation of each individual + ALTER TABLE action to determine whether and how it + affects partitions. + -- 2.34.1