ALTER TABLE is used to modify tables, including modifying table definitions, renaming tables, renaming specified columns in tables, renaming table constraints, setting table schemas, enabling or disabling row-level access control, and adding or updating multiple columns.
1 2 | ALTER TABLE [ IF EXISTS ] { table_name [*] | ONLY table_name | ONLY ( table_name ) } action [, ... ]; |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | column_clause | ADD table_constraint [ NOT VALID ] | ADD table_constraint_using_index | VALIDATE CONSTRAINT constraint_name | DROP CONSTRAINT [ IF EXISTS ] constraint_name [ RESTRICT | CASCADE ] | CLUSTER ON index_name | SET WITHOUT CLUSTER | SET ( {storage_parameter = value} [, ... ] ) | RESET ( storage_parameter [, ... ] ) | OWNER TO new_owner | SET TABLESPACE new_tablespace | SET {COMPRESS|NOCOMPRESS} | DISTRIBUTE BY { REPLICATION | { HASH ( column_name [,...] ) } } | TO { GROUP groupname | NODE ( nodename [, ... ] ) } | ADD NODE ( nodename [, ... ] ) | DELETE NODE ( nodename [, ... ] ) | DISABLE TRIGGER [ trigger_name | ALL | USER ] | ENABLE TRIGGER [ trigger_name | ALL | USER ] | ENABLE REPLICA TRIGGER trigger_name | ENABLE ALWAYS TRIGGER trigger_name | DISABLE ROW LEVEL SECURITY | ENABLE ROW LEVEL SECURITY | FORCE ROW LEVEL SECURITY | NO FORCE ROW LEVEL SECURITY | REFRESH STORAGE |
Adds a new table constraint.
Adds primary key constraint or unique constraint based on the unique index.
Validates a foreign key or check constraint that was previously created as NOT VALID, by scanning the table to ensure there are no rows for which the constraint is not satisfied. Nothing happens if the constraint is already marked valid.
Drops a table constraint.
Selects the default index for future CLUSTER operations. It does not actually re-cluster the table.
Removes the most recently used CLUSTER index specification from the table. This operation affects future cluster operations that do not specify an index.
Changes one or more storage parameters for the table.
Resets one or more storage parameters to their defaults. As with SET, a table rewrite might be needed to update the table entirely.
Changes the owner of the table, sequence, or view to the specified user.
Sets the compression feature of a table. The table compression feature affects only the storage mode of data inserted in a batch subsequently and does not affect storage of existing data. Setting the table compression feature will result in the fact that there are both compressed and uncompressed data in the table.
Changing a table's distribution mode will physically redistribute the table data based on the new distribution mode. After the distribution mode is changed, you are advised to manually run the ANALYZE statement to collect new statistics about the table.
The syntax is only available in extended mode (when GUC parameter support_extended_features is on). Exercise caution when enabling the mode. It is used for tools like internal dilatation tools. Common users should not use the mode.
It is only available for tools like internal dilatation. General users should not use the mode.
It is only available for internal scale-in tools. Common users should not use the syntax.
Disables a single trigger specified by trigger_name, disables all triggers, or disables only user triggers (excluding internally generated constraint triggers, for example, deferrable unique constraint triggers and exclusion constraints triggers).
Exercise caution when using this function because data integrity cannot be ensured as expected if the triggers are not executed.
Enables a single trigger specified by trigger_name, enables all triggers, or enables only user triggers.
Determines that the trigger firing mechanism is affected by the configuration variable session_replication_role. When the replication role is origin (default value) or local, a simple trigger is fired.
When ENABLE REPLICA is configured for a trigger, it is fired only when the session is in replica mode.
Determines that all triggers are fired regardless of the current replication mode.
Enables or disables row-level access control for a table.
If row-level access control is enabled for a data table but no row-level access control policy is defined, the row-level access to the data table is not affected. If row-level access control for a table is disabled, the row-level access to the table is not affected even if a row-level access control policy has been defined. For details, see CREATE ROW LEVEL SECURITY POLICY.
Forcibly enables or disables row-level access control for a table.
By default, the table owner is not affected by the row-level access control feature. However, if row-level access control is forcibly enabled, the table owner (excluding system administrators) will be affected. System administrators are not affected by any row-level access control policies.
Changes the local hot partitions that meet the criteria defined by the rules specified in the storage_policy parameter of an OBS hot or cold table to the cold partitions stored in the OBS.
For example, if storage_policy is set to 'LMT:10' for an OBS hot or cold table when it is created, the partitions that are not updated within the last 10 days are switched to cold partitions in the OBS.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | ADD [ COLUMN ] column_name data_type [ compress_mode ] [ COLLATE collation ] [ column_constraint [ ... ] ] | MODIFY column_name data_type | MODIFY column_name [ CONSTRAINT constraint_name ] NOT NULL [ ENABLE ] | MODIFY column_name [ CONSTRAINT constraint_name ] NULL | DROP [ COLUMN ] [ IF EXISTS ] column_name [ RESTRICT | CASCADE ] | ALTER [ COLUMN ] column_name [ SET DATA ] TYPE data_type [ COLLATE collation ] [ USING expression ] | ALTER [ COLUMN ] column_name { SET DEFAULT expression | DROP DEFAULT } | ALTER [ COLUMN ] column_name { SET | DROP } NOT NULL | ALTER [ COLUMN ] column_name SET STATISTICS [PERCENT] integer | ADD STATISTICS (( column_1_name, column_2_name [, ...] )) | DELETE STATISTICS (( column_1_name, column_2_name [, ...] )) | ALTER [ COLUMN ] column_name SET ( {attribute_option = value} [, ... ] ) | ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] ) | ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } |
Adds a column to a table. If a column is added with ADD COLUMN, all existing rows in the table are initialized with the column's default value (NULL if no DEFAULT clause is specified).
Adds columns in the table.
Change the data type of an existing field in the table. Only the type conversion of the same category (between values, character strings, and time) is allowed.
Adds a NOT NULL constraint to a column of a table. Currently, this clause is unavailable to column-store tables.
Deletes the NOT NULL constraint to a certain column in the table.
Drops a column from a table. Index and constraint related to the column are automatically dropped. If an object not belonging to the table depends on the column, CASCADE must be specified, such as foreign key reference and view.
The DROP COLUMN form does not physically remove the column, but simply makes it invisible to SQL operations. Subsequent insert and update operations in the table will store a NULL value for the column. Therefore, column deletion takes a short period of time but does not immediately release the table space on the disks, because the space occupied by the deleted column is not reclaimed. The space will be reclaimed when VACUUM is executed.
To change the data type of a table column (data in the distribution column is not allowed to change types), only the type conversion of the same category (between values, strings, and time) is allowed. Indexes and simple table constraints on the column will automatically use the new data type by reparsing the originally supplied expression.
ALTER TYPE requires an entire table be rewritten. This is an advantage sometimes, because it frees up unnecessary space from a table. For example, to reclaim the space occupied by a deleted column, the fastest method is to use the command.
1 | ALTER TABLE table ALTER COLUMN anycol TYPE anytype; |
In this command, anycol indicates any column existing in the table and anytype indicates the type of the prototype of the column. ALTER TYPE does not change the table except that the table is forcibly rewritten. In this way, the data that is no longer used is deleted.
Sets or removes the default value for a column. The default values only apply to subsequent INSERT commands; they do not cause rows already in the table to change. Defaults can also be created for views, in which case they are inserted into INSERT statements on the view before the view's ON INSERT rule is applied.
Changes whether a column is marked to allow NULL values or to reject NULL values. You can only use SET NOT NULL when the column contains no NULL values.
Specifies the per-column statistics-gathering target for subsequent ANALYZE operations. The value ranges from 0 to 10000. Set it to -1 to revert to using the default system statistics target.
Adds or deletes the declaration of collecting multi-column statistics to collect multi-column statistics as needed when ANALYZE is performed for a table or a database. The statistics about a maximum of 32 columns can be collected at a time. You are not allowed to add or delete the declaration for system tables or foreign tables
ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )
Sets or resets per-attribute options.
Currently, the only defined per-attribute options are n_distinct and n_distinct_inherited. n_distinct affects statistics of table, while n_distinct_inherited affects the statistics of table and its subtables. Currently, only SET/RESET n_distinct is supported, and SET/RESET n_distinct_inherited is forbidden.
Sets the storage mode for a column. This clause specifies whether this column is held inline or in a secondary TOAST table, and whether the data should be compressed. This statement can only be used for row-based tables. SET STORAGE only sets the strategy to be used for future table operations.
1 2 3 4 5 6 7 8 | [ CONSTRAINT constraint_name ] { NOT NULL | NULL | CHECK ( expression ) | DEFAULT default_expr | UNIQUE index_parameters | PRIMARY KEY index_parameters } [ DEFERRABLE | NOT DEFERRABLE | INITIALLY DEFERRED | INITIALLY IMMEDIATE ] |
1 | [ DELTA | PREFIX | DICTIONARY | NUMSTR | NOCOMPRESS ] |
1 2 3 | [ CONSTRAINT constraint_name ] { UNIQUE | PRIMARY KEY } USING INDEX index_name [ DEFERRABLE | NOT DEFERRABLE | INITIALLY DEFERRED | INITIALLY IMMEDIATE ] |
1 2 3 4 5 6 | [ CONSTRAINT constraint_name ] { CHECK ( expression ) | UNIQUE ( column_name [, ... ] ) index_parameters | PRIMARY KEY ( column_name [, ... ] ) index_parameters } [ DEFERRABLE | NOT DEFERRABLE | INITIALLY DEFERRED | INITIALLY IMMEDIATE ] |
1 2 | [ WITH ( {storage_parameter = value} [, ... ] ) ] [ USING INDEX TABLESPACE tablespace_name ] |
1 2 | ALTER TABLE [ IF EXISTS ] table_name RENAME TO new_table_name; |
1 2 | ALTER TABLE [ IF EXISTS ] { table_name [*] | ONLY table_name | ONLY ( table_name )} RENAME [ COLUMN ] column_name TO new_column_name; |
1 2 | ALTER TABLE { table_name [*] | ONLY table_name | ONLY ( table_name ) } RENAME CONSTRAINT constraint_name TO new_constraint_name; |
1 2 | ALTER TABLE [ IF EXISTS ] table_name SET SCHEMA new_schema; |
1 2 | ALTER TABLE [ IF EXISTS ] table_name ADD ( { column_name data_type [ compress_mode ] [ COLLATE collation ] [ column_constraint [ ... ] ]} [, ...] ); |
1 2 | ALTER TABLE [ IF EXISTS ] table_name MODIFY ( { column_name data_type | column_name [ CONSTRAINT constraint_name ] NOT NULL [ ENABLE ] | column_name [ CONSTRAINT constraint_name ] NULL } [, ...] ); |
Sends a notification instead of an error if no tables have identical names. The notification prompts that the table you are querying does not exist.
table_name is the name of table that you need to modify.
If ONLY is specified, only the table is modified. If ONLY is not specified, the table and all subtables will be modified. You can add the asterisk (*) option following the table name to specify that all subtables are scanned, which is the default operation.
Specifies the name of an existing constraint to drop.
Specifies the name of this index.
Specifies the name of a storage parameter.
Specifies the name of the new table owner.
Specifies the new name of the tablespace to which the table belongs.
Specifies the name of a new or an existing column.
Specifies the type of a new column or a new type of an existing column.
Specifies the compress options of the table, only available for row-based tables. The clause specifies the algorithm preferentially used by the column.
Specifies the collation rule name of a column. The optional COLLATE clause specifies a collation for the new column; if omitted, the collation is the default for the new column.
A USING clause specifies how to compute the new column value from the old; if omitted, the default conversion is an assignment cast from old data type to new. A USING clause must be provided if there is no implicit or assignment cast from the old to new type.
USING in ALTER TYPE can specify any expression involving the old values of the row; that is, it can refer to any columns other than the one being converted. This allows very general conversions to be done with the ALTER TYPE syntax. Because of this flexibility, the USING expression is not applied to the column's default value (if any); the result might not be a constant expression as required for a default. This means that when there is no implicit or assignment cast from old to new type, ALTER TYPE might fail to convert the default even though a USING clause is supplied. In such cases, drop the default with DROP DEFAULT, perform the ALTER TYPE, and then use SET DEFAULT to add a suitable new default. Similar considerations apply to indexes and constraints involving the column.
Sets whether the column allows null values.
Specifies the constant value of an integer with a sign. If PERCENT is used, the range of integer is from 0 to 100.
Specifies an attribute option.
Specifies a column storage mode.
New or updated rows must satisfy for an insert or update operation to succeed. Expressions evaluating to TRUE succeed. If any row of an insert or update operation produces a FALSE result, an error exception is raised and the insert or update does not alter the database.
A check constraint specified as a column constraint should reference only the column's values, while an expression appearing in a table constraint can reference multiple columns.
Currently, CHECK expression does not include subqueries and cannot use variables apart from the current column.
Assigns a default data value for a column.
The data type of the default expression must match the data type of the column.
The default expression will be used in any insert operation that does not specify a value for the column. If there is no default value for a column, then the default value is NULL.
UNIQUE ( column_name [, ... ] ) index_parameters
The UNIQUE constraint specifies that a group of one or more columns of a table can contain only unique values.
PRIMARY KEY ( column_name [, ... ] ) index_parameters
The primary key constraint specifies that one or more columns of a table must contain unique (non-duplicate) and non-null values. This parameter is valid only for columns with the NOT NULL constraint.
Sets whether the constraint is deferrable. This option is unavailable to column-store tables.
Specifies an optional storage parameter for a table or an index.
Specifies the new table name.
Specifies the new name of a specific column in a table.
Specifies the new name of a table constraint.
Specifies the new schema name.
Automatically drops objects that depend on the dropped column or constraint (for example, views referencing the column).
Refuses to drop the column or constraint if there are any dependent objects. This is the default behavior.
Specifies the schema name of a table.
Move a table to another schema.
1 | ALTER TABLE tpcds.warehouse_t19 SET SCHEMA joe; |
When renaming an existing table, the new table name cannot be prefixed with the schema name of the original table.
1 | ALTER TABLE joe.warehouse_t19 RENAME TO warehouse_t23; |
Change the distribution mode of the tpcds.warehouse_t22 table to REPLICATION.
1 | ALTER TABLE tpcds.warehouse_t22 DISTRIBUTE BY REPLICATION; |
Change the distribution column of the tpcds.warehouse_t22 table to W_WAREHOUSE_SK.
1 | ALTER TABLE tpcds.warehouse_t22 DISTRIBUTE BY HASH(W_WAREHOUSE_SK); |
Switch the storage format of a column-store table.
1 | ALTER TABLE tpcds.warehouse_t18 SET (COLVERSION = 1.0); |
Disable the delta table function of the column-store table.
1 | ALTER TABLE tpcds.warehouse_t21 SET (ENABLE_DELTA = OFF); |
Disable the SKIP_FPI_HINT function of the table.
1 | ALTER TABLE tpcds.warehouse_t22 SET (SKIP_FPI_HINT = FALSE); |
Change the data temperature for a single table.
1 | ALTER TABLE tpcds.warehouse_t23 REFRESH STORAGE; |
Change the data temperature for multiple tables in batches.
SELECT pg_refresh_storage();
Create an index ds_warehouse_t1_index1 for the table tpcds.warehouse_t1. Then add primary key constraints, and rename the created index.
1 2 | CREATE UNIQUE INDEX ds_warehouse_t1_index1 ON tpcds.warehouse_t1(W_WAREHOUSE_SK); ALTER TABLE tpcds.warehouse_t1 ADD CONSTRAINT ds_warehouse_t1_index2 PRIMARY KEY USING INDEX ds_warehouse_t1_index1; |
Delete the primary key ds_warehouse_t1_index2 from the table tpcds.warehouse_t1.
1 | ALTER TABLE tpcds.warehouse_t1 DROP CONSTRAINT ds_warehouse_t1_index2; |
If no partial clusters have been specified in a column-store table, add a partial cluster to the table.
1 | ALTER TABLE tpcds.warehouse_t17 ADD PARTIAL CLUSTER KEY(W_WAREHOUSE_SK); |
Delete a partial cluster column from the column-store table.
1 | ALTER TABLE tpcds.warehouse_t17 DROP CONSTRAINT warehouse_t17_cluster; |
Add a Not-Null constraint to an existing column.
1 | ALTER TABLE tpcds.warehouse_t19 ALTER COLUMN W_GOODS_CATEGORY SET NOT NULL; |
Remove Not-Null constraints from an existing column.
1 | ALTER TABLE tpcds.warehouse_t19 ALTER COLUMN W_GOODS_CATEGORY DROP NOT NULL; |
Add a check constraint to the tpcds.warehouse_t19 table.
1 | ALTER TABLE tpcds.warehouse_t19 ADD CONSTRAINT W_CONSTR_KEY4 CHECK (W_STATE <> ''); |
Add a primary key to the tpcds.warehouse_t1 table.
1 | ALTER TABLE tpcds.warehouse_t1 ADD PRIMARY KEY(W_WAREHOUSE_SK); |
Add a varchar column to the tpcds.warehouse_t19 table.
1 | ALTER TABLE tpcds.warehouse_t19 ADD W_GOODS_CATEGORY varchar(30); |
Use one statement to alter the types of two existing columns.
1 2 3 | ALTER TABLE tpcds.warehouse_t19 ALTER COLUMN W_GOODS_CATEGORY TYPE varchar(80), ALTER COLUMN W_STREET_NAME TYPE varchar(100); |
This statement is equivalent to the preceding statement.
1 | ALTER TABLE tpcds.warehouse_t19 MODIFY (W_GOODS_CATEGORY varchar(30), W_STREET_NAME varchar(60)); |
Delete a column from the tpcds.warehouse_t23 table.
1 | ALTER TABLE tpcds.warehouse_t23 DROP COLUMN W_STREET_NAME; |