Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 7ce9b7c

Browse files
bmomjianbmomjian
committed
This patch adds a new GUC var, "default_with_oids", which follows the
proposal for eventually deprecating OIDs on user tables that I posted earlier to pgsql-hackers. pg_dump now always specifies WITH OIDS or WITHOUT OIDS when dumping a table. The documentation has been updated. Neil Conway
1 parent e7ca867 commit 7ce9b7c

File tree

18 files changed

+218
-90
lines changed

18 files changed

+218
-90
lines changed

‎doc/src/sgml/datatype.sgml

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.134 2003/12/01 20:34:53 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.135 2003/12/01 22:07:55 momjian Exp $
33
-->
44

55
<chapter id="datatype">
@@ -2932,24 +2932,43 @@ SELECT * FROM test;
29322932

29332933
<para>
29342934
Object identifiers (OIDs) are used internally by
2935-
<productname>PostgreSQL</productname> as primary keys for various system
2936-
tables. Also, an OID system column is added to user-created tables
2937-
(unless <literal>WITHOUT OIDS</> is specified at table creation time).
2938-
Type <type>oid</> represents an object identifier. There are also
2939-
several alias types for <type>oid</>: <type>regproc</>, <type>regprocedure</>,
2940-
<type>regoper</>, <type>regoperator</>, <type>regclass</>,
2941-
and <type>regtype</>. <xref linkend="datatype-oid-table"> shows an overview.
2935+
<productname>PostgreSQL</productname> as primary keys for various
2936+
system tables. An OID system column is also added to user-created
2937+
tables, unless <literal>WITHOUT OIDS</literal> is specified when
2938+
the table is created, or the <varname>default_with_oids</varname>
2939+
configuration variable is set to false. Type <type>oid</>
2940+
represents an object identifier. There are also several alias
2941+
types for <type>oid</>: <type>regproc</>, <type>regprocedure</>,
2942+
<type>regoper</>, <type>regoperator</>, <type>regclass</>, and
2943+
<type>regtype</>. <xref linkend="datatype-oid-table"> shows an
2944+
overview.
29422945
</para>
29432946

29442947
<para>
2945-
The <type>oid</> type is currently implemented as an unsigned four-byte
2946-
integer.
2947-
Therefore, it is not large enough to provide database-wide uniqueness
2948-
in large databases, or even in large individual tables. So, using a
2949-
user-created table's OID column as a primary key is discouraged.
2950-
OIDs are best used only for references to system tables.
2948+
The <type>oid</> type is currently implemented as an unsigned
2949+
four-byte integer. Therefore, it is not large enough to provide
2950+
database-wide uniqueness in large databases, or even in large
2951+
individual tables. So, using a user-created table's OID column as
2952+
a primary key is discouraged. OIDs are best used only for
2953+
references to system tables.
29512954
</para>
29522955

2956+
<note>
2957+
<para>
2958+
OIDs are included by default in user-created tables in
2959+
<productname>PostgreSQL</productname> &version;. However, this
2960+
behavior is likely to change in a future version of
2961+
<productname>PostgreSQL</productname>. Eventually, user-created
2962+
tables will not include an OID system column unless <literal>WITH
2963+
OIDS</literal> is specified when the table is created, or the
2964+
<varname>default_with_oids</varname> configuration variable is set
2965+
to true. If your application requires the presence of an OID
2966+
system column in a table, it should specify <literal>WITH
2967+
OIDS</literal> when that table is created to ensure compatibility
2968+
with future releases of <productname>PostgreSQL</productname>.
2969+
</para>
2970+
</note>
2971+
29532972
<para>
29542973
The <type>oid</> type itself has few operations beyond comparison.
29552974
It can be cast to

‎doc/src/sgml/ref/alter_table.sgml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.63 2003/11/29 19:51:38 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.64 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -149,6 +149,12 @@ ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
149149
of the OID are kept indefinitely. This is semantically similar
150150
to the <literal>DROP COLUMN</literal> process.
151151
</para>
152+
153+
<para>
154+
Note that there is no variant of <command>ALTER TABLE</command>
155+
that allows OIDs to be restored to a table once they have been
156+
removed.
157+
</para>
152158
</listitem>
153159
</varlistentry>
154160

‎doc/src/sgml/ref/create_table.sgml

