From 0c1fe3d2b99a658b2fe03e27338e819b52357cf3 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 23 Apr 2002 02:07:16 +0000 Subject: [PATCH] Update SQL-command reference pages for schema features. --- doc/src/sgml/ref/alter_database.sgml | 14 +- doc/src/sgml/ref/alter_table.sgml | 191 +++++++++++++++++------- doc/src/sgml/ref/analyze.sgml | 5 +- doc/src/sgml/ref/cluster.sgml | 4 +- doc/src/sgml/ref/comment.sgml | 10 +- doc/src/sgml/ref/copy.sgml | 4 +- doc/src/sgml/ref/create_aggregate.sgml | 18 ++- doc/src/sgml/ref/create_constraint.sgml | 7 +- doc/src/sgml/ref/create_domain.sgml | 25 ++-- doc/src/sgml/ref/create_function.sgml | 18 ++- doc/src/sgml/ref/create_index.sgml | 12 +- doc/src/sgml/ref/create_operator.sgml | 16 +- doc/src/sgml/ref/create_sequence.sgml | 17 ++- doc/src/sgml/ref/create_table.sgml | 25 +++- doc/src/sgml/ref/create_table_as.sgml | 20 +-- doc/src/sgml/ref/create_type.sgml | 24 +-- doc/src/sgml/ref/create_view.sgml | 24 ++- doc/src/sgml/ref/delete.sgml | 4 +- doc/src/sgml/ref/drop_aggregate.sgml | 8 +- doc/src/sgml/ref/drop_domain.sgml | 4 +- doc/src/sgml/ref/drop_function.sgml | 6 +- doc/src/sgml/ref/drop_index.sgml | 4 +- doc/src/sgml/ref/drop_operator.sgml | 6 +- doc/src/sgml/ref/drop_rule.sgml | 5 +- doc/src/sgml/ref/drop_sequence.sgml | 4 +- doc/src/sgml/ref/drop_table.sgml | 14 +- doc/src/sgml/ref/drop_trigger.sgml | 6 +- doc/src/sgml/ref/drop_type.sgml | 4 +- doc/src/sgml/ref/drop_view.sgml | 8 +- doc/src/sgml/ref/insert.sgml | 4 +- doc/src/sgml/ref/lock.sgml | 4 +- doc/src/sgml/ref/reindex.sgml | 5 +- doc/src/sgml/ref/select.sgml | 15 +- doc/src/sgml/ref/select_into.sgml | 16 +- doc/src/sgml/ref/truncate.sgml | 4 +- doc/src/sgml/ref/update.sgml | 4 +- doc/src/sgml/ref/vacuum.sgml | 6 +- doc/src/sgml/reference.sgml | 6 +- 38 files changed, 366 insertions(+), 205 deletions(-) diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml index b1aa34262a..a7e81d22d9 100644 --- a/doc/src/sgml/ref/alter_database.sgml +++ b/doc/src/sgml/ref/alter_database.sgml @@ -1,5 +1,5 @@ @@ -28,15 +28,16 @@ ALTER DATABASE name RESET ALTER DATABASE is used to change the session default of a run-time configuration variable for a PostgreSQL database. Whenever a new - session is subsequently started, SET + session is subsequently started in that database, SET variable TO value is effectively executed - before the start of the session. + before the start of the session. The database-specific default + overrides whatever setting is present in postgresql.conf + or has been received from the postmaster. - Only a database owner can change the session defaults for a - database. Superusers can change the session defaults of any + Only a superuser or the database owner can change the session defaults for a database. @@ -113,7 +114,8 @@ ALTER DATABASE name RESET Using , it is also possible to tie a session default to a specific user - rather than a database. + rather than a database. User-specific settings override database-specific + ones if there is a conflict. diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 6c9c01c885..b131a11638 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1,5 +1,5 @@ @@ -24,23 +24,22 @@ PostgreSQL documentation ALTER TABLE [ ONLY ] table [ * ] ADD [ COLUMN ] column type [ column_constraint [ ... ] ] ALTER TABLE [ ONLY ] table [ * ] - ALTER [ COLUMN ] column { SET DEFAULT value | DROP DEFAULT } + ALTER [ COLUMN ] column { SET DEFAULT value | DROP DEFAULT } ALTER TABLE [ ONLY ] table [ * ] ALTER [ COLUMN ] column { SET | DROP } NOT NULL ALTER TABLE [ ONLY ] table [ * ] ALTER [ COLUMN ] column SET STATISTICS integer ALTER TABLE [ ONLY ] table [ * ] - ALTER [ COLUMN ] column SET STORAGE {PLAIN | EXTERNAL | EXTENDED | MAIN} + ALTER [ COLUMN ] column SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } ALTER TABLE [ ONLY ] table [ * ] RENAME [ COLUMN ] column TO newcolumn + class="PARAMETER">new_column ALTER TABLE table RENAME TO new_table ALTER TABLE table ADD table_constraint_definition ALTER TABLE [ ONLY ] table - DROP CONSTRAINT constraint { RESTRICT | CASCADE } + DROP CONSTRAINT constraint_name { RESTRICT | CASCADE } ALTER TABLE table OWNER TO new_owner @@ -58,7 +57,7 @@ ALTER TABLE table table - The name of an existing table to alter. + The name (possibly schema-qualified) of an existing table to alter. @@ -82,7 +81,7 @@ ALTER TABLE table - newcolumn + new_column New name for an existing column. @@ -103,7 +102,16 @@ ALTER TABLE table table_constraint_definition - New table constraint for the table + New table constraint for the table. + + + + + + constraint_name + + + Name of an existing constraint to drop. @@ -162,44 +170,124 @@ ALTER TABLE table ALTER TABLE changes the definition of an existing table. - The ADD COLUMN form adds a new column to the table - using the same syntax as . - The ALTER COLUMN SET/DROP DEFAULT forms - allow you to set or remove the default for the column. Note that defaults - only apply to subsequent INSERT commands; they do not - cause rows already in the table to change. - The ALTER COLUMN SET/DROP NOT NULL forms allow you to - change whether a column is marked to allow NULL values or to reject NULL - values. - The ALTER COLUMN SET STATISTICS form allows you to - set the statistics-gathering target for subsequent - operations. - The ALTER COLUMN SET STORAGE form allows the - column storage mode to be set. This controls whether this column is - held inline or in a supplementary table, and whether the data - should be compressed or not. PLAIN must be used - for fixed-length values such as INTEGER and is - inline, uncompressed. MAIN is for inline, - compressible data. EXTERNAL is for external, - uncompressed data and EXTENDED is for external, - compressed data. The use of EXTERNAL will make - substring operations on a column faster, at the penalty of - increased storage space. - The RENAME clause causes the name of a table, - column, index, sequence or view to change without changing any of the - data. The data will remain of the same type and size after the - command is executed. - The ADD table_constraint_definition clause - adds a new constraint to the table using the same syntax as . - The DROP CONSTRAINT constraint clause - drops all constraints on the table (and its children) that match constraint. - The OWNER clause changes the owner of the table, index, sequence or view to the - user new user. + There are several sub-forms: + + + + ADD COLUMN + + + This form adds a new column to the table using the same syntax as + . + + + + + + SET/DROP DEFAULT + + + These forms set or remove the default value for a column. Note + that defaults only apply to subsequent INSERT + commands; they do not cause rows already in the table to change. + Defaults may also be created for views, in which case they are + inserted into INSERT statements on the view before + the view's ON INSERT rule is applied. + + + + + + SET/DROP NOT NULL + + + These forms change whether a column is marked to allow NULL + values or to reject NULL values. You may only SET NOT NULL + when the table contains no NULLs in the column. + + + + + + SET STATISTICS + + + This form + sets the per-column statistics-gathering target for subsequent + operations. + + + + + + SET STORAGE + + + This form sets the storage mode for a column. This controls whether this + column is held inline or in a supplementary table, and whether the data + should be compressed or not. PLAIN must be used + for fixed-length values such as INTEGER and is + inline, uncompressed. MAIN is for inline, + compressible data. EXTERNAL is for external, + uncompressed data and EXTENDED is for external, + compressed data. EXTENDED is the default for all + datatypes that support it. The use of EXTERNAL will + make substring operations on a TEXT column faster, at the penalty of + increased storage space. + + + + + + RENAME + + + The RENAME forms change the name of a table + (or an index, sequence, or view) or the name of an individual column in + a table. There is no effect on the stored data. + + + + + + ADD table_constraint_definition + + + This form adds a new constraint to a table using the same syntax as + . + + + + + + DROP CONSTRAINT + + + This form drops constraints on a table (and its children). + Currently, constraints on tables are not required to have unique + names, so there may be more than one constraint matching the specified + name. All such constraints will be dropped. + + + + + + OWNER + + + This form changes the owner of the table, index, sequence or view to the + specified user. + + + + + + - You must own the table in order to change its schema. + You must own the table to use ALTER TABLE; except for + ALTER TABLE OWNER, which may only be executed by a superuser. @@ -216,16 +304,20 @@ ALTER TABLE table In the current implementation of ADD COLUMN, default and NOT NULL clauses for the new column are not supported. + The new column always comes into being with all values NULL. You can use the SET DEFAULT form - of ALTER TABLE to set the default later. + of ALTER TABLE to set the default afterwards. (You may also want to update the already existing rows to the - new default value, using .) + new default value, using + .) + If you want to mark the column non-null, use the SET NOT NULL + form after you've entered non-null values for the column in all rows. In DROP CONSTRAINT, the RESTRICT keyword is required, although dependencies are not yet checked. The CASCADE option is unsupported. - Currently DROP CONSTRAINT drops only CHECK constraints. + Currently DROP CONSTRAINT only handles CHECK constraints. To remove a PRIMARY or UNIQUE constraint, drop the relevant index using the command. To remove FOREIGN KEY constraints you need to recreate @@ -243,16 +335,15 @@ DROP TABLE temp; - You must own the table in order to change it. Changing any part of the schema of a system catalog is not permitted. - The PostgreSQL User's Guide has further - information on inheritance. Refer to CREATE TABLE for a further description of valid arguments. + The PostgreSQL User's Guide has further + information on inheritance. diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 7c92bb614f..5fbef560de 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -1,5 +1,5 @@ @@ -46,7 +46,8 @@ ANALYZE [ VERBOSE ] [ table [ (table - The name of a specific table to analyze. Defaults to all tables. + The name (possibly schema-qualified) of a specific table to + analyze. Defaults to all tables in the current database. diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 8bd948ef58..c8499ca058 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -1,5 +1,5 @@ @@ -46,7 +46,7 @@ CLUSTER indexname ON table - The name of a table. + The name (possibly schema-qualified) of a table. diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index 27d4f3f016..ae6092f1a2 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -1,5 +1,5 @@ @@ -44,11 +44,13 @@ COMMENT ON - object_name, table_name, - column_name, agg_name, func_name, op, rule_name, trigger_name + object_name, + table_name.column_name, agg_name, func_name, op, rule_name, trigger_name - The name of the object to be be commented. + The name of the object to be be commented. Names of tables, + indexes, sequences, views, types, domains, functions, aggregates, + and operators may be schema-qualified. diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index a2bbd1c0aa..95958e9580 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -1,5 +1,5 @@ @@ -56,7 +56,7 @@ COPY [ BINARY ] table [ WITH OIDS ] table - The name of an existing table. + The name (possibly schema-qualified) of an existing table. diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index babbaedbc4..0c326b6f8d 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -1,5 +1,5 @@ @@ -41,7 +41,8 @@ CREATE AGGREGATE name ( BASETYPE = name - The name of an aggregate function to create. + The name (optionally schema-qualified) of an aggregate function to + create. @@ -163,12 +164,19 @@ CREATE already provided, then CREATE AGGREGATE can be used to provide the desired features. + + If a schema name is given (for example, CREATE AGGREGATE + myschema.myagg ...) then the aggregate function is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + An aggregate function is identified by its name and input data type. - Two aggregates can have the same name if they operate on different - input types. The + Two aggregates in the same schema can have the same name if they operate on + different input types. The name and input data type of an aggregate must also be distinct from - the name and input data type of every ordinary function. + the name and input data type(s) of every ordinary function in the same + schema. An aggregate function is made from one or two ordinary diff --git a/doc/src/sgml/ref/create_constraint.sgml b/doc/src/sgml/ref/create_constraint.sgml index 76d41fd345..c5af73ad42 100644 --- a/doc/src/sgml/ref/create_constraint.sgml +++ b/doc/src/sgml/ref/create_constraint.sgml @@ -1,5 +1,5 @@ @@ -56,7 +56,8 @@ CREATE CONSTRAINT TRIGGER name relation - Table name of the triggering relation. + The name (possibly schema-qualified) of the relation in which + the triggering events occur. @@ -118,7 +119,7 @@ CREATE CONSTRAINT Description - CREATE CONSTRAINT TRIGGER is used from inside of + CREATE CONSTRAINT TRIGGER is used within CREATE/ALTER TABLE and by pg_dump to create the special triggers for referential integrity. diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml index 222d49da5d..6a8401a62b 100644 --- a/doc/src/sgml/ref/create_domain.sgml +++ b/doc/src/sgml/ref/create_domain.sgml @@ -1,5 +1,5 @@ @@ -47,7 +47,7 @@ where constraint is: domainname - The name of a domain to be created. + The name (optionally schema-qualified) of a domain to be created. @@ -56,7 +56,8 @@ where constraint is: data_type - The data type of the domain. This may include array specifiers. + The underlying data type of the domain. This may include array + specifiers. Refer to the User's Guide for further information about data types and arrays. @@ -167,12 +168,18 @@ CREATE DOMAIN - CREATE DOMAIN allows the user to register a new user data - domain with PostgreSQL for use in the current data base. The - user who defines a domain becomes its owner. - domainname is - the name of the new type and must be unique within the - types and domains defined for this database. + CREATE DOMAIN allows the user to register a new + data domain with PostgreSQL for use in the + current data base. The user who defines a domain becomes its owner. + + + + If a schema name is given (for example, CREATE DOMAIN + myschema.mydomain ...) then the domain is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + The domain name must be unique among the types and domains existing + in its schema. diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 9c47721dc5..1896133653 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ @@ -44,9 +44,14 @@ CREATE [ OR REPLACE ] FUNCTION name - The name of a function to create. The name need not be unique, - because functions may be overloaded, but functions with the - same name must have different argument types. + The name of a function to create. If a schema name is included, + then the function is created in the + specified schema. Otherwise it is created in the current schema (the + one at the front of the search path; see CURRENT_SCHEMA()). + The name of the new function must not match any existing function + with the same argument types in the same schema. However, functions of + different argument types may share a name (this is called + overloading). @@ -332,8 +337,9 @@ CREATE [ OR REPLACE ] FUNCTION name A function that has one parameter and is named the same as its output - datatype is considered to be a type coercion function: - it can be invoked to convert a value of its input datatype into a value + datatype (including the schema name) is considered to be a type + coercion function: it can be invoked to convert a value of its input + datatype into a value of its output datatype. For example, SELECT CAST(42 AS text); diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index b59fd6bd28..637d4965a4 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -1,5 +1,5 @@ @@ -56,7 +56,9 @@ CREATE [ UNIQUE ] INDEX index_name index_name - The name of the index to be created. + The name of the index to be created. No schema name can be included + here; the index is always created in the same schema as its parent + table. @@ -65,7 +67,7 @@ CREATE [ UNIQUE ] INDEX index_name table - The name of the table to be indexed. + The name (possibly schema-qualified) of the table to be indexed. @@ -270,11 +272,11 @@ ERROR: Cannot create index: 'index_name' already exists. All functions and operators used in an index definition must be - cacheable, that is, their results must depend only on + immutable, that is, their results must depend only on their input arguments and never on any outside influence (such as the contents of another table or the current time). This restriction ensures that the behavior of the index is well-defined. To use a - user-defined function in an index, remember to mark the function cacheable + user-defined function in an index, remember to mark the function immutable when you create it. diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index beaf292fb0..b1371140f1 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -1,5 +1,5 @@ @@ -46,6 +46,8 @@ CREATE OPERATOR name ( PROCEDURE = The operator to be defined. See below for allowable characters. + The name may be schema-qualified, for example + CREATE OPERATOR myschema.+ (...). @@ -199,6 +201,18 @@ CREATE name. The user who defines an operator becomes its owner. + + If a schema name is given then the operator is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + + + Two operators in the same schema can have the same name if they operate on + different data types. This is called overloading. The + system will attempt to pick the intended operator based on the actual + input data types when there is ambiguity. + + The operator name is a sequence of up to NAMEDATALEN-1 (31 by default) characters diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 1199ee4b64..5df6618bfa 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -1,5 +1,5 @@ @@ -43,7 +43,8 @@ CREATE [ TEMPORARY | TEMP ] SEQUENCE seqname @@ -52,7 +53,7 @@ CREATE [ TEMPORARY | TEMP ] SEQUENCE seqnameseqname - The name of a sequence to be created. + The name (optionally schema-qualified) of a sequence to be created. @@ -228,6 +229,16 @@ ERROR: DefineSequence: MINVALUE (min + + If a schema name is given then the sequence is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + TEMP sequences exist in a special schema, so a schema name may not be + given when creating a TEMP sequence. + The sequence name must be distinct from the name of any other sequence, + table, index, or view in the same schema. + + After a sequence is created, you use the functions nextval, diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 671a49d739..936fe1ba3c 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1,5 +1,5 @@ @@ -54,17 +54,27 @@ and table_constraint is: command. + + If a schema name is given (for example, CREATE TABLE + myschema.mytable ...) then the table is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + TEMP tables exist in a special schema, so a schema name may not be + given when creating a TEMP table. + The table name must be distinct from the name of any other table, + sequence, index, or view in the same schema. + + CREATE TABLE also automatically creates a data type that represents the tuple type (structure type) corresponding to one row of the table. Therefore, tables cannot have the same - name as any existing data type. + name as any existing data type in the same schema. A table cannot have more than 1600 columns. (In practice, the - effective limit is lower because of tuple-length constraints). A - table cannot have the same name as a system catalog table. + effective limit is lower because of tuple-length constraints). @@ -97,8 +107,9 @@ 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. Existing persistent tables with the same name are not - visible to the current session while the temporary table exists. + session. 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. @@ -115,7 +126,7 @@ and table_constraint is: table_name - The name of the table to be created. + The name (optionally schema-qualified) of the table to be created. diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index b18e9cdccf..d027ff506f 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -1,5 +1,5 @@ @@ -42,8 +42,8 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE table_nameSELECT statements whenever it is + source tables of the query. In contrast, a view re-evaluates its + defining SELECT statement whenever it is queried. @@ -57,15 +57,7 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name If specified, the table is created as a temporary table. - Temporary tables are automatically dropped at the end of a - session. Existing persistent tables with the same name are not - visible to the current session while the temporary table exists. - Any indexes created on a temporary table are automatically - temporary as well. - - - - The LOCAL word is optional. + Refer to for details. @@ -74,9 +66,7 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE table_nametable_name - The name of the new table to be created. This table must not - already exist. However, a temporary table can be created that - has the same name as an existing permanent table. + The name (optionally schema-qualified) of the table to be created. diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 922497255b..82847df7d7 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -1,5 +1,5 @@ @@ -48,7 +48,7 @@ CREATE TYPE typename ( INPUT = typename - The name of a type to be created. + The name (optionally schema-qualified) of a type to be created. @@ -208,12 +208,18 @@ CREATE - CREATE TYPE allows the user to register a new user data - type with PostgreSQL for use in the current data base. The - user who defines a type becomes its owner. - typename is - the name of the new type and must be unique within the - types defined for this database. + CREATE TYPE allows the user to register a new data + type with PostgreSQL for use in the current data base. + The user who defines a type becomes its owner. + + + + If a schema name is given then the type is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + The type name must be distinct from the name of any existing type or + domain in the same schema. (Because tables have associated datatypes, + type names also must not conflict with table names in the same schema.) @@ -361,7 +367,7 @@ CREATE accessed like point[0] and point[1]. Note that this facility only works for fixed-length types whose internal form - is exactly a sequence of N identical fields. A subscriptable + is exactly a sequence of N identical fixed-length fields. A subscriptable variable-length type must have the generalized internal representation used by array_in and array_out. For historical reasons (i.e., this is clearly wrong but it's far too diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index f40bee7d2a..f7fa744366 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -1,5 +1,5 @@ @@ -39,7 +39,7 @@ class="PARAMETER">column name list ) ] AS SELECT view - The name of a view to be created. + The name (optionally schema-qualified) of a view to be created. @@ -57,10 +57,11 @@ class="PARAMETER">column name list ) ] AS SELECT query - An SQL query which will provide the columns and rows of the view. + An SQL query (that is, a SELECT statement) + which will provide the columns and rows of the view. - Refer to the SELECT statement for more information + Refer to for more information about valid arguments. @@ -132,10 +133,19 @@ CREATE VIEW vista AS SELECT text 'Hello World' Description - CREATE VIEW will define a view of a table. + CREATE VIEW will define a view of a query. The view is not physically materialized. Instead, a query - rewrite retrieve rule is automatically generated to support - retrieve operations on views. + rewrite rule (an ON SELECT rule) is automatically generated to + support SELECT operations on views. + + + + If a schema name is given (for example, CREATE VIEW + myschema.myview ...) then the view is created in the + specified schema. Otherwise it is created in the current schema (the one + at the front of the search path; see CURRENT_SCHEMA()). + The view name must be distinct from the name of any other view, table, + sequence, or index in the same schema. diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index ac5c699cf8..e821d5e3cb 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -1,5 +1,5 @@ @@ -38,7 +38,7 @@ DELETE FROM [ ONLY ] table [ WHERE table - The name of an existing table. + The name (optionally schema-qualified) of an existing table. diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index 307e1ff276..b39daaaeb9 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP AGGREGATE name ( name - The name of an existing aggregate function. + The name (optionally schema-qualified) of an existing aggregate function. @@ -45,7 +45,7 @@ DROP AGGREGATE name ( type - The input data type of an existing aggregate function, + The input data type of the aggregate function, or * if the function accepts any input type. (Refer to the PostgreSQL User's Guide for further information about data types.) @@ -101,7 +101,7 @@ ERROR: RemoveAggregate: aggregate 'name - DROP AGGREGATE will remove all references to an existing + DROP AGGREGATE will delete an existing aggregate definition. To execute this command the current user must be the owner of the aggregate. diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index 63eb0dc057..0a74649f95 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -1,5 +1,5 @@ @@ -39,7 +39,7 @@ DROP DOMAIN domainname [, ...] [ C domainname - The name of an existing domain. + The name (optionally schema-qualified) of an existing domain. diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 2f226e725f..14c6f451c9 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP FUNCTION name ( [ name - The name of an existing function. + The name (optionally schema-qualified) of an existing function. @@ -45,7 +45,7 @@ DROP FUNCTION name ( [ type - The type of the function's parameters. + The type of a parameter of the function. diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 7eb4565ea5..99336704cf 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP INDEX index_name [, ...] index_name - The name of an index to remove. + The name (optionally schema-qualified) of an index to remove. diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index a53434009c..5383d3bea3 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -1,5 +1,5 @@ @@ -38,7 +38,7 @@ DROP OPERATOR id ( id - The identifier of an existing operator. + The identifier (optionally schema-qualified) of an existing operator. @@ -156,7 +156,7 @@ ERROR: RemoveOperator: right unary operator 'oper for information on how to create operators. - It is the user's responsibility to remove any access methods and + It is the user's responsibility to remove any access method operator classes that rely on the deleted operator. diff --git a/doc/src/sgml/ref/drop_rule.sgml b/doc/src/sgml/ref/drop_rule.sgml index 2719d292dc..1596b460c4 100644 --- a/doc/src/sgml/ref/drop_rule.sgml +++ b/doc/src/sgml/ref/drop_rule.sgml @@ -1,5 +1,5 @@ @@ -45,7 +45,8 @@ DROP RULE name ON relation - The name of the relation the rule applies to. + The name (optionally schema-qualified) of the relation the rule + applies to. diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index fa8494e7ef..669d4962a5 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP SEQUENCE name [, ...] name - The name of a sequence. + The name (optionally schema-qualified) of a sequence. diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index 0850e1d942..20de8b484c 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP TABLE name [, ...] name - The name of an existing table to drop. + The name (optionally schema-qualified) of an existing table to drop. @@ -88,14 +88,18 @@ ERROR: table "name" does not exist DROP TABLE removes tables from the database. - Only its owner may destroy a table. A table - may be emptied of rows, but not destroyed, by using DELETE. + Only its owner may destroy a table. A table may be emptied of rows, but not + destroyed, by using DELETE. If a table being destroyed has secondary indexes on it, they will be removed first. The removal of just a secondary index will not affect the contents of the underlying table. + + DROP TABLE will also remove any rules or triggers + that exist for the target table. + @@ -166,7 +170,7 @@ DROP TABLE table { RESTRICT | CASCA - At present, to remove a referenced view you must drop + At present, to remove a referencing view you must drop it explicitly. diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml index c8b69813ce..30c9260549 100644 --- a/doc/src/sgml/ref/drop_trigger.sgml +++ b/doc/src/sgml/ref/drop_trigger.sgml @@ -1,5 +1,5 @@ @@ -46,7 +46,7 @@ DROP TRIGGER name ON table - The name of a table. + The name (optionally schema-qualified) of a table. @@ -97,7 +97,7 @@ ERROR: DropTrigger: there is no trigger name - DROP TRIGGER will remove all references to an existing + DROP TRIGGER will remove an existing trigger definition. To execute this command the current user must be the owner of the table for which the trigger is defined. diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 07d7f2f804..9d88fc85b9 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ DROP TYPE typename [, ...] typename - The name of an existing type. + The name (optionally schema-qualified) of an existing type. diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 1cddf8ec51..5d168628fd 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -1,5 +1,5 @@ @@ -38,7 +38,7 @@ DROP VIEW name [, ...] name - The name of an existing view. + The name (optionally schema-qualified) of an existing view. @@ -103,7 +103,7 @@ ERROR: view name does not exist Notes - Refer to CREATE VIEW + Refer to for information on how to create views. @@ -181,7 +181,7 @@ DROP VIEW view { RESTRICT | CASCADE Notes - At present, to remove a referenced view from a + At present, to remove a referencing view from a PostgreSQL database, you must drop it explicitly. diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 7788d91cf2..bd3aa6f438 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -1,5 +1,5 @@ @@ -37,7 +37,7 @@ INSERT INTO table [ ( table - The name of an existing table. + The name (optionally schema-qualified) of an existing table. diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index 2af4e3f41d..a5191fb20d 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -1,5 +1,5 @@ @@ -45,7 +45,7 @@ where lockmode is one of: name - The name of an existing table to lock. + The name (optionally schema-qualified) of an existing table to lock. diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index bfacbd6f1c..95830ebd42 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -1,5 +1,5 @@ @@ -63,7 +63,8 @@ REINDEX { TABLE | DATABASE | INDEX } namename - The name of the specific table/database/index to be be reindexed. + The name of the specific table/database/index to be reindexed. + Table and index names may be schema-qualified. diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index fe81252a44..9c203f5e57 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,5 +1,5 @@ @@ -119,12 +119,13 @@ where from_item can be: table_name - The name of an existing table or view. If ONLY is specified, only that - table is scanned. If ONLY is not specified, the table and all its - descendant tables (if any) are scanned. * can be appended to the - table name to indicate that descendant tables are to be scanned, - but in the current version, this is the default behavior. - (In releases before 7.1, ONLY was the default behavior.) + The name (optionally schema-qualified) of an existing table or view. + If ONLY is specified, only that table is scanned. If + ONLY is not specified, the table and all its descendant + tables (if any) are scanned. * can be appended to the + table name to indicate that descendant tables are to be scanned, but + in the current version, this is the default behavior. (In releases + before 7.1, ONLY was the default behavior.) diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index 438eb57502..13a8062268 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -1,5 +1,5 @@ @@ -60,13 +60,8 @@ where from_item can be: TEMP - If TEMPORARY or TEMP is specified, - the output table is created only within this session, and is - automatically dropped on session exit. - Existing permanent tables with the same name are not visible - (in this session) while the temporary table exists. - Any indexes created on a temporary table are automatically - temporary as well. + If specified, the table is created as a temporary table. + Refer to for details. @@ -75,10 +70,7 @@ where from_item can be: new_table - The name of the new table to be created. - This table must not already exist. However, a temporary table - can be created that has the same name as an existing permanent - table. + The name (optionally schema-qualified) of the table to be created. diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index 5ef060c600..a3888b7d32 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -1,5 +1,5 @@ @@ -38,7 +38,7 @@ TRUNCATE [ TABLE ] name name - The name of the table to be truncated. + The name (optionally schema-qualified) of the table to be truncated. diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index baf13a6ac8..439e11be4b 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,5 +1,5 @@ @@ -40,7 +40,7 @@ UPDATE [ ONLY ] table SET table - The name of an existing table. + The name (optionally schema-qualified) of an existing table. diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 80ddc4d2c4..310dd4004f 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -1,5 +1,5 @@ @@ -73,8 +73,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ table - The name of a specific table to vacuum. Defaults to all tables - in the current database. + The name (optionally schema-qualified) of a specific table to + vacuum. Defaults to all tables in the current database. diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 41d419dd2e..f1e4a23811 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,5 +1,5 @@ @@ -17,8 +17,8 @@ PostgreSQL Reference Manual The entries in this Reference Manual are - meant to provide in reasonable length an authorative, complete, and - formal summary about the respective subjects. More information + meant to provide in reasonable length an authoritative, complete, and + formal summary about their respective subjects. More information about the use of PostgreSQL, in narrative, tutorial, or example form, may be found in other parts of the PostgreSQL documentation set.