diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index 1e5b9bf890..15116144b6 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -1,5 +1,5 @@ @@ -8,130 +8,82 @@ PostgreSQL documentation ABORT SQL - Language Statements + - - ABORT - - - abort the current transaction - + ABORT + abort the current transaction + - - 1999-07-20 - - + ABORT [ WORK | TRANSACTION ] - - - - - 1998-09-27 - - - Inputs - - - - None. - - - - - - 1998-09-27 - - - Outputs - - - - - - - -ROLLBACK - - - - Message returned if successful. - - - - - -WARNING: ROLLBACK: no transaction in progress - - - - If there is not any transaction currently in progress. - - - - - - + - - - 1998-09-27 - - - Description - + + Description + ABORT rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical - in behavior to the SQL92 command ROLLBACK, + in behavior to the standard SQL command ROLLBACK, and is present only for historical reasons. - - - 1998-09-27 - - - Notes - - - Use COMMIT to successfully - terminate a transaction. - - - - - Usage - + + Diagnostics + + + + ROLLBACK + + + Message returned if successful. + + + + + + WARNING: ROLLBACK: no transaction in progress + + + If there is not any transaction currently in progress. + + + + + + + + Notes + + + Use COMMIT to successfully + terminate a transaction. + + + + + Examples + To abort all changes: - + ABORT WORK; - + - - - - Compatibility - + + Compatibility - - - 1998-09-27 - - - SQL92 - - - This command is a PostgreSQL extension present - for historical reasons. ROLLBACK is the SQL92 - equivalent command. - - + + This command is a PostgreSQL extension + present for historical reasons. ROLLBACK is the + equivalent standard SQL command. + diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml index 6118737176..326f784918 100644 --- a/doc/src/sgml/ref/alter_database.sgml +++ b/doc/src/sgml/ref/alter_database.sgml @@ -1,5 +1,5 @@ @@ -32,18 +32,18 @@ ALTER DATABASE name RESET postgresql.conf - or has been received from the postmaster. + or has been received from the postmaster command line. - Only a superuser or the database owner can change the session defaults for a + Only the database owner or a superuser can change the session defaults for a database. + - - Parameters + + Parameters - name @@ -77,14 +77,11 @@ ALTER DATABASE name RESET - - Diagnostics - ALTER DATABASE @@ -105,7 +102,6 @@ ALTER DATABASE name RESET - diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml index 946fbc86e0..f036916a46 100644 --- a/doc/src/sgml/ref/alter_group.sgml +++ b/doc/src/sgml/ref/alter_group.sgml @@ -1,5 +1,5 @@ @@ -8,92 +8,29 @@ PostgreSQL documentation ALTER GROUP SQL - Language Statements + - - ALTER GROUP - - - add users to a group or remove users from a group - + ALTER GROUP + add users to a group or remove users from a group + - - 2000-01-14 - - -ALTER GROUP name ADD USER username [, ... ] -ALTER GROUP name DROP USER username [, ... ] - - - - - 2000-01-14 - - - Inputs - - - - - - name - - - The name of the group to modify. - - - - - - username - - - Users which are to be added or removed from the group. The user - names must exist. - - - - - - - - - - - 2000-01-14 - - - Outputs - - - - - ALTER GROUP - - - Message returned if the alteration was successful. - - - - - - - + +ALTER GROUP groupname ADD USER username [, ... ] +ALTER GROUP groupname DROP USER username [, ... ] + - - - 2000-01-14 - - - Description - + + Description + ALTER GROUP is used to add or remove users from a group. Only database superusers can use this command. Adding a user to a group does not create the user. Similarly, removing a user from a group does not drop the user itself. + Use to create a new group and name DROP USER - - - Usage - + + Parameter + + + + groupname + + + The name of the group to modify. + + + + + + username + + + Users which are to be added or removed from the group. The users + must exist. + + + + + + + + Diagnostics + + + + ALTER GROUP + + + Message returned if the alteration was successful. + + + + + + + + Examples Add users to a group: @@ -121,24 +96,13 @@ ALTER GROUP workers DROP USER beth; - - - Compatibility - + + Compatibility - - - 2000-01-14 - - - SQL92 - - - There is no ALTER GROUP statement in - SQL92. The concept of roles is - similar. - - + + There is no ALTER GROUP statement in the SQL + standard. The concept of roles is similar. + diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 578dcf59d6..7f5456c277 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1,5 +1,5 @@ @@ -8,19 +8,14 @@ PostgreSQL documentation ALTER TABLE SQL - Language Statements + - - ALTER TABLE - - - change the definition of a table - + ALTER TABLE + change the definition of a table + - - 1999-07-20 - - + ALTER TABLE [ ONLY ] table [ * ] ADD [ COLUMN ] column type [ column_constraint [ ... ] ] ALTER TABLE [ ONLY ] table [ * ] @@ -48,179 +43,19 @@ ALTER TABLE table OWNER TO new_owner ALTER TABLE table CLUSTER ON index_name - - - - - 1998-04-15 - - - Inputs - - - - - - table - - - The name (possibly schema-qualified) of an existing table to - alter. If ONLY is specified, only that table is - altered. If ONLY is not specified, the table and all - its descendant tables (if any) are updated. * 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 default can be altered by changing the - configuration option. - - - - - - column - - - Name of a new or existing column. - - - - - - type - - - Type of the new column. - - - - - - new_column - - - New name for an existing column. - - - - - - new_table - - - New name for the table. - - - - - - table_constraint - - - New table constraint for the table. - - - - - - constraint_name - - - Name of an existing constraint to drop. - - - - - - new_owner - - - The user name of the new owner of the table. - - - - - - index_name - - - The index name on which the table should be marked for clustering. - - - - - - CASCADE - - - Automatically drop objects that depend on the dropped column - or constraint (for example, views referencing the column). - - - - - - RESTRICT - - - Refuse to drop the column or constraint if there are any dependent - objects. This is the default behavior. - - - - - - - - - - - 1998-04-15 - - - Outputs - - - - - - ALTER TABLE - - - Message returned from column or table renaming. - - - - - - ERROR - - - Message returned if table or column is not available. - - - - - - + - - - 1998-04-15 - - - Description - + + Description + ALTER TABLE changes the definition of an existing table. - There are several sub-forms: - + There are several subforms: - - ADD COLUMN + ADD COLUMN This form adds a new column to the table using the same syntax as @@ -230,45 +65,45 @@ ALTER TABLE table - DROP COLUMN + DROP COLUMN - This form drops a column from a table. Note that indexes and + This form drops a column from a table. Indexes and table constraints involving the column will be automatically dropped as well. You will need to say CASCADE if - anything outside the table depends on the column --- for example, - foreign key references, views, etc. + anything outside the table depends on the column, for example, + foreign key references or views. - SET/DROP DEFAULT + SET/DROP DEFAULT - These forms set or remove the default value for a column. Note - that defaults only apply to subsequent INSERT + These forms set or remove the default value for a column. + The default values 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. + the view's ON INSERT rule is applied. - SET/DROP NOT NULL + 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 null values in the column. + These forms change whether a column is marked to allow null + values or to reject null values. You can only use SET + NOT NULL when the column contains no null values. - SET STATISTICS + SET STATISTICS This form @@ -281,39 +116,40 @@ ALTER TABLE table - SET STORAGE + 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 + 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, + uncompressed data, and EXTENDED is for external, compressed data. EXTENDED is the default for all - data types that support it. The use of EXTERNAL will - make substring operations on a TEXT column faster, at the penalty of + data types that support it. The use of EXTERNAL will, for example, + make substring operations on a text column faster, at the penalty of increased storage space. - SET WITHOUT OIDS + SET WITHOUT OIDS - Removes the OID column from the the table. Removing (setting without) - oids from a table also do not occur immediately. The space an OID - uses will be reclaimed when the tuple is updated. Without updating the tuple, both the - space and the value of the OID are maintained indefinitely. This is - semantically similar to the DROP COLUMN process. + This form removes the oid column from the + table. Removing OIDs from a table does not occur immediately. + The space that the OID uses will be reclaimed when the row is + updated. Without updating the row, both the space and the value + of the OID are kept indefinitely. This is semantically similar + to the DROP COLUMN process. - RENAME + RENAME The RENAME forms change the name of a table @@ -324,7 +160,7 @@ ALTER TABLE table - ADD table_constraint + ADD table_constraint This form adds a new constraint to a table using the same syntax as @@ -334,7 +170,7 @@ ALTER TABLE table - DROP CONSTRAINT + DROP CONSTRAINT This form drops constraints on a table. @@ -346,17 +182,17 @@ ALTER TABLE table - OWNER + OWNER - This form changes the owner of the table, index, sequence or view to the + This form changes the owner of the table, index, sequence, or view to the specified user. - CLUSTER + CLUSTER This form marks a table for future @@ -366,27 +202,166 @@ ALTER TABLE table + You must own the table to use ALTER TABLE; except for ALTER TABLE OWNER, which may only be executed by a superuser. + + + + Parameters + + + + + table + + + The name (possibly schema-qualified) of an existing table to + alter. If ONLY is specified, only that table is + altered. If ONLY is not specified, the table and all + its descendant tables (if any) are updated. * can be + appended to the table name to indicate that descendant tables are + to be altered, but in the current version, this is the default + behavior. (In releases before 7.1, ONLY was the + default behavior. The default can be altered by changing the + configuration parameter sql_inheritance.) + + + + + + column + + + Name of a new or existing column. + + + + + + type + + + Data type of the new column. + + + + + + new_column + + + New name for an existing column. + + + + + + new_table + + + New name for the table. + + + + + + table_constraint + + + New table constraint for the table. + + + + + + constraint_name + + + Name of an existing constraint to drop. + + + + + + new_owner + + + The user name of the new owner of the table. + + + + + + index_name + + + The index name on which the table should be marked for clustering. + + + + + + CASCADE + + + Automatically drop objects that depend on the dropped column + or constraint (for example, views referencing the column). + + + + + + RESTRICT + + + Refuse to drop the column or constraint if there are any dependent + objects. This is the default behavior. + + + + + + + + + Diagnostics + + + + ALTER TABLE + + + Message returned if successful. + + + + + + ERROR + + + Message returned if table or column does not exist. + + + + + + + + Notes - - - 1998-04-15 - - - Notes - - The keyword COLUMN is noise and can be omitted. + The key word COLUMN is noise and can be omitted. 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. + 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 afterward. (You may also want to update the already existing rows to the @@ -397,25 +372,25 @@ ALTER TABLE table - The DROP COLUMN command does not physically remove + The DROP COLUMN form does not physically remove the column, but simply makes it invisible to SQL operations. Subsequent - inserts and updates of the table will store a NULL for the column. + insert and update operations in the table will store a null value for the column. Thus, dropping a column is quick but it will not immediately reduce the on-disk size of your table, as the space occupied by the dropped column is not reclaimed. The space will be reclaimed over time as existing rows are updated. To reclaim the space at once, do a dummy UPDATE of all rows and then vacuum, as in: - + UPDATE table SET col = col; VACUUM FULL table; - + - If a table has any descendant tables, it is not permitted to ADD - or RENAME a column in the parent table without doing the same to - the descendants --- that is, ALTER TABLE ONLY + If a table has any descendant tables, it is not permitted to add + or rename a column in the parent table without doing the same to + the descendants. That is, ALTER TABLE ONLY will be rejected. This ensures that the descendants always have columns matching the parent. @@ -431,126 +406,115 @@ VACUUM FULL table; - Changing any part of the schema of a system - catalog is not permitted. + Changing any part of a system catalog table is not permitted. Refer to CREATE TABLE for a further description - of valid arguments. has further information on + of valid parameters. has further information on inheritance. - - - - Usage - + + Examples + To add a column of type varchar to a table: - -ALTER TABLE distributors ADD COLUMN address VARCHAR(30); - + +ALTER TABLE distributors ADD COLUMN address varchar(30); + To drop a column from a table: - + ALTER TABLE distributors DROP COLUMN address RESTRICT; - + To rename an existing column: - + ALTER TABLE distributors RENAME COLUMN address TO city; - + To rename an existing table: - + ALTER TABLE distributors RENAME TO suppliers; - + - To add a NOT NULL constraint to a column: - + To add a not-null constraint to a column: + ALTER TABLE distributors ALTER COLUMN street SET NOT NULL; - - To remove a NOT NULL constraint from a column: - + + To remove a not-null constraint from a column: + ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL; - + To add a check constraint to a table: - + ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5); - + To remove a check constraint from a table and all its children: - + ALTER TABLE distributors DROP CONSTRAINT zipchk; - + To add a foreign key constraint to a table: - -ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses(address) MATCH FULL; - + +ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) MATCH FULL; + To add a (multicolumn) unique constraint to a table: - + ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode); - + To add an automatically named primary key constraint to a table, noting that a table can only ever have one primary key: - + ALTER TABLE distributors ADD PRIMARY KEY (dist_id); - + - - - Compatibility - + + Compatibility - - - 1998-04-15 - - SQL92 - - The ADD COLUMN form is compliant with the exception that - it does not support defaults and NOT NULL constraints, as explained above. - The ALTER COLUMN form is in full compliance. - + + The ADD COLUMN form conforms with the SQL + standard, with the exception that it does not support defaults and + not-null constraints, as explained above. The ALTER + COLUMN form is in full conformance. + - - The clauses to rename tables, columns, indexes, and sequences are - PostgreSQL extensions from SQL92. - + + The clauses to rename tables, columns, indexes, views, and sequences are + PostgreSQL extensions of the SQL standard. + - - ALTER TABLE DROP COLUMN can be used to drop the only column - of a table, leaving a zero-column table. This is an extension from SQL92, - which disallows zero-column tables. - - - + + ALTER TABLE DROP COLUMN can be used to drop the only + column of a table, leaving a zero-column table. This is an + extension of SQL, which disallows zero-column tables. + diff --git a/doc/src/sgml/ref/alter_trigger.sgml b/doc/src/sgml/ref/alter_trigger.sgml index 4dfe945d2b..b335434eaf 100644 --- a/doc/src/sgml/ref/alter_trigger.sgml +++ b/doc/src/sgml/ref/alter_trigger.sgml @@ -1,162 +1,117 @@ - - ALTER TRIGGER - + ALTER TRIGGER SQL - Language Statements + - - ALTER TRIGGER - - - change the definition of a trigger - + ALTER TRIGGER + change the definition of a trigger + - - 2002-04-19 - - + ALTER TRIGGER trigger ON table RENAME TO newname - - - - - 2002-04-19 - - - Inputs - - - - - - trigger - - - The name of an existing trigger to alter. - - - - - - table - - - The name of the table on which this trigger acts. - - - - - - newname - - - New name for the existing trigger. - - - - - - - - - - - 2002-04-19 - - - Outputs - - - - - - ALTER TRIGGER - - - Message returned from trigger renaming. - - - - - - ERROR - - - Message returned if trigger is not available, or new name is a duplicate of another existing trigger on the table. - - - - - - + - - - 2002-04-19 - - - Description - + + Description + - ALTER TRIGGER changes the definition of an existing trigger. - The RENAME clause causes the name of a trigger on the given table - to change without otherwise changing the trigger definition. + ALTER TRIGGER changes properties of an existing + trigger. The RENAME clause changes the name of + the given trigger without otherwise changing the trigger + definition. - You must own the table on which the trigger acts in order to change its properties. + You must own the table on which the trigger acts to be allowed to change its properties. - - - - 2002-04-19 - - - Notes - - - Refer to CREATE TRIGGER for a further description - of valid arguments. - - - - - Usage - + + Parameter + + + + trigger + + + The name of an existing trigger to alter. + + + + + + table + + + The name of the table on which this trigger acts. + + + + + + newname + + + The new name for the trigger. + + + + + + + + Diagnostics + + + + ALTER TRIGGER + + + Message returned if successful. + + + + + + ERROR + + + If the trigger does not exist, or the new name is a duplicate of + another existing trigger on the table. + + + + + + + + Examples + To rename an existing trigger: - + ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs; - + - - - Compatibility - + + Compatibility - - - 2002-04-19 - - SQL92 - - ALTER TRIGGER is a PostgreSQL - extension of SQL92. - - + + ALTER TRIGGER is a PostgreSQL + extension of the SQL standard. + diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml index f67292517b..121b4253ac 100644 --- a/doc/src/sgml/ref/alter_user.sgml +++ b/doc/src/sgml/ref/alter_user.sgml @@ -1,5 +1,5 @@ @@ -20,7 +20,7 @@ ALTER USER username [ [ WITH ] option can be: - [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' + [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | CREATEDB | NOCREATEDB | CREATEUSER | NOCREATEUSER | VALID UNTIL 'abstime' @@ -42,8 +42,8 @@ ALTER USER username RESET The first variant of this command in the synopsis changes certain global user privileges and authentication settings. (See below for - details.) Only a database superuser can change privileges and - password expiration with this command. Ordinary users can only + details.) Only a database superuser can change these privileges and + the password expiration with this command. Ordinary users can only change their own password. @@ -52,15 +52,15 @@ ALTER USER username RESET postgresql.conf - or has been received from the postmaster. + or has been received from the postmaster command line. Ordinary users can change their own session defaults. Superusers can change anyone's session defaults. + - - Parameters + + Parameters - username @@ -99,8 +99,8 @@ ALTER USER username RESET These clauses define a user's ability to create databases. If - CREATEDB is specified, the user being - defined will be allowed to create his own databases. Using + CREATEDB is specified, the user + will be allowed to create his own databases. Using NOCREATEDB will deny a user the ability to create databases. @@ -125,7 +125,7 @@ ALTER USER username RESET The date (and, optionally, the time) at which this user's password is to expire. To set the password - never to expire, use 'infinity'. + never to expire, use 'infinity'. @@ -152,14 +152,11 @@ ALTER USER username RESET - - Diagnostics - ALTER USER @@ -175,12 +172,11 @@ ALTER USER username RESET Error message returned if the specified user is not known to - the database. + the database system. - @@ -226,10 +222,10 @@ ALTER USER manuel VALID UNTIL 'Jan 31 2030'; Change a user's valid until date, specifying that his - authorization should expire at midday on 4th May 1998 using + authorization should expire at midday on 4th May 2005 using the time zone which is one hour ahead of UTC: -ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1'; +ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1'; diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index fdfc0f18bf..4977964f4e 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -1,5 +1,5 @@ @@ -8,97 +8,24 @@ PostgreSQL documentation ANALYZE SQL - Language Statements + - - ANALYZE - - - collect statistics about a database - + ANALYZE + collect statistics about a database + - - 2001-05-04 - - + ANALYZE [ VERBOSE ] [ table [ (column [, ...] ) ] ] - - - - - 2001-05-04 - - - Inputs - - - - - - VERBOSE - - - Enables display of progress messages. - - - - - table - - - The name (possibly schema-qualified) of a specific table to - analyze. Defaults to all tables in the current database. - - - - - column - - - The name of a specific column to analyze. Defaults to all columns. - - - - - - - - - - 2001-05-04 - - - Outputs - - - - - - -ANALYZE - - - - The command is complete. - - - - - - - + - - - 2001-05-04 - - - Description - + + Description + ANALYZE collects statistics about the contents of - PostgreSQL tables, and stores the results in + tables in the database, and stores the results in the system table pg_statistic. Subsequently, the query planner uses the statistics to help determine the most efficient execution plans for queries. @@ -108,16 +35,61 @@ ANALYZE [ VERBOSE ] [ table [ (ANALYZE examines every table in the current database. With a parameter, ANALYZE examines only that table. It is further possible to give a list of column names, - in which case only the statistics for those columns are updated. + in which case only the statistics for those columns are collected. + - - - 2001-05-04 - - - Notes - + + Parameters + + + + VERBOSE + + + Enables display of progress messages. + + + + + + table + + + The name (possibly schema-qualified) of a specific table to + analyze. Defaults to all tables in the current database. + + + + + + column + + + The name of a specific column to analyze. Defaults to all columns. + + + + + + + + Diagnostics + + + + ANALYZE + + + The command is complete. + + + + + + + + Notes It is a good idea to run ANALYZE periodically, or @@ -138,7 +110,7 @@ ANALYZE [ VERBOSE ] [ table [ ( For large tables, ANALYZE takes a random sample of the table contents, rather than examining every row. This allows even very - large tables to be analyzed in a small amount of time. Note however + large tables to be analyzed in a small amount of time. Note, however, that the statistics are only approximate, and will change slightly each time ANALYZE is run, even if the actual table contents did not change. This may result in small changes in the planner's @@ -159,7 +131,7 @@ ANALYZE [ VERBOSE ] [ table [ (default_statistics_target parameter variable, or on a column-by-column basis by setting the per-column - statistics target with ALTER TABLE ALTER COLUMN SET + statistics target with ALTER TABLE ... ALTER COLUMN ... SET STATISTICS (see ). The target value sets the maximum number of entries in the most-common-value @@ -170,7 +142,7 @@ ANALYZE [ VERBOSE ] [ table [ (pg_statistic. In particular, setting the statistics target to zero disables collection of statistics for that column. It may be useful to do that for columns that - are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of + are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of queries, since the planner will have no use for statistics on such columns. @@ -180,26 +152,14 @@ ANALYZE [ VERBOSE ] [ table [ (ANALYZE. - - - - - Compatibility - + + Compatibility - - - 2001-05-04 - - - SQL92 - - - There is no ANALYZE statement in SQL92. - - + + There is no ANALYZE statement in the SQL standard. + diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml index 921792a386..1c5fe0f6ce 100644 --- a/doc/src/sgml/ref/begin.sgml +++ b/doc/src/sgml/ref/begin.sgml @@ -1,5 +1,5 @@ @@ -8,218 +8,137 @@ PostgreSQL documentation BEGIN SQL - Language Statements + - - BEGIN - - - start a transaction block - - - + BEGIN + start a transaction block + + - - 1999-07-20 - - + BEGIN [ WORK | TRANSACTION ] - - - - - 1999-06-11 - - - Inputs - - - - - - WORK - TRANSACTION - - - Optional keywords. They have no effect. - - - - - - - - - - 1999-06-11 - - - Outputs - - - - - - -BEGIN - - - - This signifies that a new transaction has been started. - - - - - -WARNING: BEGIN: already a transaction in progress - - - - This indicates that a transaction was already in progress. - The current transaction is not affected. - - - - - - + - - - 1999-06-11 - - - Description - + + Description - By default, PostgreSQL executes transactions - in unchained mode - (also known as autocommit in other database - systems). - In other words, each user statement is executed in its own transaction - and a commit is implicitly performed at the end of the statement - (if execution was successful, otherwise a rollback is done). - BEGIN initiates a user transaction in chained mode, - i.e., all user statements after BEGIN command will - be executed in a single transaction until an explicit - or - . - Statements are executed more quickly in chained mode, - because transaction start/commit requires significant CPU and disk - activity. Execution of multiple statements inside a transaction - is also useful to ensure consistency when changing several - related tables: other clients will be unable to see the intermediate - states wherein not all the related updates have been done. - - - - The default transaction isolation level in - PostgreSQL - is READ COMMITTED, wherein each query inside the transaction sees changes - committed before that query begins execution. So, you have to use - SET TRANSACTION ISOLATION LEVEL SERIALIZABLE - just after BEGIN if you need more rigorous transaction - isolation. (Alternatively, you can change the default transaction - isolation level; see for details.) - In SERIALIZABLE mode queries will see only changes committed before - the entire - transaction began (actually, before execution of the first DML statement - in the transaction). - - - - Transactions have the standard ACID - (atomic, consistent, isolatable, and durable) properties. + By default, PostgreSQL executes + transactions in autocommit mode, that is, each + statement is executed in its own transaction and a commit is + implicitly performed at the end of the statement (if execution was + successful, otherwise a rollback is done). + BEGIN initiates a transaction block, that is, + all statements after BEGIN command will be + executed in a single transaction until an explicit or . Statements + are executed more quickly in a transaction block, because + transaction start/commit requires significant CPU and disk + activity. Execution of multiple statements inside a transaction is + also useful to ensure consistency when changing several related + tables: other sessions will be unable to see the intermediate states + wherein not all the related updates have been done. + - - - 1999-06-11 - - - Notes - - - has the same functionality - as BEGIN. - - - - Use - or - - to terminate a transaction. - + + Parameters - - Refer to - for further information - about locking tables inside a transaction. - + + + WORK + TRANSACTION + + + Optional key words. They have no effect. + + + + + + + + Diagnostics + + + + BEGIN + + + This signifies that a new transaction has been started. + + + + + + WARNING: BEGIN: already a transaction in progress + + + This indicates that a transaction was already in progress. The + current transaction is not affected. + + + + + + + + Notes + + + has the same functionality + as BEGIN. + - - If you turn autocommit mode off, then BEGIN - is not required: any SQL command automatically starts a transaction. - - + + Use or + + to terminate a transaction. + + + + If you turn the configuration parameter autocommit off, + then BEGIN is not required: any SQL command + automatically starts a transaction. + - - - Usage - + + Examples - To begin a user transaction: + To begin a transaction block: - -BEGIN WORK; - + +BEGIN; + - - - Compatibility - + + Compatibility - - - 1999-06-11 - - - SQL92 - + + BEGIN is a PostgreSQL + language extension. There is no explicit BEGIN + command in the SQL standard; transaction initiation is + always implicit and it terminates either with a + COMMIT or ROLLBACK statement. + - - BEGIN - is a PostgreSQL language extension. - There is no explicit BEGIN - command in SQL92; - transaction initiation is always implicit and it terminates either - with a COMMIT or ROLLBACK statement. + + Other relational database systems may offer an autocommit feature + as a convenience. + - - - Many relational database systems offer an autocommit feature as a - convenience. - - - - - - Incidentally, the BEGIN keyword is used for a different - purpose in embedded SQL. You are advised to be careful about the transaction - semantics when porting database applications. - - - - SQL92 also requires SERIALIZABLE to be the default - transaction isolation level. - - + + Incidentally, the BEGIN key word is used for a + different purpose in embedded SQL. You are advised to be careful + about the transaction semantics when porting database applications. + diff --git a/doc/src/sgml/ref/checkpoint.sgml b/doc/src/sgml/ref/checkpoint.sgml index badcaa4dac..71d075d542 100644 --- a/doc/src/sgml/ref/checkpoint.sgml +++ b/doc/src/sgml/ref/checkpoint.sgml @@ -1,4 +1,4 @@ - + @@ -24,8 +24,8 @@ CHECKPOINT Write-Ahead Logging (WAL) puts a checkpoint in the transaction log every so often. (To adjust the automatic checkpoint interval, see the run-time - configuration options CHECKPOINT_SEGMENTS - and CHECKPOINT_TIMEOUT.) + configuration options checkpoint_segments + and checkpoint_timeout.) The CHECKPOINT command forces an immediate checkpoint when the command is issued, without waiting for a scheduled checkpoint. diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml index e82bb4d90e..9ae487c3f7 100644 --- a/doc/src/sgml/ref/close.sgml +++ b/doc/src/sgml/ref/close.sgml @@ -1,5 +1,5 @@ @@ -8,144 +8,104 @@ PostgreSQL documentation CLOSE SQL - Language Statements + - - CLOSE - - - close a cursor - + CLOSE + close a cursor + - - 1999-07-20 - - + CLOSE cursor - - - - - 1998-09-08 - - - Inputs - - - - - - cursor - - - The name of an open cursor to close. - - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -CLOSE CURSOR - - - - Message returned if the cursor is successfully closed. - - - - - -WARNING: PerformPortalClose: portal "cursor" not found - - - - This warning is given if - cursor is not - declared or has already been closed. - - - - - - + - - - 1998-09-08 - - - Description - + + Description + CLOSE frees the resources associated with an open cursor. After the cursor is closed, no subsequent operations are allowed on it. A cursor should be closed when it is no longer needed. + - An implicit close is executed for every open cursor when a - transaction is terminated by COMMIT - or ROLLBACK. + Every open cursor is implicitly closed when a transaction is + terminated by COMMIT or + ROLLBACK. + - - - 1998-09-08 - - - Notes - - - PostgreSQL does not have - an explicit OPEN cursor statement; - a cursor is considered open when it is declared. - Use the DECLARE statement to declare a cursor. - - + + Parameters + + + + cursor + + + The name of an open cursor to close. + + + + + + + + Diagnostics + + + + CLOSE CURSOR + + + Message returned if the cursor is successfully closed. + + + + + + WARNING: PerformPortalClose: portal "cursor" not found + + + This warning is given if cursor is not declared or has + already been closed. + + + + - - - Usage - + + Notes + + + PostgreSQL does not have an explicit + OPEN cursor statement; a cursor is considered + open when it is declared. Use the DECLARE + statement to declare a cursor. + + + + + Examples + Close the cursor liahona: - - + CLOSE liahona; - + + - - - Compatibility - + + Compatibility - - - 1998-09-08 - - - SQL92 - - - CLOSE is fully compatible with SQL92. - - + + CLOSE is fully conforming with the SQL standard. + diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 52a895b12b..90c56551a3 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -1,5 +1,5 @@ @@ -8,89 +8,27 @@ PostgreSQL documentation CLUSTER SQL - Language Statements + - - CLUSTER - - - cluster a table according to an index - + CLUSTER + cluster a table according to an index + - - 1999-07-20 - - + CLUSTER indexname ON tablename CLUSTER tablename CLUSTER - - - - - 1998-09-08 - - - Inputs - - - - - - indexname - - - The name of an index. - - - - - table - - - The name (possibly schema-qualified) of a table. - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -CLUSTER - - - - The clustering was done successfully. - - - - - - + - - - 1998-09-08 - - - Description - + + Description + CLUSTER instructs PostgreSQL to cluster the table specified - by table + by tablename based on the index specified by indexname. The index must already have been defined on @@ -102,19 +40,19 @@ CLUSTER based on the index information. Clustering is a one-time operation: when the table is subsequently updated, the changes are not clustered. That is, no attempt is made to store new or - updated tuples according to their index order. If one wishes, one can - periodically re-cluster by issuing the command again. + updated rows according to their index order. If one wishes, one can + periodically recluster by issuing the command again. When a table is clustered, PostgreSQL remembers on which index it was clustered. The form CLUSTER tablename, - re-clusters the table on the same index that it was clustered before. + reclusters the table on the same index that it was clustered before. - CLUSTER without any parameter re-clusters all the tables + CLUSTER without any parameter reclusters all the tables in the current database that the calling user owns, or all tables if called by a superuser. (Never-clustered tables are not included.) This @@ -129,33 +67,62 @@ CLUSTER table until the CLUSTER is finished. See for more information on database locking. + - - - 1998-09-08 - - - Notes - + + Parameter + + + + indexname + + + The name of an index. + + + + + + tablename + + + The name (possibly schema-qualified) of a table. + + + + + + + + Diagnostics + + + + CLUSTER + + + The clustering was done successfully. + + + + + + + + Notes In cases where you are accessing single rows randomly - within a table, the actual order of the data in the heap + within a table, the actual order of the data in the table is unimportant. However, if you tend to access some data more than others, and there is an index that groups them together, you will benefit from using CLUSTER. - - - - Another place where CLUSTER is helpful is in - cases where you use an - index to pull out several rows from a table. If you are - requesting a range of indexed values from a table, or a + If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, CLUSTER will help because once the index identifies the heap page for the first row that matches, all other rows that match are probably already on the same heap page, - saving disk accesses and speeding up the query. + and so you save disk accesses and speed up the query. @@ -166,23 +133,17 @@ CLUSTER sizes. - - CLUSTER preserves GRANT, - inheritance, index, foreign key, and other ancillary information - about the table. - - Because CLUSTER remembers the clustering information, one can cluster the tables one wants clustered manually the first time, and setup a timed event similar to VACUUM so that the tables - are periodically re-clustered. + are periodically reclustered. - Because the optimizer records statistics about the ordering of tables, it + Because the planner records statistics about the ordering of tables, it is advisable to run ANALYZE on the newly clustered - table. Otherwise, the optimizer may make poor choices of query plans. + table. Otherwise, the planner may make poor choices of query plans. @@ -196,68 +157,57 @@ CLUSTER but the majority of a big table will not fit in the cache.) The other way to cluster a table is to use - -SELECT columnlist INTO TABLE newtable - FROM table ORDER BY columnlist - + +CREATE TABLE newtable AS + SELECT columnlist FROM table ORDER BY columnlist; + which uses the PostgreSQL sorting code in - the ORDER BY clause to create the desired order; this is usually much + the ORDER BY clause to create the desired order; this is usually much faster than an index scan for unordered data. You then drop the old table, use - ALTER TABLE...RENAME + ALTER TABLE ... RENAME to rename newtable to the old name, and recreate the table's indexes. However, this approach does not preserve OIDs, constraints, foreign key relationships, granted privileges, and other ancillary properties of the table --- all such items must be manually recreated. - - - - - Usage - + + Examples + - Cluster the employees relation on the basis of - its ID attribute: - - + Cluster the table employees on the basis of + its index emp_ind: + CLUSTER emp_ind ON emp; - + + + Cluster the employees relation using the same index that was used before: - - + CLUSTER emp; - + + + Cluster all the tables on the database that have previously been clustered: - - + CLUSTER; - + + - - - Compatibility - + + Compatibility - - - 1998-09-08 - - - SQL92 - - - There is no CLUSTER statement in SQL92. - - + + There is no CLUSTER statement in the SQL standard. + diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index ea173e1741..2eaf4ada45 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -1,5 +1,5 @@ @@ -8,21 +8,16 @@ PostgreSQL documentation COMMENT SQL - Language Statements + - - COMMENT - - - define or change the comment of an object - + COMMENT + define or change the comment of an object + - - 1999-07-20 - - + COMMENT ON -[ +{ TABLE object_name | COLUMN table_name.column_name | AGGREGATE agg_name (agg_type) | @@ -38,83 +33,21 @@ COMMENT ON TRIGGER trigger_name ON table_name | TYPE object_name | VIEW object_name -] IS 'text' - - - - - 1999-10-25 - - - Inputs - - - - - - object_name, - table_name.column_name, agg_name, constraint_name, func_name, op, rule_name, trigger_name - - - The name of the object to be be commented. Names of tables, - aggregates, domains, functions, indexes, operators, sequences, types, - and views - may be schema-qualified. - - - - - text - - - The comment to add. - - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -COMMENT - - - - Message returned if the table is successfully commented. - - - - - - +} IS 'text' + - - - 1998-10-25 - - - Description - + + Description + COMMENT stores a comment about a database object. Comments can be - easily retrieved with psql's - \dd, \d+, or \l+ - commands. Other user interfaces to retrieve comments can be built atop - the same built-in functions that psql uses, namely - obj_description() and col_description(). + easily retrieved with the psql commands + \dd, \d+, and \l+. + Other user interfaces to retrieve comments can be built atop + the same built-in functions that psql uses, namely + obj_description and col_description. @@ -124,75 +57,114 @@ COMMENT string. Comments are automatically dropped when the object is dropped. - - - - There is presently no security mechanism - for comments: any user connected to a database can see all the comments - for objects in that database (although only superusers can change - comments for objects that they don't own). Therefore, don't put - security-critical information in comments. - - - - - Usage - + + Parameters + + + + object_name + table_name.column_name + aggname + constraint_name + func_name + op + rule_name + trigger_name + + + The name of the object to be be commented. Names of tables, + aggregates, domains, functions, indexes, operators, sequences, + types, and views may be schema-qualified. + + + + + + text + + + The new comment. + + + + + + + + Diagnostics + + + + COMMENT + + + Message returned if the comment was successfully changed. + + + + + + + + Notes + + + There is presently no security mechanism for comments: any user + connected to a database can see all the comments for objects in + that database (although only superusers can change comments for + objects that they don't own). Therefore, don't put + security-critical information in comments. + + + + + Examples + Attach a comment to the table mytable: - + COMMENT ON TABLE mytable IS 'This is my table.'; - + Remove it again: - + COMMENT ON TABLE mytable IS NULL; - + Some more examples: - + COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance'; -COMMENT ON COLUMN my_table.my_field IS 'Employee ID number'; +COMMENT ON COLUMN my_table.my_column IS 'Employee ID number'; COMMENT ON DATABASE my_database IS 'Development Database'; COMMENT ON DOMAIN my_domain IS 'Email Address Domain'; COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral'; -COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee id'; +COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID'; COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts'; COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text'; -COMMENT ON RULE my_rule ON my_table IS 'Logs UPDATES of employee records'; +COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records'; COMMENT ON SCHEMA my_schema IS 'Departmental data'; COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys'; COMMENT ON TABLE my_schema.my_table IS 'Employee Information'; -COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for R.I.'; -COMMENT ON TYPE complex IS 'Complex Number datatype'; +COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI'; +COMMENT ON TYPE complex IS 'Complex number data type'; COMMENT ON VIEW my_view IS 'View of departmental costs'; - + - - - Compatibility - + + Compatibility - - - 1998-09-08 - - - SQL92 - - - There is no COMMENT in SQL92. - - + + There is no COMMENT command in the SQL standard. + diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index 77c56238eb..a84c61a901 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -1,5 +1,5 @@ @@ -8,141 +8,96 @@ PostgreSQL documentation COMMIT SQL - Language Statements + - - COMMIT - - - commit the current transaction - + COMMIT + commit the current transaction - - 1999-07-20 - - + COMMIT [ WORK | TRANSACTION ] - - - - - 1998-09-08 - - - Inputs - - - - - - WORK - TRANSACTION - - - Optional keywords. They have no effect. - - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -COMMIT - - - - Message returned if the transaction is successfully committed. - - - - - -WARNING: COMMIT: no transaction in progress - - - - If there is no transaction in progress. - - - - - - + - - - 1998-09-08 - - - Description - + + Description + COMMIT commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs. + - - - 1998-09-08 - - - Notes - - - The keywords WORK and TRANSACTION are noise and can be omitted. - + + Parameters - - Use - to abort a transaction. - - + + + WORK + TRANSACTION + + + Optional key words. They have no effect. + + + + + + + + Diagnostics + + + + COMMIT + + + Message returned if the transaction was successfully committed. + + + + + + WARNING: COMMIT: no transaction in progress + + + Message if there is no transaction in progress. + + + + - - - Usage - + + Notes + - To make all changes permanent: - -COMMIT WORK; - + Use to + abort a transaction. + + + + + Examples + + + To commit the current transaction and make all changes permanent: + +COMMIT; + - - - Compatibility - + + Compatibility - - - 1998-09-08 - - - SQL92 - - - SQL92 only specifies the two forms COMMIT - and COMMIT WORK. Otherwise full compatibility. - - + + The SQL standard only specifies the two forms + COMMIT and COMMIT + WORK. Otherwise, this command is fully conforming. + diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 389b455fde..56e7223bd9 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -1,5 +1,5 @@ @@ -8,186 +8,35 @@ PostgreSQL documentation COPY SQL - Language Statements + - - COPY - - - copy data between files and tables - + COPY + copy data between files and tables + - - 1999-12-11 - - + COPY table [ ( column [, ...] ) ] - FROM { 'filename' | stdin } + FROM { 'filename' | STDIN } [ [ WITH ] [ BINARY ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] ] + COPY table [ ( column [, ...] ) ] - TO { 'filename' | stdout } + TO { 'filename' | STDOUT } [ [ WITH ] [ BINARY ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] ] - - - - - 1998-09-08 - - - Inputs - - - - - - table - - - The name (possibly schema-qualified) of an existing table. - - - - - - column - - - An optional list of columns to be copied. If no column list is - specified, all columns will be used. - - - - - - filename - - - The absolute Unix path name of the input or output file. - - - - - - stdin - - - Specifies that input comes from the client application. - - - - - - stdout - - - Specifies that output goes to the client application. - - - - - - BINARY - - - Changes the behavior of field formatting, forcing all data to be - stored or read in binary format rather than as text. You can not - specify or - in binary mode. - - - - - - OIDS - - - Specifies copying the internal object id (OID) for each row. - - - - - - delimiter - - - The single character that separates fields within each row (line) of the file. - - - - - - null string - - - The string that represents a NULL value. The default is - \N (backslash-N). You might - prefer an empty string, for example. - - - - On a COPY FROM, any data item that matches - this string will be stored as a NULL value, so you should - make sure that you use the same string as you used with - COPY TO. - - - - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -COPY - - - - The copy completed successfully. - - - - - -ERROR: reason - - - - The copy failed for the reason stated in the error message. - - - - - - + - - - 2001-01-02 - - - Description - + + Description + COPY moves data between PostgreSQL tables and standard file-system @@ -207,61 +56,186 @@ ERROR: reason COPY with a file name instructs the - PostgreSQL backend to directly read from - or write to a file. The file must be accessible to the backend and - the name must be specified from the viewpoint of the backend. When - stdin or stdout is + PostgreSQL server to directly read from + or write to a file. The file must be accessible to the server and + the name must be specified from the viewpoint of the server. When + STDIN or STDOUT is specified, data is transmitted via the connection between the - client frontend and the backend. - - - - Do not confuse COPY with the - psql instruction - \copy. \copy invokes - COPY FROM stdin or COPY TO - stdout, and then fetches/stores the data in a file - accessible to the psql client. Thus, - file accessibility and access rights depend on the client rather - than the backend when \copy is used. - - - + client and the server. + + + + + Parameters + + + + table + + + The name (possibly schema-qualified) of an existing table. + + + + + + column + + + An optional list of columns to be copied. If no column list is + specified, all columns will be used. + + + + + + filename + + + The absolute path name of the input or output file. + + + + + + STDIN + + + Specifies that input comes from the client application. + + + + + + STDOUT + + + Specifies that output goes to the client application. + + + + + + BINARY + + + Forces all data to be stored or read in binary format rather + than as text. You cannot specify the + or options in binary mode. + + + + + + OIDS + + + Specifies copying the OID for each row. (An error is raised if + OIDS is specified for a table that does not + have OIDs.) + + + + + + delimiter + + + The single character that separates columns within each row + (line) of the file. The default is a tab character. + + + + + + null string + + + The string that represents a null value. The default is + \N (backslash-N). You might prefer an empty + string, for example. + + + + + On a COPY FROM, any data item that matches + this string will be stored as a null value, so you should make + sure that you use the same string as you used with + COPY TO. + + + + + + + + + Diagnostics + + + + COPY + + + The copy operation completed successfully. + + + + + + + + Notes - - - 2001-01-02 - - - Notes - COPY can only be used with plain tables, not with views. - The BINARY keyword will force all data to be + The BINARY key word will force all data to be stored/read as binary format rather than as text. It is - somewhat faster than the normal copy command, but a binary copy + somewhat faster than the normal text mode, but a binary format file is not portable across machine architectures. - - - - By default, a text copy uses a tab ("\t") character as a delimiter - between fields. The field delimiter may be changed to any other - single character with the keyword . Characters - in data fields that happen to match the delimiter character will be - backslash quoted. - + - You must have select privilege on any table + You must have select privilege on any table whose values are read by COPY TO, and - insert privilege on a table into which values - are being inserted by COPY FROM. The backend also - needs appropriate Unix permissions for any file read or written by - COPY. + insert privilege on a table into which values + are being inserted by COPY FROM. + + + + Files named in a COPY command are read or written + directly by the server, not by the client application. Therefore, + they must reside on or be accessible to the database server machine, + not the client. They must be accessible to and readable or writable + by the PostgreSQL user (the user ID the + server runs as), not the client. COPY naming a + file is only allowed to database superusers, since it allows reading + or writing any file that the server has privileges to access. + + + + Do not confuse COPY with the + psql instruction + \copy. \copy invokes + COPY FROM STDIN or COPY TO + STDOUT, and then fetches/stores the data in a file + accessible to the psql client. Thus, + file accessibility and access rights depend on the client rather + than the server when \copy is used. + + + + It is recommended that the file name used in COPY + always be specified as an absolute path. This is enforced by the + server in the case of COPY TO, but for + COPY FROM you do have the option of reading from + a file specified by a relative path. The path will be interpreted + relative to the working directory of the server process (somewhere below + the data directory), not the client's working directory. @@ -272,87 +246,52 @@ ERROR: reason COPY stops operation at the first error. This should not lead to problems in the event of a COPY - TO, but the target relation will already have received + TO, but the target table will already have received earlier rows in a COPY FROM. These rows will not be visible or accessible, but they still occupy disk space. This may amount to a considerable amount of wasted disk space if the failure happened well into a large copy operation. You may wish to invoke VACUUM to recover the wasted space. - - - Files named in a COPY command are read or written - directly by the backend, not by the client application. Therefore, - they must reside on or be accessible to the database server machine, - not the client. They must be accessible to and readable or writable - by the PostgreSQL user (the user ID the - server runs as), not the client. COPY naming a - file is only allowed to database superusers, since it allows reading - or writing any file that the backend has privileges to access. - - - - The - psql instruction \copy - reads or writes files on the client machine with the client's - permissions, so it is not restricted to superusers. - - - - - - It is recommended that the file name used in COPY - always be specified as an absolute path. This is enforced by the - backend in the case of COPY TO, but for - COPY FROM you do have the option of reading from - a file specified by a relative path. The path will be interpreted - relative to the backend's working directory (somewhere below - $PGDATA), not the client's working directory. - - - - - 2001-01-02 - + File Formats + - - 2002-02-12 - Text Format + - When COPY is used without the BINARY option, - the file read or written is a text file with one line per table row. - Columns (attributes) in a row are separated by the delimiter character. - The attribute values themselves are strings generated by the + When COPY is used without the BINARY option, + the data read or written is a text file with one line per table row. + Columns in a row are separated by the delimiter character. + The column values themselves are strings generated by the output function, or acceptable to the input function, of each attribute's data type. The specified null-value string is used in - place of attributes that are NULL. + place of columns that are null. COPY FROM will raise an error if any line of the input file contains more or fewer columns than are expected. + If OIDS is specified, the OID is read or written as the first column, + preceding the user data columns. - - If OIDS is specified, the OID is read or written as the first column, - preceding the user data columns. (An error is raised if OIDS is - specified for a table that does not have OIDs.) - + End of data can be represented by a single line containing just backslash-period (\.). An end-of-data marker is - not necessary when reading from a Unix file, since the end of file + not necessary when reading from a file, since the end of file serves perfectly well; but an end marker must be provided when copying data to or from a client application. + Backslash characters (\) may be used in the COPY data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the following characters must be preceded by a backslash if - they appear as part of an attribute value: backslash itself, + they appear as part of a column value: backslash itself, newline, and the current delimiter character. + The following special backslash sequences are recognized by COPY FROM: @@ -404,47 +343,44 @@ ERROR: reason backslash sequence, but it does use the other sequences listed above for those control characters. + Never put a backslash before a data character N or period (.). Such pairs will be mistaken for the default null string or the end-of-data marker, respectively. Any other backslashed character that is not mentioned in the above table will be taken to represent itself. + It is strongly recommended that applications generating COPY data convert data newlines and carriage returns to the \n and - \r sequences respectively. At present - (PostgreSQL 7.2 and older versions) it is + \r sequences respectively. At present it is possible to represent a data carriage return without any special quoting, and to represent a data newline by a backslash and newline. However, these representations will not be accepted by default in future releases. + Note that the end of each row is marked by a Unix-style newline - ("\n"). Presently, COPY FROM will not behave as + (\n). Presently, COPY FROM will not behave as desired if given a file containing DOS- or Mac-style newlines. This is expected to change in future releases. - - 2001-01-02 - Binary Format + The file format used for COPY BINARY changed in - PostgreSQL v7.1. The new format consists - of a file header, zero or more tuples, and a file trailer. + PostgreSQL 7.1. The new format consists + of a file header, zero or more tuples containing the row data, and + a file trailer. - - 2001-01-02 - - - File Header - + File Header + The file header consists of 24 bytes of fixed fields, followed by a variable-length header extension area. The fixed fields are: @@ -454,11 +390,11 @@ ERROR: reason Signature -12-byte sequence PGBCOPY\n\377\r\n\0 --- note that the null +12-byte sequence PGBCOPY\n\377\r\n\0 --- note that the zero byte is a required part of the signature. (The signature is designed to allow easy identification of files that have been munged by a non-8-bit-clean transfer. This signature will be changed by newline-translation -filters, dropped nulls, dropped high bits, or parity changes.) +filters, dropped zero bytes, dropped high bits, or parity changes.) @@ -467,7 +403,7 @@ filters, dropped nulls, dropped high bits, or parity changes.) Integer layout field -int32 constant 0x01020304 in source's byte order. Potentially, a reader +32-bit integer constant 0x01020304 in source's byte order. Potentially, a reader could engage in byte-flipping of subsequent fields if the wrong byte order is detected here. @@ -478,7 +414,7 @@ order is detected here. Flags field -int32 bit mask to denote important aspects of the file format. Bits are +32-bit integer bit mask to denote important aspects of the file format. Bits are numbered from 0 (LSB) to 31 (MSB) --- note that this field is stored with source's endianness, as are all subsequent integer fields. Bits 16-31 are reserved to denote critical file format issues; a reader @@ -491,7 +427,7 @@ only one flag bit is defined, and the rest must be zero: Bit 16 - if 1, OIDs are included in the dump; if 0, not + if 1, OIDs are included in the data; if 0, not @@ -504,8 +440,8 @@ only one flag bit is defined, and the rest must be zero: Header extension area length -int32 length in bytes of remainder of header, not including self. In -the initial version this will be zero, and the first tuple follows +32-bit integer, length in bytes of remainder of header, not including self. +Currently, this is zero, and the first tuple follows immediately. Future changes to the format might allow additional data to be present in the header. A reader should silently skip over any header extension data it does not know what to do with. @@ -531,17 +467,12 @@ is left for a later release. - - 2001-01-02 - - - Tuples - + Tuples -Each tuple begins with an int16 count of the number of fields in the +Each tuple begins with a 16-bit integer count of the number of fields in the tuple. (Presently, all tuples in a table will have the same count, but that might not always be true.) Then, repeated for each field in the -tuple, there is an int16 typlen word possibly followed by field data. +tuple, there is a 16-bit integer typlen word possibly followed by field data. The typlen field is interpreted thus: @@ -549,7 +480,7 @@ The typlen field is interpreted thus: Zero - Field is NULL. No data follows. + Field is null. No data follows. @@ -558,7 +489,7 @@ The typlen field is interpreted thus: > 0 - Field is a fixed-length data type. Exactly N + Field is a fixed-length data type. Exactly that many bytes of data follow the typlen word. @@ -570,7 +501,7 @@ The typlen field is interpreted thus: Field is a varlena data type. The next four bytes are the varlena header, which contains - the total value length including itself. + the total value length including the header itself. @@ -587,7 +518,7 @@ The typlen field is interpreted thus: -For non-NULL fields, the reader can check that the typlen matches the +For nonnull fields, the reader can check that the typlen matches the expected typlen for the destination column. This provides a simple but very useful check that the data is as expected. @@ -602,23 +533,19 @@ you from moving a binary file across machines). -If OIDs are included in the dump, the OID field immediately follows the +If OIDs are included in the file, the OID field immediately follows the field-count word. It is a normal field except that it's not included in the field-count. In particular it has a typlen --- this will allow -handling of 4-byte vs 8-byte OIDs without too much pain, and will allow -OIDs to be shown as NULL if that ever proves desirable. +handling of 4-byte vs. 8-byte OIDs without too much pain, and will allow +OIDs to be shown as null if that ever proves desirable. - - 2001-01-02 - - - File Trailer - + File Trailer + - The file trailer consists of an int16 word containing -1. This is + The file trailer consists of an 16-bit integer word containing -1. This is easily distinguished from a tuple's field-count word. @@ -631,48 +558,47 @@ OIDs to be shown as NULL if that ever proves desirable. - - - Usage - + + Examples + - The following example copies a table to standard output, - using a vertical bar (|) as the field delimiter: + The following example copies a table to the client + using the vertical bar (|) as the field delimiter: + +COPY country TO STDOUT WITH DELIMITER '|'; + - -COPY country TO stdout WITH DELIMITER '|'; - + - To copy data from a Unix file into the country table: - - + To copy data from a file into the country table: + COPY country FROM '/usr1/proj/bray/sql/country_data'; - + + + Here is a sample of data suitable for copying into a table from - stdin (so it has the termination sequence on the + STDIN (so it must have the termination sequence on the last line): - - + AF AFGHANISTAN AL ALBANIA DZ ALGERIA ZM ZAMBIA ZW ZIMBABWE \. - - - Note that the white space on each line is actually a TAB. + + Note that the white space on each line is actually a tab character. + The following is the same data, output in binary format on a Linux/i586 machine. The data is shown after filtering through the - Unix utility od -c. The table has three fields; - the first is char(2), the second is text, - and the third is integer. All the rows have a null value - in the third field. - - + Unix utility od -c. The table has three columns; + the first has type char(2), the second has type text, + and the third has type integer. All the rows have a null value + in the third column. + 0000000 P G B C O P Y \n 377 \r \n \0 004 003 002 001 0000020 \0 \0 \0 \0 \0 \0 \0 \0 003 \0 377 377 006 \0 \0 \0 0000040 A F 377 377 017 \0 \0 \0 A F G H A N I S @@ -683,38 +609,33 @@ ZW ZIMBABWE 0000160 M 377 377 \n \0 \0 \0 Z A M B I A \0 \0 003 0000200 \0 377 377 006 \0 \0 \0 Z W 377 377 \f \0 \0 \0 Z 0000220 I M B A B W E \0 \0 377 377 - + + - - - Compatibility - + + Compatibility - - - 1998-09-08 - - - SQL92 - - - There is no COPY statement in SQL92. - - - The following syntax was used by pre-7.3 applications and is still supported: - - COPY [ BINARY ] table [ WITH OIDS ] - FROM { 'filename' | stdin } - [ [USING] DELIMITERS 'delimiter' ] - [ WITH NULL AS 'null string' ] - COPY [ BINARY ] table [ WITH OIDS ] - TO { 'filename' | stdout } - [ [USING] DELIMITERS 'delimiter' ] - [ WITH NULL AS 'null string' ] - - - + + There is no COPY statement in the SQL standard. + + + + The following syntax was used before PostgreSQL version 7.3 and is + still supported: + + +COPY [ BINARY ] table [ WITH OIDS ] + FROM { 'filename' | STDIN } + [ [USING] DELIMITERS 'delimiter' ] + [ WITH NULL AS 'null string' ] + +COPY [ BINARY ] table [ WITH OIDS ] + TO { 'filename' | STDOUT } + [ [USING] DELIMITERS 'delimiter' ] + [ WITH NULL AS 'null string' ] + +