Lines changed: 33 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.76 2003/11/29 19:51:38 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.77 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -111,12 +111,12 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
111111
<para>
112112
If specified, the table is created as a temporary table.
113113
Temporary tables are automatically dropped at the end of a
114-
session, or optionally at the end of the current transaction
115-
(see ON COMMIT below). Existing permanent tables with the same
116-
name are not visible to the current session while the temporary
117-
table exists, unless they are referenced with schema-qualified
118-
names. Any indexes created on a temporary table are automatically
119-
temporary as well.
114+
session, or optionally at the end of the current transaction
115+
(see <literal>ON COMMIT</literal> below). Existing permanent
116+
tables with the same name are not visible to the current session
117+
while the temporary table exists, unless they are referenced
118+
with schema-qualified names. Any indexes created on a temporary
119+
table are automatically temporary as well.
120120
</para>
121121

122122
<para>
@@ -243,22 +243,30 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
243243
<listitem>
244244
<para>
245245
This optional clause specifies whether rows of the new table
246-
should have OIDs (object identifiers) assigned to them. The
247-
default is to have OIDs. (If the new table inherits from any
248-
tables that have OIDs, then <literal>WITH OIDS</> is forced even
249-
if the command says <literal>WITHOUT OIDS</>.)
246+
should have OIDs (object identifiers) assigned to them. If
247+
neither <literal>WITH OIDS</literal> nor <literal>WITHOUT
248+
OIDS</literal> is specified, the default value depends upon the
249+
<varname>default_with_oids</varname> configuration parameter. (If
250+
the new table inherits from any tables that have OIDs, then
251+
<literal>WITH OIDS</> is forced even if the command says
252+
<literal>WITHOUT OIDS</>.)
250253
</para>
251254

252255
<para>
253-
Specifying <literal>WITHOUT OIDS</> allows the user to suppress
254-
generation of OIDs for rows of a table. This may be worthwhile
255-
for large tables, since it will reduce OID consumption and
256-
thereby postpone wraparound of the 32-bit OID counter. Once the
257-
counter wraps around, uniqueness of OIDs can no longer be
258-
assumed, which considerably reduces their usefulness. Specifying
259-
<literal>WITHOUT OIDS</literal> also reduces the space required
260-
to store the table on disk by 4 bytes per row of the table,
261-
thereby improving performance.
256+
If <literal>WITHOUT OIDS</literal> is specified or implied, this
257+
means that the generation of OIDs for this table will be
258+
supressed. This is generally considered worthwhile, since it
259+
will reduce OID consumption and thereby postpone the wraparound
260+
of the 32-bit OID counter. Once the counter wraps around, OIDs
261+
can no longer be assumed to be unique, which makes them
262+
considerably less useful. In addition, excluding OIDs from a
263+
table reduces the space required on disk to storage the table by
264+
4 bytes per row, leading to increased performance.
265+
</para>
266+
267+
<para>
268+
To remove OIDs from a table after it has been created, use <xref
269+
linkend="sql-altertable" endterm="sql-altertable-title">.
262270
</para>
263271
</listitem>
264272
</varlistentry>
@@ -572,18 +580,17 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
572580
<itemizedlist>
573581
<listitem>
574582
<para>
575-
Whenever an application makes use of OIDs to identify specific
583+
Using OIDs in new applications is not recommended: where
584+
possible, using a <literal>SERIAL</literal> or other sequence
585+
generator as the table's primary key is preferred. However, if
586+
your application does make use of OIDs to identify specific rows
576587
rows of a table, it is recommended to create a unique constraint
577588
on the <structfield>oid</> column of that table, to ensure that
578589
OIDs in the table will indeed uniquely identify rows even after
579590
counter wraparound. Avoid assuming that OIDs are unique across
580591
tables; if you need a database-wide unique identifier, use the
581592
combination of <structfield>tableoid</> and row OID for the
582-
purpose. (It is likely that future <productname>PostgreSQL</>
583-
releases will use a separate OID counter for each table, so that
584-
it will be <emphasis>necessary</>, not optional, to include
585-
<structfield>tableoid</> to have a unique identifier
586-
database-wide.)
593+
purpose.
587594
</para>
588595

589596
<tip>

