Project: YugabyteDB (App Definition and Development / Database)
File: ddl_alter_table.md

title: ALTER TABLE statement [YSQL] headerTitle: ALTER TABLE linkTitle: ALTER TABLE description: Use the `ALTER TABLE` statement to change the definition of a table. menu: v2.18: identifier: ddlaltertable parent: statements type: docs Use the `ALTER TABLE` statement to change the definition of a table. {{%ebnf%}} alter_table, altertableaction, altertableconstraint, altercolumnconstraint, table_expr {{%/ebnf%}} <a name="table-expr-note"></a></br></br> {{< note title="Table inheritance is not yet supported" >}} YSQL in the present "latest" YugabyteDB does not yet support the "table inheritance" feature that is described in the . The attempt to create a table that inherits another table causes the 0A000 (featurenotsupported) error with the message "INHERITS not supported yet". This means that the syntax that the `table_expr` rule allows doesn't not yet bring any useful meaning. It says that you can write, for example, this: ```plpgsql alter table t * add column y text; ``` or this: ```plpgsql alter table only t add column y text; ``` These variants are useful only when at least one other table inherits `t`. But as yet, no table can inherit `t`. This means that if the unadorned variant `alter table t...` runs without error, then each of these variants will run without error too. But the effect of each is the same as that of the unadorned variant. Until inheritance is supported, use a bare . {{< /note >}} Specify one of the following actions. Add the specified column with the specified data type and constraint. Rename the table to the specified table name. {{< note title="Note" >}} Renaming a table is a non blocking metadata change operation. {{< /note >}} Drop the named column from the table. `RESTRICT` Remove only the specified column. `CASCADE` Remove the specified column and any dependent objects. Set up and populate a parents-children pair of tables: ```plpgsql drop table if exists children cascade; drop table if exists parents cascade; -- The column "b" models a (natural) business unique key. create table parents( k int primary key, b int not null, v text not null, constraint parentsbunq unique(b)); create table children( parents_b int not null, k int not null, v text not null, constraint childrenpk primary key(parentsb, k), constraint childrenfk foreign key(parentsb) references parents(b) match full on delete cascade on update restrict); insert into parents(k, b, v) values (1, 10, 'dog'), (2, 20, 'cat'), (3, 30, 'frog'); insert into children(parents_b, k, v) values (10, 1, 'dog-child-a'), (10, 2, 'dog-child-b'), (10, 3, 'dog-child-c'), (20, 1, 'cat-child-a'), (20, 2, 'cat-child-b'), (20, 3, 'cat-child-c'), (30, 1, 'frog-child-a'), (30, 2, 'frog-child-b'), (30, 3, 'frog-child-c'); select p.v as "p.v", c.v as "c.v" from parents p inner join children c on c.parents_b = p.b order by p.b, c.k; ``` This is the result: ```output p.v | c.v +-- dog | dog-child-a dog | dog-child-b dog | dog-child-c cat | cat-child-a cat | cat-child-b cat | cat-child-c frog | frog-child-a frog | frog-child-b frog | frog-child-c ``` The `\d children` meta-command shows that it has a foreign key that's a dependent object on the column `b` in the `parents` table: ```output Indexes: "childrenpk" PRIMARY KEY, lsm (parentsb HASH, k ASC) Foreign-key constraints: "childrenfk" FOREIGN KEY (parentsb) REFERENCES parents(b) MATCH FULL ON UPDATE RESTRICT ON DELETE CASCADE ``` This is a contrived

It is unusual practice (and normally bad practice) to make a foreign key constraint target anything but the column list upon which the parent table's primary key constraint is defined. But there are sometimes defensible reasons to do this. Now try to drop the column `parents.b`: ```plpgsql do $body$ declare message text not null := ''; detail text not null := ''; begin -- Causes error 'cos "cascade" is required. alter table parents drop column b; assert false, 'Should not get here'; exception -- Error 2BP01 when dependentobjectsstill_exist then get stacked diagnostics message = message_text, detail = pgexceptiondetail; assert message = 'cannot drop column b of table parents because other objects depend on it', 'Bad message'; assert detail = 'constraint children_fk on table children depends on column b of table parents', 'Bad detail'; end; $body$; ``` It finishes without error, showing that the bare `alter table parents drop column b`, without `cascade`, fails and causes the message and hint that the code presents. Now repeat the attempt with `cascade` and observe the result: ```plpgsql alter table parents drop column b cascade; ``` It quietly succeeds. Now `\d children` shows that the foreign key constraint `children_fk` has been transitively dropped. Add the specified constraint to the table. Drop the named constraint from the table. `RESTRICT` Remove only the specified constraint. `CASCADE` Remove the specified constraint and any dependent objects. Rename a column to the specified name. This enables or disables row level security for the table. If enabled and no policies exist for the table, then a default-deny policy is applied. If disabled, then existing policies for the table will not be applied and will be ignored. See for details on how to create row level security policies. This controls the application of row security policies for the table when the user is the table owner. If enabled, row level security policies will be applied when the user is the table owner. If disabled (the default) then row level security will not be applied when the user is the table owner. See for details on how to create row level security policies. Specify a table or column constraint. Specify the name of the constraint. `FOREIGN KEY` and `REFERENCES` specify that the set of columns can only contain values that are present in the referenced columns of the referenced table. It is used to enforce referential integrity of data. This enforces that the set of columns specified in the `UNIQUE` constraint are unique in the table, that is, no two rows can have the same values for the set of columns specified in the `UNIQUE` constraint. This is used to enforce that data in the specified table meets the requirements specified in the `CHECK` clause. This is used to specify a default value for the column. If an `INSERT` statement does not specify a value for the column, then the default value is used. If no default is specified for a column, then the default is NULL. Constraints can be deferred using the `DEFERRABLE` clause. Currently, only foreign key constraints can be deferred in YugabyteDB. A constraint that is not deferrable will be checked after every row within a statement. In the case of deferrable constraints, the checking of the constraint can be postponed until the end of the transaction. Constraints marked as `INITIALLY IMMEDIATE` will be checked after every row within a statement. Constraints marked as `INITIALLY DEFERRED` will be checked at the end of the transaction.