begriffs open source - ai-pg/blob - full-docs/txt/ddl-alter.txt

   1
   2 5.7. Modifying Tables #
   3
   4    5.7.1. Adding a Column
   5    5.7.2. Removing a Column
   6    5.7.3. Adding a Constraint
   7    5.7.4. Removing a Constraint
   8    5.7.5. Changing a Column's Default Value
   9    5.7.6. Changing a Column's Data Type
  10    5.7.7. Renaming a Column
  11    5.7.8. Renaming a Table
  12
  13    When you create a table and you realize that you made a mistake, or the
  14    requirements of the application change, you can drop the table and
  15    create it again. But this is not a convenient option if the table is
  16    already filled with data, or if the table is referenced by other
  17    database objects (for instance a foreign key constraint). Therefore
  18    PostgreSQL provides a family of commands to make modifications to
  19    existing tables. Note that this is conceptually distinct from altering
  20    the data contained in the table: here we are interested in altering the
  21    definition, or structure, of the table.
  22
  23    You can:
  24      * Add columns
  25      * Remove columns
  26      * Add constraints
  27      * Remove constraints
  28      * Change default values
  29      * Change column data types
  30      * Rename columns
  31      * Rename tables
  32
  33    All these actions are performed using the ALTER TABLE command, whose
  34    reference page contains details beyond those given here.
  35
  36 5.7.1. Adding a Column #
  37
  38    To add a column, use a command like:
  39 ALTER TABLE products ADD COLUMN description text;
  40
  41    The new column is initially filled with whatever default value is given
  42    (null if you don't specify a DEFAULT clause).
  43
  44 Tip
  45
  46    Adding a column with a constant default value does not require each row
  47    of the table to be updated when the ALTER TABLE statement is executed.
  48    Instead, the default value will be returned the next time the row is
  49    accessed, and applied when the table is rewritten, making the ALTER
  50    TABLE very fast even on large tables.
  51
  52    If the default value is volatile (e.g., clock_timestamp()) each row
  53    will need to be updated with the value calculated at the time ALTER
  54    TABLE is executed. To avoid a potentially lengthy update operation,
  55    particularly if you intend to fill the column with mostly nondefault
  56    values anyway, it may be preferable to add the column with no default,
  57    insert the correct values using UPDATE, and then add any desired
  58    default as described below.
  59
  60    You can also define constraints on the column at the same time, using
  61    the usual syntax:
  62 ALTER TABLE products ADD COLUMN description text CHECK (description <> '');
  63
  64    In fact all the options that can be applied to a column description in
  65    CREATE TABLE can be used here. Keep in mind however that the default
  66    value must satisfy the given constraints, or the ADD will fail.
  67    Alternatively, you can add constraints later (see below) after you've
  68    filled in the new column correctly.
  69
  70 5.7.2. Removing a Column #
  71
  72    To remove a column, use a command like:
  73 ALTER TABLE products DROP COLUMN description;
  74
  75    Whatever data was in the column disappears. Table constraints involving
  76    the column are dropped, too. However, if the column is referenced by a
  77    foreign key constraint of another table, PostgreSQL will not silently
  78    drop that constraint. You can authorize dropping everything that
  79    depends on the column by adding CASCADE:
  80 ALTER TABLE products DROP COLUMN description CASCADE;
  81
  82    See Section 5.15 for a description of the general mechanism behind
  83    this.
  84
  85 5.7.3. Adding a Constraint #
  86
  87    To add a constraint, the table constraint syntax is used. For example:
  88 ALTER TABLE products ADD CHECK (name <> '');
  89 ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no);
  90 ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_group
  91 s;
  92
  93    To add a not-null constraint, which is normally not written as a table
  94    constraint, this special syntax is available:
  95 ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
  96
  97    This command silently does nothing if the column already has a not-null
  98    constraint.
  99
 100    The constraint will be checked immediately, so the table data must
 101    satisfy the constraint before it can be added.
 102
 103 5.7.4. Removing a Constraint #
 104
 105    To remove a constraint you need to know its name. If you gave it a name
 106    then that's easy. Otherwise the system assigned a generated name, which
 107    you need to find out. The psql command \d tablename can be helpful
 108    here; other interfaces might also provide a way to inspect table
 109    details. Then the command is:
 110 ALTER TABLE products DROP CONSTRAINT some_name;
 111
 112    As with dropping a column, you need to add CASCADE if you want to drop
 113    a constraint that something else depends on. An example is that a
 114    foreign key constraint depends on a unique or primary key constraint on
 115    the referenced column(s).
 116
 117    Simplified syntax is available to drop a not-null constraint:
 118 ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
 119
 120    This mirrors the SET NOT NULL syntax for adding a not-null constraint.
 121    This command will silently do nothing if the column does not have a
 122    not-null constraint. (Recall that a column can have at most one
 123    not-null constraint, so it is never ambiguous which constraint this
 124    command acts on.)
 125
 126 5.7.5. Changing a Column's Default Value #
 127
 128    To set a new default for a column, use a command like:
 129 ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77;
 130
 131    Note that this doesn't affect any existing rows in the table, it just
 132    changes the default for future INSERT commands.
 133
 134    To remove any default value, use:
 135 ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
 136
 137    This is effectively the same as setting the default to null. As a
 138    consequence, it is not an error to drop a default where one hadn't been
 139    defined, because the default is implicitly the null value.
 140
 141 5.7.6. Changing a Column's Data Type #
 142
 143    To convert a column to a different data type, use a command like:
 144 ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2);
 145
 146    This will succeed only if each existing entry in the column can be
 147    converted to the new type by an implicit cast. If a more complex
 148    conversion is needed, you can add a USING clause that specifies how to
 149    compute the new values from the old.
 150
 151    PostgreSQL will attempt to convert the column's default value (if any)
 152    to the new type, as well as any constraints that involve the column.
 153    But these conversions might fail, or might produce surprising results.
 154    It's often best to drop any constraints on the column before altering
 155    its type, and then add back suitably modified constraints afterwards.
 156
 157 5.7.7. Renaming a Column #
 158
 159    To rename a column:
 160 ALTER TABLE products RENAME COLUMN product_no TO product_number;
 161
 162 5.7.8. Renaming a Table #
 163
 164    To rename a table:
 165 ALTER TABLE products RENAME TO items;