‎doc/src/sgml/ref/create_table_as.sgml

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.17 2003/11/29 19:51:38 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.18 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -51,7 +51,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
5151

5252
<refsect1>
5353
<title>Parameters</title>
54-
54+
55+
<variablelist>
56+
<varlistentry>
57+
<term><literal>GLOBAL</literal> or <literal>LOCAL</literal></term>
58+
<listitem>
59+
<para>
60+
Ignored for compatibility. Refer to <xref
61+
linkend="sql-createtable" endterm="sql-createtable-title"> for
62+
details.
63+
</para>
64+
</listitem>
65+
</varlistentry>
66+
</variablelist>
67+
5568
<variablelist>
5669
<varlistentry>
5770
<term><literal>TEMPORARY</> or <literal>TEMP</></term>
@@ -105,10 +118,24 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
105118
<title>Notes</title>
106119

107120
<para>
108-
This command is functionally equivalent to <xref
109-
linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is preferred since it is less
110-
likely to be confused with other uses of the <command>SELECT
111-
... INTO</command> syntax.
121+
This command is functionally similar to <xref
122+
linkend="sql-selectinto" endterm="sql-selectinto-title">, but it is
123+
preferred since it is less likely to be confused with other uses of
124+
the <command>SELECT INTO</command> syntax.
125+
</para>
126+
127+
<para>
128+
Prior to PostgreSQL 7.5, <command>CREATE TABLE AS</command> always
129+
included OIDs in the table it produced. Furthermore, these OIDs
130+
were newly generated: they were distinct from the OIDs of any of
131+
the rows in the source tables of the <command>SELECT</command> or
132+
<command>EXECUTE</command> statement. Therefore, if <command>CREATE
133+
TABLE AS</command> was frequently executed, the OID counter would
134+
be rapidly incremented. As of PostgreSQL 7.5, the inclusion of OIDs
135+
in the table generated by <command>CREATE TABLE AS</command> is
136+
controlled by the <varname>default_with_oids</varname> configuration
137+
variable. This variable currently defaults to true, but will likely
138+
default to false in a future release of <productname>PostgreSQL</>.
112139
</para>
113140
</refsect1>
114141

@@ -129,7 +156,6 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
129156

130157
<simplelist type="inline">
131158
<member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
132-
<member><xref linkend="sql-createview" endterm="sql-createview-title"></member>
133159
<member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
134160
<member><xref linkend="sql-select" endterm="sql-select-title"></member>
135161
<member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>

‎doc/src/sgml/ref/pg_dump.sgml

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.67 2003/11/29 19:51:39 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.68 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -611,8 +611,11 @@ CREATE DATABASE foo WITH TEMPLATE template0;
611611
</para>
612612

613613
<para>
614-
Once restored, it is wise to run <command>ANALYZE</> on each
615-
restored table so the optimizer has useful statistics.
614+
The dump file produced by <application>pg_dump</application> does
615+
not contain the statistics used by the optimizer to make query
616+
planning decisions. Therefore, it is wise to run
617+
<command>ANALYZE</command> after restoring from a dump file to
618+
ensure good performance.
616619
</para>
617620

618621
</refsect1>

‎doc/src/sgml/ref/prepare.sgml

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.8 2003/11/29 19:51:39 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.9 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -52,13 +52,12 @@ PREPARE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable c
5252
</para>
5353

5454
<para>
55-
Prepared statements are only stored in and for the duration of
56-
the current database session. When
57-
the session ends, the prepared statement is forgotten, and so it must be
58-
recreated before being used again. This also means that a single
59-
prepared statement cannot be used by multiple simultaneous database
60-
clients; however, each client can create their own prepared statement
61-
to use.
55+
Prepared statements are only for the duration of the current
56+
database session. When the session ends, the prepared statement is
57+
forgotten, so it must be recreated before being used again. This
58+
also means that a single prepared statement cannot be used by
59+
multiple simultaneous database clients; however, each client can
60+
create their own prepared statement to use.
6261
</para>
6362

6463
<para>

‎doc/src/sgml/ref/select_into.sgml

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.25 2003/11/29 19:51:39 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.26 2003/12/01 22:07:58 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -82,21 +82,37 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
8282
<title>Notes</title>
8383

