diff options
Diffstat (limited to 'doc/src/sgml/ref')
| -rw-r--r-- | doc/src/sgml/ref/alter_table.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_table.sgml | 59 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_table_as.sgml | 40 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 9 | ||||
| -rw-r--r-- | doc/src/sgml/ref/prepare.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/ref/select_into.sgml | 34 |
6 files changed, 111 insertions, 54 deletions
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 9662d9b02f4..d10be7f2905 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.63 2003/11/29 19:51:38 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.64 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -149,6 +149,12 @@ ALTER TABLE <replaceable class="PARAMETER">name</replaceable> of the OID are kept indefinitely. This is semantically similar to the <literal>DROP COLUMN</literal> process. </para> + + <para> + Note that there is no variant of <command>ALTER TABLE</command> + that allows OIDs to be restored to a table once they have been + removed. + </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 00814fa4431..4af03bccfaa 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.76 2003/11/29 19:51:38 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.77 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -111,12 +111,12 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is: <para> If specified, the table is created as a temporary table. Temporary tables are automatically dropped at the end of a - session, or optionally at the end of the current transaction - (see ON COMMIT below). Existing permanent tables with the same - name are not visible to the current session while the temporary - table exists, unless they are referenced with schema-qualified - names. Any indexes created on a temporary table are automatically - temporary as well. + session, or optionally at the end of the current transaction + (see <literal>ON COMMIT</literal> below). Existing permanent + tables with the same name are not visible to the current session + while the temporary table exists, unless they are referenced + with schema-qualified names. Any indexes created on a temporary + table are automatically temporary as well. </para> <para> @@ -243,22 +243,30 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is: <listitem> <para> This optional clause specifies whether rows of the new table - should have OIDs (object identifiers) assigned to them. The - default is to have OIDs. (If the new table inherits from any - tables that have OIDs, then <literal>WITH OIDS</> is forced even - if the command says <literal>WITHOUT OIDS</>.) + should have OIDs (object identifiers) assigned to them. If + neither <literal>WITH OIDS</literal> nor <literal>WITHOUT + OIDS</literal> is specified, the default value depends upon the + <varname>default_with_oids</varname> configuration parameter. (If + the new table inherits from any tables that have OIDs, then + <literal>WITH OIDS</> is forced even if the command says + <literal>WITHOUT OIDS</>.) </para> <para> - Specifying <literal>WITHOUT OIDS</> allows the user to suppress - generation of OIDs for rows of a table. This may be worthwhile - for large tables, since it will reduce OID consumption and - thereby postpone wraparound of the 32-bit OID counter. Once the - counter wraps around, uniqueness of OIDs can no longer be - assumed, which considerably reduces their usefulness. Specifying - <literal>WITHOUT OIDS</literal> also reduces the space required - to store the table on disk by 4 bytes per row of the table, - thereby improving performance. + If <literal>WITHOUT OIDS</literal> is specified or implied, this + means that the generation of OIDs for this table will be + supressed. This is generally considered worthwhile, since it + will reduce OID consumption and thereby postpone the wraparound + of the 32-bit OID counter. Once the counter wraps around, OIDs + can no longer be assumed to be unique, which makes them + considerably less useful. In addition, excluding OIDs from a + table reduces the space required on disk to storage the table by + 4 bytes per row, leading to increased performance. + </para> + + <para> + To remove OIDs from a table after it has been created, use <xref + linkend="sql-altertable" endterm="sql-altertable-title">. </para> </listitem> </varlistentry> @@ -572,18 +580,17 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is: <itemizedlist> <listitem> <para> - Whenever an application makes use of OIDs to identify specific + Using OIDs in new applications is not recommended: where + possible, using a <literal>SERIAL</literal> or other sequence + generator as the table's primary key is preferred. However, if + your application does make use of OIDs to identify specific rows rows of a table, it is recommended to create a unique constraint on the <structfield>oid</> column of that table, to ensure that OIDs in the table will indeed uniquely identify rows even after counter wraparound. Avoid assuming that OIDs are unique across tables; if you need a database-wide unique identifier, use the combination of <structfield>tableoid</> and row OID for the - purpose. (It is likely that future <productname>PostgreSQL</> - releases will use a separate OID counter for each table, so that - it will be <emphasis>necessary</>, not optional, to include - <structfield>tableoid</> to have a unique identifier - database-wide.) + purpose. </para> <tip> diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 856846c50b2..a7382abfdc9 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.17 2003/11/29 19:51:38 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.18 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -51,7 +51,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name <refsect1> <title>Parameters</title> - + + <variablelist> + <varlistentry> + <term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term> + <listitem> + <para> + Ignored for compatibility. Refer to <xref + linkend="sql-createtable" endterm="sql-createtable-title"> for + details. + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> <varlistentry> <term><literal>TEMPORARY</> or <literal>TEMP</></term> @@ -105,10 +118,24 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name <title>Notes</title> <para> - This command is functionally equivalent to <xref - linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is preferred since it is less - likely to be confused with other uses of the <command>SELECT - ... INTO</command> syntax. + This command is functionally similar to <xref + linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is + preferred since it is less likely to be confused with other uses of + the <command>SELECT INTO</command> syntax. + </para> + + <para> + Prior to PostgreSQL 7.5, <command>CREATE TABLE AS</command> always + included OIDs in the table it produced. Furthermore, these OIDs + were newly generated: they were distinct from the OIDs of any of + the rows in the source tables of the <command>SELECT</command> or + <command>EXECUTE</command> statement. Therefore, if <command>CREATE + TABLE AS</command> was frequently executed, the OID counter would + be rapidly incremented. As of PostgreSQL 7.5, the inclusion of OIDs + in the table generated by <command>CREATE TABLE AS</command> is + controlled by the <varname>default_with_oids</varname> configuration + variable. This variable currently defaults to true, but will likely + default to false in a future release of <productname>PostgreSQL</>. </para> </refsect1> @@ -129,7 +156,6 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name <simplelist type="inline"> <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member> - <member><xref linkend="sql-createview" endterm="sql-createview-title"></member> <member><xref linkend="sql-execute" endterm="sql-execute-title"></member> <member><xref linkend="sql-select" endterm="sql-select-title"></member> <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index f02c3638a7f..c6041237240 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.67 2003/11/29 19:51:39 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.68 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -611,8 +611,11 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - Once restored, it is wise to run <command>ANALYZE</> on each - restored table so the optimizer has useful statistics. + The dump file produced by <application>pg_dump</application> does + not contain the statistics used by the optimizer to make query + planning decisions. Therefore, it is wise to run + <command>ANALYZE</command> after restoring from a dump file to + ensure good performance. </para> </refsect1> diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index 82e36fe89fc..684b4bb8ba0 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.8 2003/11/29 19:51:39 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.9 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -52,13 +52,12 @@ PREPARE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable c </para> <para> - Prepared statements are only stored in and for the duration of - the current database session. When - the session ends, the prepared statement is forgotten, and so it must be - recreated before being used again. This also means that a single - prepared statement cannot be used by multiple simultaneous database - clients; however, each client can create their own prepared statement - to use. + Prepared statements are only for the duration of the current + database session. When the session ends, the prepared statement is + forgotten, so it must be recreated before being used again. This + also means that a single prepared statement cannot be used by + multiple simultaneous database clients; however, each client can + create their own prepared statement to use. </para> <para> diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index cb321f0cfa6..1261f3cd4b5 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.25 2003/11/29 19:51:39 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.26 2003/12/01 22:07:58 momjian Exp $ PostgreSQL documentation --> @@ -82,13 +82,29 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac <title>Notes</title> <para> - <xref linkend="sql-createtableas" endterm="sql-createtableas-title"> - is functionally equivalent to <command>SELECT INTO</command>. - <command>CREATE TABLE AS</command> is the recommended syntax, since - this form of <command>SELECT INTO</command> is not available in - <application>ECPG</application> or - <application>PL/pgSQL</application>, because they interpret the - <literal>INTO</literal> clause differently. + <xref linkend="sql-createtableas" + endterm="sql-createtableas-title"> is functionally similar to + <command>SELECT INTO</command>. <command>CREATE TABLE AS</command> + is the recommended syntax, since this form of <command>SELECT + INTO</command> is not available in <application>ECPG</application> + or <application>PL/pgSQL</application>, because they interpret the + <literal>INTO</literal> clause differently. Furthermore, + <command>CREATE TABLE AS</command> offers a superset of the + functionality provided by <command>SELECT INTO</command>. + </para> + + <para> + Prior to PostgreSQL 7.5, the table created by <command>SELECT + INTO</command> always included OIDs. Furthermore, these OIDs were + newly generated: they were distinct from the OIDs of any of the + rows in the source tables of the <command>SELECT INTO</command> + statement. Therefore, if <command>SELECT INTO</command> was + frequently executed, the OID counter would be rapidly + incremented. As of PostgreSQL 7.5, the inclusion of OIDs in the + table created by <command>SELECT INTO</command> is controlled by + the <varname>default_with_oids</varname> configuration + variable. This variable currently defaults to true, but will likely + default to false in a future release of <productname>PostgreSQL</>. </para> </refsect1> @@ -96,7 +112,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac <title>Compatibility</title> <para> - The SQL standard uses <command>SELECT ... INTO</command> to + The SQL standard uses <command>SELECT INTO</command> to represent selecting values into scalar variables of a host program, rather than creating a new table. This indeed is the usage found in <application>ECPG</application> (see <xref linkend="ecpg">) and |