From 04604fd1a4ccaa91f83adbbca364999e864b463e Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 5 Sep 2002 21:32:23 +0000
Subject: [PATCH] Fill in section on table modification.
---
doc/src/sgml/ddl.sgml | 196 ++++++++++++++++++++++++++++++++++--------
1 file changed, 158 insertions(+), 38 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 49fb9784b15..85ba27b3ce7 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.2 2002/08/28 20:17:44 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.3 2002/09/05 21:32:23 petere Exp $ -->
<chapter id="ddl">
<title>Data Definition</title>
@@ -151,7 +151,7 @@ DROP TABLE products;
columns will be filled with their respective default values. A
data manipulation command can also request explicitly that a column
be set to its default value, without knowing what this value is.
- (Details about data manipulation commands are in the next chapter.)
+ (Details about data manipulation commands are in <xref linkend="dml">.)
</para>
<para>
@@ -263,7 +263,7 @@ CREATE TABLE products (
The first two constraints should look familiar. The third one
uses a new syntax. It is not attached to a particular column,
instead it appears as a separate item in the comma-separated
- column list. In general, column definitions and constraint
+ column list. Column definitions and these constraint
definitions can be listed in mixed order.
</para>
@@ -299,8 +299,10 @@ CREATE TABLE products (
<para>
It should be noted that a check constraint is satisfied if the
- check expression evaluates to true or the null value. To ensure
- that a column does not contain null values, the not-null
+ check expression evaluates to true or the null value. Since most
+ expressions will evaluate to the null value if one operand is null
+ they will not prevent null values in the constrained columns. To
+ ensure that a column does not contain null values, the not-null
constraint described in the next section should be used.
</para>
</sect2>
@@ -322,12 +324,13 @@ CREATE TABLE products (
<para>
A not-null constraint is always written as a column constraint. A
- not-null constraint is equivalent to creating a check constraint
- <literal>CHECK (<replaceable>column_name</replaceable> IS NOT
- NULL)</literal>, but in <productname>PostgreSQL</productname>
- creating an explicit not-null constraint is more efficient. The
- drawback is that you cannot give explicit names to not-null
- constraints created that way.
+ not-null constraint is functionally equivalent to creating a check
+ constraint <literal>CHECK (<replaceable>column_name</replaceable>
+ IS NOT NULL)</literal>, but in
+ <productname>PostgreSQL</productname> creating an explicit
+ not-null constraint is more efficient. The drawback is that you
+ cannot give explicit names to not-null constraints created that
+ way.
</para>
<para>
@@ -564,8 +567,8 @@ CREATE TABLE t1 (
<emphasis>FOREIGN KEY (b, c) REFERENCES other_table (c1, c2)</emphasis>
);
</programlisting>
- Of course, the number and type of constrained columns needs to
- match the number and type of referenced columns.
+ Of course, the number and type of the constrained columns needs to
+ match the number and type of the referenced columns.
</para>
<para>
@@ -847,13 +850,14 @@ SET SQL_Inheritance TO OFF;
<title>Modifying Tables</title>
<para>
- When you create a table and you realize that you made a mistake,
- then you can drop the table and create it again. But this is not a
- convenient option if the table is already filled with data, or if
- the table is referenced by other database objects (for instance a
- foreign key constraint). Therefore
- <productname>PostgreSQL</productname> provides a family of commands
- to make modifications on existing tables.
+ When you create a table and you realize that you made a mistake, or
+ the requirements of the application changed, then you can drop the
+ table and create it again. But this is not a convenient option if
+ the table is already filled with data, or if the table is
+ referenced by other database objects (for instance a foreign key
+ constraint). Therefore <productname>PostgreSQL</productname>
+ provides a family of commands to make modifications on existing
+ tables.
</para>
<para>
@@ -862,6 +866,9 @@ SET SQL_Inheritance TO OFF;
<listitem>
<para>Add columns,</para>
</listitem>
+ <listitem>
+ <para>Remove a column,</para>
+ </listitem>
<listitem>
<para>Add constraints,</para>
</listitem>
@@ -879,22 +886,135 @@ SET SQL_Inheritance TO OFF;
</listitem>
</itemizedlist>
- In the current implementation you cannot
- <itemizedlist spacing="compact">
- <listitem>
- <para>Remove a column,</para>
- </listitem>
- <listitem>
- <para>Change the data type of a column.</para>
- </listitem>
- </itemizedlist>
- These may be possible in a future release.
+ All these actions are performed using the <literal>ALTER
+ TABLE</literal> command.
</para>
- <comment>
- OK, now explain how to do this. There's currently so much activity
- on <literal>ALTER TABLE</literal> that I'm holding off a bit.
- </comment>
+ <sect2>
+ <title>Adding a Column</title>
+
+ <para>
+ To add a column, use this command:
+<programlisting>
+ALTER TABLE products ADD COLUMN description text;
+</programlisting>
+ The new column will initially be filled with null values in the
+ existing rows of the table.
+ </para>
+
+ <para>
+ You can also define a constraint on the column at the same time,
+ using the usual syntax:
+<programlisting>
+ALTER TABLE products ADD COLUMN description text CHECK (description <> '');
+</programlisting>
+ A new column cannot have a not-null constraint since the column
+ initially has to contain null values. But you can add a not-null
+ constraint later. Also, you cannot define a default value on a
+ new column. According to the SQL standard, this would have to
+ fill the new columns in the existing rows with the default value,
+ which is not implemented yet. But you can adjust the column
+ default later on.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Removing a Column</title>
+
+ <para>
+ To remove a column, use this command:
+<programlisting>
+ALTER TABLE products DROP COLUMN description;
+</programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Adding a Constraint</title>
+
+ <para>
+ To add a constraint, the table constraint syntax is used. For example:
+<programlisting>
+ALTER TABLE products ADD CHECK (name <> '');
+ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no);
+ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_groups;
+</programlisting>
+ To add a not-null constraint, which cannot be written as a table
+ constraint, use this syntax:
+<programlisting>
+ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
+</programlisting>
+ </para>
+
+ <para>
+ The constraint will be checked immediately, so the table data must
+ satisfy the constraint before it can be added.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Removing a Constraint</title>
+
+ <para>
+ To remove a constraint you need to know its name. If you gave it
+ a name then that's easy. Otherwise the system assigned a
+ generated name, which you need to find out. The
+ <application>psql</application> command <literal>\d
+ <replaceable>tablename</replaceable></literal> can be helpful
+ here; other interfaces might also provide a way to inspect table
+ details. Then the command is:
+<programlisting>
+ALTER TABLE products DROP CONSTRAINT some_name;
+</programlisting>
+ This works the same for all constraint types except not-null
+ constraints. To drop a not null constraint use
+<programlisting>
+ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
+</programlisting>
+ (Recall that not-null constraints do not have names.)
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Changing the Default</title>
+
+ <para>
+ To set a new default for a column, use a command like this:
+<programlisting>
+ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77;
+</programlisting>
+ To remove any default value, use
+<programlisting>
+ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
+</programlisting>
+ This is equivalent to setting the default to null, at least in
+ PostgreSQL. As a consequence, it is not an error to drop a
+ default where one hadn't been defined, because the default is
+ implicitly the null value.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Renaming a Column</title>
+
+ <para>
+ To rename a column:
+<programlisting>
+ALTER TABLE products RENAME COLUMN product_no TO product_number;
+</programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Renaming a Table</title>
+
+ <para>
+ To rename a table:
+<programlisting>
+ALTER TABLE products RENAME TO items;
+</programlisting>
+ </para>
+ </sect2>
</sect1>
<sect1 id="ddl-schemas">
@@ -990,10 +1110,10 @@ DROP TABLE products CASCADE;
<note>
<para>
- Foreign Key constraint dependencies and SERIAL dependencies from
- <productname>PostgreSQL</productname> versions prior to 7.3 are
- <emphasis>not</emphasis> maintained or created during the upgrade
- process. However, all other dependency types are created successfully.
+ Foreign key constraint dependencies and serial column dependencies
+ from <productname>PostgreSQL</productname> versions prior to 7.3
+ are <emphasis>not</emphasis> maintained or created during the
+ upgrade process. All other dependency types survive the upgrade.
</para>
</note>
</sect1>
--
GitLab