8484
<para>
85-
<xref linkend="sql-createtableas" endterm="sql-createtableas-title">
86-
is functionally equivalent to <command>SELECT INTO</command>.
87-
<command>CREATE TABLE AS</command> is the recommended syntax, since
88-
this form of <command>SELECT INTO</command> is not available in
89-
<application>ECPG</application> or
90-
<application>PL/pgSQL</application>, because they interpret the
91-
<literal>INTO</literal> clause differently.
85+
<xref linkend="sql-createtableas"
86+
endterm="sql-createtableas-title"> is functionally similar to
87+
<command>SELECT INTO</command>. <command>CREATE TABLE AS</command>
88+
is the recommended syntax, since this form of <command>SELECT
89+
INTO</command> is not available in <application>ECPG</application>
90+
or <application>PL/pgSQL</application>, because they interpret the
91+
<literal>INTO</literal> clause differently. Furthermore,
92+
<command>CREATE TABLE AS</command> offers a superset of the
93+
functionality provided by <command>SELECT INTO</command>.
94+
</para>
95+
96+
<para>
97+
Prior to PostgreSQL 7.5, the table created by <command>SELECT
98+
INTO</command> always included OIDs. Furthermore, these OIDs were
99+
newly generated: they were distinct from the OIDs of any of the
100+
rows in the source tables of the <command>SELECT INTO</command>
101+
statement. Therefore, if <command>SELECT INTO</command> was
102+
frequently executed, the OID counter would be rapidly
103+
incremented. As of PostgreSQL 7.5, the inclusion of OIDs in the
104+
table created by <command>SELECT INTO</command> is controlled by
105+
the <varname>default_with_oids</varname> configuration
106+
variable. This variable currently defaults to true, but will likely
107+
default to false in a future release of <productname>PostgreSQL</>.
92108
</para>
93109
</refsect1>
94110

95111
<refsect1>
96112
<title>Compatibility</title>
97113

98114
<para>
99-
The SQL standard uses <command>SELECT ... INTO</command> to
115+
The SQL standard uses <command>SELECT INTO</command> to
100116
represent selecting values into scalar variables of a host program,
101117
rather than creating a new table. This indeed is the usage found
102118
in <application>ECPG</application> (see <xref linkend="ecpg">) and

‎doc/src/sgml/runtime.sgml

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.223 2003/11/29 19:51:37 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.224 2003/12/01 22:07:56 momjian Exp $
33
-->
44

55
<Chapter Id="runtime">
@@ -2433,7 +2433,38 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
24332433
</listitem>
24342434
</varlistentry>
24352435

2436-
</variablelist>
2436+
<varlistentry>
2437+
<term><varname>default_with_oids</varname> (<type>boolean</type>)</term>
2438+
<listitem>
2439+
<para>
2440+
This controls whether <command>CREATE TABLE</command> will
2441+
include OIDs in newly-created tables, if neither <literal>WITH
2442+
OIDS</literal> or <literal>WITHOUT OIDS</literal> have been
2443+
specified. It also determines whether OIDs will be included in
2444+
the table generated by <command>SELECT INTO</command> and
2445+
<command>CREATE TABLE AS</command>. In
2446+
<productname>PostgreSQL</productname> &version;
2447+
<varname>default_with_oids</varname> defaults to true. This is
2448+
also the behavior of previous versions of
2449+
<productname>PostgreSQL</productname>. However, assuming that
2450+
tables will contain OIDs by default is not
2451+
encouraged. Therefore, this option will default to false in a
2452+
future release of <productname>PostgreSQL</productname>.
2453+
</para>
2454+
2455+
<para>
2456+
To ease compatibility with applications that make use of OIDs,
2457+
this option should left enabled. To ease compatibility with
2458+
future versions of <productname>PostgreSQL</productname>, this
2459+
option should be disabled, and applications that require OIDs
2460+
on certain tables should explictely specify <literal>WITH
2461+
OIDS</literal> when issuing the <command>CREATE
2462+
TABLE</command> statements for the tables in question.
2463+
</para>
2464+
</listitem>
2465+
</varlistentry>
2466+
2467+
</variablelist>
24372468
</sect3>
24382469
<sect3 id="runtime-config-compatible-clients">
24392470
<title>Platform and Client Compatibility</title>

0 commit comments

Comments
 (0)