From 7ce9b7c0d8c8dbefc04978765422f760dcf3788c Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Mon, 1 Dec 2003 22:08:02 +0000 Subject: [PATCH] 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 --- doc/src/sgml/datatype.sgml | 47 ++++++++++----- doc/src/sgml/ref/alter_table.sgml | 8 ++- doc/src/sgml/ref/create_table.sgml | 59 +++++++++++-------- doc/src/sgml/ref/create_table_as.sgml | 40 ++++++++++--- doc/src/sgml/ref/pg_dump.sgml | 9 ++- doc/src/sgml/ref/prepare.sgml | 15 +++-- doc/src/sgml/ref/select_into.sgml | 34 ++++++++--- doc/src/sgml/runtime.sgml | 35 ++++++++++- doc/src/sgml/spi.sgml | 6 +- src/backend/executor/execMain.c | 12 ++-- src/backend/parser/gram.y | 10 +++- src/backend/utils/misc/guc.c | 14 ++++- src/backend/utils/misc/postgresql.conf.sample | 3 +- src/bin/pg_dump/pg_dump.c | 5 +- src/bin/psql/tab-complete.c | 3 +- src/include/utils/guc.h | 4 +- src/test/regress/expected/without_oid.out | 2 +- src/test/regress/sql/without_oid.sql | 2 +- 18 files changed, 218 insertions(+), 90 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index a214f5398c..8bae619c3d 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -2932,24 +2932,43 @@ SELECT * FROM test; Object identifiers (OIDs) are used internally by - PostgreSQL as primary keys for various system - tables. Also, an OID system column is added to user-created tables - (unless WITHOUT OIDS is specified at table creation time). - Type oid represents an object identifier. There are also - several alias types for oid: regproc, regprocedure, - regoper, regoperator, regclass, - and regtype. shows an overview. + PostgreSQL as primary keys for various + system tables. An OID system column is also added to user-created + tables, unless WITHOUT OIDS is specified when + the table is created, or the default_with_oids + configuration variable is set to false. Type oid + represents an object identifier. There are also several alias + types for oid: regproc, regprocedure, + regoper, regoperator, regclass, and + regtype. shows an + overview. - The oid type is currently implemented as an unsigned four-byte - integer. - Therefore, it is not large enough to provide database-wide uniqueness - in large databases, or even in large individual tables. So, using a - user-created table's OID column as a primary key is discouraged. - OIDs are best used only for references to system tables. + The oid type is currently implemented as an unsigned + four-byte integer. Therefore, it is not large enough to provide + database-wide uniqueness in large databases, or even in large + individual tables. So, using a user-created table's OID column as + a primary key is discouraged. OIDs are best used only for + references to system tables. + + + OIDs are included by default in user-created tables in + PostgreSQL &version;. However, this + behavior is likely to change in a future version of + PostgreSQL. Eventually, user-created + tables will not include an OID system column unless WITH + OIDS is specified when the table is created, or the + default_with_oids configuration variable is set + to true. If your application requires the presence of an OID + system column in a table, it should specify WITH + OIDS when that table is created to ensure compatibility + with future releases of PostgreSQL. + + + The oid type itself has few operations beyond comparison. It can be cast to diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 9662d9b02f..d10be7f290 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1,5 +1,5 @@ @@ -149,6 +149,12 @@ ALTER TABLE name of the OID are kept indefinitely. This is semantically similar to the DROP COLUMN process. + + + Note that there is no variant of ALTER TABLE + that allows OIDs to be restored to a table once they have been + removed. + diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 00814fa443..4af03bccfa 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1,5 +1,5 @@ @@ -111,12 +111,12 @@ and table_constraint is: 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 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. @@ -243,22 +243,30 @@ and table_constraint is: 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 WITH OIDS is forced even - if the command says WITHOUT OIDS.) + should have OIDs (object identifiers) assigned to them. If + neither WITH OIDS nor WITHOUT + OIDS is specified, the default value depends upon the + default_with_oids configuration parameter. (If + the new table inherits from any tables that have OIDs, then + WITH OIDS is forced even if the command says + WITHOUT OIDS.) - Specifying 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 - WITHOUT OIDS also reduces the space required - to store the table on disk by 4 bytes per row of the table, - thereby improving performance. + If WITHOUT OIDS 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. + + + + To remove OIDs from a table after it has been created, use . @@ -572,18 +580,17 @@ and table_constraint is: - Whenever an application makes use of OIDs to identify specific + Using OIDs in new applications is not recommended: where + possible, using a SERIAL 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 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 tableoid and row OID for the - purpose. (It is likely that future PostgreSQL - releases will use a separate OID counter for each table, so that - it will be necessary, not optional, to include - tableoid to have a unique identifier - database-wide.) + purpose. diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 856846c50b..a7382abfdc 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -1,5 +1,5 @@ @@ -51,7 +51,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name Parameters - + + + + GLOBAL or LOCAL + + + Ignored for compatibility. Refer to for + details. + + + + + TEMPORARY or TEMP @@ -105,10 +118,24 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name Notes - This command is functionally equivalent to , but it is preferred since it is less - likely to be confused with other uses of the SELECT - ... INTO syntax. + This command is functionally similar to , but it is + preferred since it is less likely to be confused with other uses of + the SELECT INTO syntax. + + + + Prior to PostgreSQL 7.5, CREATE TABLE AS 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 SELECT or + EXECUTE statement. Therefore, if CREATE + TABLE AS was frequently executed, the OID counter would + be rapidly incremented. As of PostgreSQL 7.5, the inclusion of OIDs + in the table generated by CREATE TABLE AS is + controlled by the default_with_oids configuration + variable. This variable currently defaults to true, but will likely + default to false in a future release of PostgreSQL. @@ -129,7 +156,6 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name - diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index f02c3638a7..c604123724 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ @@ -611,8 +611,11 @@ CREATE DATABASE foo WITH TEMPLATE template0; - Once restored, it is wise to run ANALYZE on each - restored table so the optimizer has useful statistics. + The dump file produced by pg_dump does + not contain the statistics used by the optimizer to make query + planning decisions. Therefore, it is wise to run + ANALYZE after restoring from a dump file to + ensure good performance. diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index 82e36fe89f..684b4bb8ba 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -1,5 +1,5 @@ @@ -52,13 +52,12 @@ PREPARE plan_name [ ( - 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. diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index cb321f0cfa..1261f3cd4b 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -1,5 +1,5 @@ @@ -82,13 +82,29 @@ SELECT [ ALL | DISTINCT [ ON ( expressionNotes - - is functionally equivalent to SELECT INTO. - CREATE TABLE AS is the recommended syntax, since - this form of SELECT INTO is not available in - ECPG or - PL/pgSQL, because they interpret the - INTO clause differently. + is functionally similar to + SELECT INTO. CREATE TABLE AS + is the recommended syntax, since this form of SELECT + INTO is not available in ECPG + or PL/pgSQL, because they interpret the + INTO clause differently. Furthermore, + CREATE TABLE AS offers a superset of the + functionality provided by SELECT INTO. + + + + Prior to PostgreSQL 7.5, the table created by SELECT + INTO 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 SELECT INTO + statement. Therefore, if SELECT INTO was + frequently executed, the OID counter would be rapidly + incremented. As of PostgreSQL 7.5, the inclusion of OIDs in the + table created by SELECT INTO is controlled by + the default_with_oids configuration + variable. This variable currently defaults to true, but will likely + default to false in a future release of PostgreSQL. @@ -96,7 +112,7 @@ SELECT [ ALL | DISTINCT [ ON ( expressionCompatibility - The SQL standard uses SELECT ... INTO to + The SQL standard uses SELECT INTO to represent selecting values into scalar variables of a host program, rather than creating a new table. This indeed is the usage found in ECPG (see ) and diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 2ee3ca9667..49bf3aa7af 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -2433,7 +2433,38 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - + + default_with_oids (boolean) + + + This controls whether CREATE TABLE will + include OIDs in newly-created tables, if neither WITH + OIDS or WITHOUT OIDS have been + specified. It also determines whether OIDs will be included in + the table generated by SELECT INTO and + CREATE TABLE AS. In + PostgreSQL &version; + default_with_oids defaults to true. This is + also the behavior of previous versions of + PostgreSQL. However, assuming that + tables will contain OIDs by default is not + encouraged. Therefore, this option will default to false in a + future release of PostgreSQL. + + + + To ease compatibility with applications that make use of OIDs, + this option should left enabled. To ease compatibility with + future versions of PostgreSQL, this + option should be disabled, and applications that require OIDs + on certain tables should explictely specify WITH + OIDS when issuing the CREATE + TABLE statements for the tables in question. + + + + + Platform and Client Compatibility diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 36b6d8be2f..aab5b0dae1 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -1,5 +1,5 @@ @@ -320,7 +320,7 @@ typedef struct if a SELECT (but not SELECT - ... INTO) was executed + INTO) was executed @@ -329,7 +329,7 @@ typedef struct SPI_OK_SELINTO - if a SELECT ... INTO was executed + if a SELECT INTO was executed diff --git a/src/backend/executor/execMain.c b/src/backend/executor/execMain.c index 2be2d2d639..e53bb1f704 100644 --- a/src/backend/executor/execMain.c +++ b/src/backend/executor/execMain.c @@ -26,7 +26,7 @@ * * * IDENTIFICATION - * $PostgreSQL: pgsql/src/backend/executor/execMain.c,v 1.222 2003/11/29 19:51:48 pgsql Exp $ + * $PostgreSQL: pgsql/src/backend/executor/execMain.c,v 1.223 2003/12/01 22:07:58 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -43,6 +43,7 @@ #include "optimizer/var.h" #include "parser/parsetree.h" #include "utils/acl.h" +#include "utils/guc.h" #include "utils/lsyscache.h" @@ -593,11 +594,12 @@ InitPlan(QueryDesc *queryDesc, bool explainOnly) do_select_into = true; /* - * For now, always create OIDs in SELECT INTO; this is for - * backwards compatibility with pre-7.3 behavior. Eventually we - * might want to allow the user to choose. + * The presence of OIDs in the result set of SELECT INTO is + * controlled by the default_with_oids GUC parameter. The + * behavior in versions of PostgreSQL prior to 7.5 is to + * always include OIDs. */ - estate->es_force_oids = true; + estate->es_force_oids = default_with_oids; } /* diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y index 9e584281c5..8866200444 100644 --- a/src/backend/parser/gram.y +++ b/src/backend/parser/gram.y @@ -11,7 +11,7 @@ * * * IDENTIFICATION - * $PostgreSQL: pgsql/src/backend/parser/gram.y,v 2.440 2003/11/29 19:51:51 pgsql Exp $ + * $PostgreSQL: pgsql/src/backend/parser/gram.y,v 2.441 2003/12/01 22:07:58 momjian Exp $ * * HISTORY * AUTHOR DATE MAJOR EVENT @@ -63,6 +63,7 @@ #include "utils/numeric.h" #include "utils/datetime.h" #include "utils/date.h" +#include "utils/guc.h" extern List *parsetree; /* final parse result is delivered here */ @@ -1822,7 +1823,12 @@ OptInherit: INHERITS '(' qualified_name_list ')' { $$ = $3; } OptWithOids: WITH OIDS { $$ = TRUE; } | WITHOUT OIDS { $$ = FALSE; } - | /*EMPTY*/ { $$ = TRUE; } + /* + * If the user didn't explicitely specify WITH or WITHOUT + * OIDS, decide whether to include OIDs based on the + * "default_with_oids" GUC var + */ + | /*EMPTY*/ { $$ = default_with_oids; } ; OnCommitOption: ON COMMIT DROP { $$ = ONCOMMIT_DROP; } diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c index 030dd9033c..18cd7e147e 100644 --- a/src/backend/utils/misc/guc.c +++ b/src/backend/utils/misc/guc.c @@ -10,7 +10,7 @@ * Written by Peter Eisentraut . * * IDENTIFICATION - * $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.173 2003/12/01 03:55:21 momjian Exp $ + * $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.174 2003/12/01 22:08:00 momjian Exp $ * *-------------------------------------------------------------------- */ @@ -126,6 +126,8 @@ bool Australian_timezones = false; bool Password_encryption = true; +bool default_with_oids = true; + int log_min_error_statement = PANIC; int log_min_messages = NOTICE; int client_min_messages = NOTICE; @@ -263,7 +265,7 @@ const char *const config_group_names[] = /* QUERY_TUNING */ gettext_noop("Query Tuning"), /* QUERY_TUNING_METHOD */ - gettext_noop("Query Tuning / Planner Method Enabling"), + gettext_noop("Query Tuning / Planner Method Configuration"), /* QUERY_TUNING_COST */ gettext_noop("Query Tuning / Planner Cost Constants"), /* QUERY_TUNING_GEQO */ @@ -831,6 +833,14 @@ static struct config_bool ConfigureNamesBool[] = &check_function_bodies, true, NULL, NULL }, + { + {"default_with_oids", PGC_USERSET, COMPAT_OPTIONS_PREVIOUS, + gettext_noop("By default, newly-created tables should have OIDs"), + NULL + }, + &default_with_oids, + true, NULL, NULL + }, /* End-of-list marker */ { diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index e4305d9859..98d4d76d3a 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -100,7 +100,7 @@ # QUERY TUNING #--------------------------------------------------------------------------- -# - Planner Method Enabling - +# - Planner Method Configuration - #enable_hashagg = true #enable_hashjoin = true @@ -255,6 +255,7 @@ #add_missing_from = true #regex_flavor = advanced # advanced, extended, or basic #sql_inheritance = true +#default_with_oids = true # - Other Platforms & Clients - diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c index 15b4ebd970..029f30f664 100644 --- a/src/bin/pg_dump/pg_dump.c +++ b/src/bin/pg_dump/pg_dump.c @@ -12,7 +12,7 @@ * by PostgreSQL * * IDENTIFICATION - * $PostgreSQL: pgsql/src/bin/pg_dump/pg_dump.c,v 1.358 2003/11/29 19:52:05 pgsql Exp $ + * $PostgreSQL: pgsql/src/bin/pg_dump/pg_dump.c,v 1.359 2003/12/01 22:08:01 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -5627,8 +5627,7 @@ dumpOneTable(Archive *fout, TableInfo *tbinfo, TableInfo *g_tblinfo) appendPQExpBuffer(q, ")"); } - if (!tbinfo->hasoids) - appendPQExpBuffer(q, " WITHOUT OIDS"); + appendPQExpBuffer(q, tbinfo->hasoids ? " WITH OIDS" : " WITHOUT OIDS"); appendPQExpBuffer(q, ";\n"); diff --git a/src/bin/psql/tab-complete.c b/src/bin/psql/tab-complete.c index f7e346478a..c50ce514d1 100644 --- a/src/bin/psql/tab-complete.c +++ b/src/bin/psql/tab-complete.c @@ -3,7 +3,7 @@ * * Copyright (c) 2000-2003, PostgreSQL Global Development Group * - * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.94 2003/11/29 19:52:07 pgsql Exp $ + * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.95 2003/12/01 22:08:01 momjian Exp $ */ /*---------------------------------------------------------------------- @@ -499,6 +499,7 @@ psql_completion(char *text, int start, int end) "default_statistics_target", "default_transaction_isolation", "default_transaction_read_only", + "default_with_oids", "dynamic_library_path", "effective_cache_size", "enable_hashagg", diff --git a/src/include/utils/guc.h b/src/include/utils/guc.h index b92cd68dc9..29d731146d 100644 --- a/src/include/utils/guc.h +++ b/src/include/utils/guc.h @@ -7,7 +7,7 @@ * Copyright (c) 2000-2003, PostgreSQL Global Development Group * Written by Peter Eisentraut . * - * $PostgreSQL: pgsql/src/include/utils/guc.h,v 1.42 2003/11/29 22:41:15 pgsql Exp $ + * $PostgreSQL: pgsql/src/include/utils/guc.h,v 1.43 2003/12/01 22:08:02 momjian Exp $ *-------------------------------------------------------------------- */ #ifndef GUC_H @@ -109,6 +109,8 @@ extern bool log_btree_build_stats; extern bool SQL_inheritance; extern bool Australian_timezones; +extern bool default_with_oids; + extern int log_min_error_statement; extern int log_min_messages; extern int client_min_messages; diff --git a/src/test/regress/expected/without_oid.out b/src/test/regress/expected/without_oid.out index c25d4e3640..23a89a06c5 100644 --- a/src/test/regress/expected/without_oid.out +++ b/src/test/regress/expected/without_oid.out @@ -1,7 +1,7 @@ -- -- WITHOUT OID -- -CREATE TABLE wi (i INT); +CREATE TABLE wi (i INT) WITH OIDS; CREATE TABLE wo (i INT) WITHOUT OIDS; INSERT INTO wi VALUES (1); -- 1 INSERT INTO wo SELECT i FROM wi; -- 1 diff --git a/src/test/regress/sql/without_oid.sql b/src/test/regress/sql/without_oid.sql index dcef735e81..727e743d02 100644 --- a/src/test/regress/sql/without_oid.sql +++ b/src/test/regress/sql/without_oid.sql @@ -2,7 +2,7 @@ -- WITHOUT OID -- -CREATE TABLE wi (i INT); +CREATE TABLE wi (i INT) WITH OIDS; CREATE TABLE wo (i INT) WITHOUT OIDS; INSERT INTO wi VALUES (1); -- 1 INSERT INTO wo SELECT i FROM wi; -- 1