From: Peter Eisentraut Date: Sat, 26 Apr 2003 23:56:51 +0000 (+0000) Subject: Editing of more reference pages. X-Git-Tag: REL9_0_0~15405 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=20aae3047fb6a04c7cd042873aefa5cba404cfa9;p=pg-rex%2Fsyncrep.git Editing of more reference pages. --- diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index 15116144b6..5d1d4472d0 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -1,5 +1,5 @@ @@ -33,6 +33,22 @@ ABORT [ WORK | TRANSACTION ] + Parameters + + + + WORK + TRANSACTION + + + Optional key words. They have no effect. + + + + + + + Diagnostics @@ -71,7 +87,7 @@ ABORT [ WORK | TRANSACTION ] To abort all changes: -ABORT WORK; +ABORT; diff --git a/doc/src/sgml/ref/deallocate.sgml b/doc/src/sgml/ref/deallocate.sgml index 29925adc4a..008a6262e1 100644 --- a/doc/src/sgml/ref/deallocate.sgml +++ b/doc/src/sgml/ref/deallocate.sgml @@ -1,5 +1,5 @@ @@ -8,114 +8,79 @@ PostgreSQL documentation DEALLOCATE SQL - Language Statements + - - DEALLOCATE - - - remove a prepared query - + DEALLOCATE + deallocate a prepared statement - - - 2002-08-12 - - - DEALLOCATE [ PREPARE ] plan_name - - - - - 2002-08-12 - - - Inputs - - - - - - PREPARE - - - This keyword is ignored. - - - - - plan_name - - - The name of the prepared query to remove. - - - - - - - - - 2002-08-12 - - - Outputs - - - - - - DEALLOCATE - - - - The prepared query was removed successfully. - - - - - - + + +DEALLOCATE [ PREPARE ] plan_name + - - - 2002-08-12 - - - Description - + + Description - DEALLOCATE is used to remove a previously - prepared query. If you do not explicitly - DEALLOCATE a prepared query, it is removed when - the session ends. + DEALLOCATE is used to deallocate a previously + prepared SQL statement. If you do not explicitly deallocate a + prepared statement, it is deallocated when the session ends. - For more information on prepared queries, see . - - - Compatibility - + + Parameters + + + + PREPARE + + + This key word is ignored. + + + + + + plan_name + + + The name of the prepared statement to deallocate. + + + + + + + + Diagnostics + + + + DEALLOCATE + + + Message returned if the prepared statement was deallocated successfully. + + + + + - - - 2002-08-12 - - - SQL92 - - - SQL92 includes a DEALLOCATE statement, but it is - only for use in embedded SQL clients. - - + + Compatibility + + + The SQL standard includes a DEALLOCATE + statement, but it is only for use in embedded SQL. + diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index e821d5e3cb..b04b86c888 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -1,5 +1,5 @@ @@ -8,105 +8,28 @@ PostgreSQL documentation DELETE SQL - Language Statements - - - DELETE - - - delete rows of a table - + + DELETE + delete rows of a table + - - 1999-07-20 - - + DELETE FROM [ ONLY ] table [ WHERE condition ] - - - - - 1998-04-15 - - - Inputs - - - - - table - - - The name (optionally schema-qualified) of an existing table. - - - - - condition - - - This is an SQL selection query which returns the rows which - are to be deleted. - - - Refer to the SELECT statement for further description - of the WHERE clause. - - - - - - - - - - 1998-04-15 - - - Outputs - - - - - -DELETE count - - - - Message returned if items are successfully deleted. The - count is the number - of rows deleted. - - - If count is 0, - no rows were deleted. - - - - - - + - - - 1998-04-15 - - - Description - + + Description - DELETE removes rows which satisfy the WHERE - clause from the specified table. + DELETE deletes rows that satisfy the + WHERE clause from the specified table. If the + WHERE clause is absent, the effect is to delete + all rows in the table. The result is a valid, but empty table. - - If the condition (WHERE clause) is absent, - the effect is to delete all rows in the table. - The result is a valid, but empty table. - is a @@ -114,39 +37,74 @@ DELETE count faster mechanism to remove all rows from a table. - - By default DELETE will delete tuples in the table specified - and all its sub-tables. If you wish to only update the - specific table mentioned, you should use the ONLY clause. + By default, DELETE will delete rows in the + specified table and all its subtables. If you wish to only delete + from the specific table mentioned, you must use the + ONLY clause. - You must have write access to the table in order to modify - it, as well as read access to any table whose values are - read in the condition. + You must have the DELETE privilege on the table + to delete from it, as well as the SELECT + privilege to any table whose values are read in the condition. - - - Usage - + + Parameters + + + + table + + + The name (optionally schema-qualified) of an existing table. + + + + + + condition + + + A value expression that returns a value of type + boolean that determines the rows which are to be + deleted. + + + + + + + + Diagnostics + + + + DELETE count + + + Message returned if rows are successfully deleted. The + count is the number + of rows deleted. If count is 0, no rows were + deleted. + + + + + + + + Examples + - Remove all films but musicals: + Delete all films but musicals: DELETE FROM films WHERE kind <> 'Musical'; -SELECT * FROM films; - - - code | title | did | date_prod | kind | len --------+---------------------------+-----+------------+---------+------- - UA501 | West Side Story | 105 | 1961-01-03 | Musical | 02:32 - TC901 | The King and I | 109 | 1956-08-11 | Musical | 02:13 - WD101 | Bed Knobs and Broomsticks | 111 | | Musical | 01:57 -(3 rows) - @@ -154,42 +112,16 @@ SELECT * FROM films; Clear the table films: DELETE FROM films; -SELECT * FROM films; - - - code | title | did | date_prod | kind | len -------+-------+-----+-----------+------+----- -(0 rows) - - - - Compatibility - - - - - 1998-04-15 - - - SQL92 - - - SQL92 allows a positioned DELETE statement: - - -DELETE FROM table WHERE - CURRENT OF cursor - - - where cursor - identifies an open cursor. - Interactive cursors in PostgreSQL are read-only. - - + + Compatibility + + + This command conforms to the SQL standard. + diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml index 3852f74286..b672319479 100644 --- a/doc/src/sgml/ref/end.sgml +++ b/doc/src/sgml/ref/end.sgml @@ -1,5 +1,5 @@ @@ -8,145 +8,99 @@ PostgreSQL documentation END SQL - Language Statements + - - END - - - commit the current transaction - - - + END + commit the current transaction + + - - 1999-07-20 - - + END [ 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 - END is a PostgreSQL - extension, and is a synonym for the SQL92-compatible - . + END commits the current transaction. All changes + made by the transaction become visible to others and are guaranteed + to be durable if a crash occurs. It is a PostgreSQL extension that + is equivalent to . + - - - 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. + + + + + + + + Notes - - - Usage - - To make all changes permanent: + Use to + abort a transaction. + + + + + Examples - -END WORK; - + + To commit the current transaction and make all changes permanent: + +END; + - - - - Compatibility - - - - - 1998-09-08 - - - SQL92 - - - END is a PostgreSQL - extension which provides functionality equivalent to - . - - + + Compatibility + + + END is a PostgreSQL + extension that provides functionality equivalent to , which is + specified in the SQL standard. + diff --git a/doc/src/sgml/ref/execute.sgml b/doc/src/sgml/ref/execute.sgml index d62209797b..f4b0a062fc 100644 --- a/doc/src/sgml/ref/execute.sgml +++ b/doc/src/sgml/ref/execute.sgml @@ -1,5 +1,5 @@ @@ -8,128 +8,100 @@ PostgreSQL documentation EXECUTE SQL - Language Statements + - - EXECUTE - - - execute a prepared query - + EXECUTE + execute a prepared statement - - - 2002-08-12 - - - EXECUTE plan_name [ (parameter [, ...] ) ] [ INTO [ TEMPORARY | TEMP ] table ] - - - - - 2002-08-12 - - - Inputs - - - - - - plan_name - - - The name of the prepared query to execute. - - - - - parameter - - - The actual value of a parameter to the prepared query. This - must be an expression yielding a value of a type compatible - with the data-type specified for this parameter position in - the PREPARE statement that created the - prepared query. - - - - - - table - - - The name of the table in which to store the results of - executing the query (if it is a SELECT). If - no table is specified, the results are returned to the client - (as normal). - - - - - - + + +EXECUTE plan_name [ (parameter [, ...] ) ] [ INTO [ TEMPORARY | TEMP ] table ] + - - - 2002-08-12 - - - Description - + + Description EXECUTE is used to execute a previously prepared - query. Since prepared queries only exist for the duration of a - session, the prepared query must have been created by a + statement. Since prepared statements only exist for the duration of a + session, the prepared statement must have been created by a PREPARE statement executed earlier in the current session. - If the PREPARE statement that created the query + If the PREPARE statement that created the statement specified some parameters, a compatible set of parameters must be passed to the EXECUTE statement, or else an - error is raised. Note that (unlike functions) prepared queries are - not overloaded based on the type or number of their parameters: the - name of a prepared query must be unique within a database session. + error is raised. Note that (unlike functions) prepared statements are + not overloaded based on the type or number of their parameters; the + name of a prepared statement must be unique within a database session. Like SELECT INTO, EXECUTE can - store the results of executing the query into a newly-created - table, by specifying an INTO clause. For more information on this behavior, + store the results of executing a query into a newly-created + table, by specifying an INTO clause. For more information on this behavior, see . - For more information on the creation and usage of prepared queries, + For more information on the creation and usage of prepared statements, see . - - - Compatibility - + + Parameters + + + + plan_name + + + The name of the prepared statement to execute. + + + - - - 2002-08-12 - - - SQL92 - - - SQL92 includes an EXECUTE statement, but it is - only for use in embedded SQL clients. The - EXECUTE statement implemented by - PostgreSQL also uses a somewhat - different syntax. - - + + parameter + + + The actual value of a parameter to the prepared statement. This + must be an expression yielding a value of a type compatible with + the data type specified for this parameter position in the + PREPARE command that created the prepared + statement. + + + + + + table + + + The name of the table in which to store the results of executing + the statement (if it is a SELECT). If no + table is specified, the results are returned to the client (as + normal). + + + + + + + + Compatibility + + + The SQL standard includes an EXECUTE statement, + but it is only for use in embedded SQL. This version of the + EXECUTE statement also uses a somewhat different + syntax. + diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 02a6a63c42..2ac74e8a38 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -1,5 +1,5 @@ @@ -8,255 +8,212 @@ PostgreSQL documentation EXPLAIN SQL - Language Statements + - - EXPLAIN - - - show the execution plan of a statement - + EXPLAIN + show the execution plan of a statement - - 1999-07-20 - - -EXPLAIN [ ANALYZE ] [ VERBOSE ] query - - - - - 1998-09-01 - - - Inputs - - - - - - ANALYZE - - - Flag to carry out the query and show actual run times. - - - - - VERBOSE - - - Flag to show detailed query plan dump. - - - - - query - - - Any SELECT, INSERT, UPDATE, - DELETE, EXECUTE, - or DECLARE CURSOR query. - - - - - - - - - - 1998-04-15 - - - Outputs - - - - - - Query plan - - - Explicit query plan from the PostgreSQL - planner. - - - - - - - - - Prior to PostgreSQL 7.3, the query - plan was emitted in the form of a NOTICE - message. Now it appears as a query result (formatted like a - table with a single text column). - - - + +EXPLAIN [ ANALYZE ] [ VERBOSE ] statement + - - - 1998-04-15 - - - Description - + + Description This command displays the execution plan that the PostgreSQL planner generates for the - supplied query. The execution plan shows how the table(s) - referenced by the query will be scanned---by plain sequential scan, + supplied statenebt. The execution plan shows how the table(s) + referenced by the statement will be scanned---by plain sequential scan, index scan, etc.---and if multiple tables are referenced, what join - algorithms will be used to bring together the required tuples from + algorithms will be used to bring together the required row from each input table. - The most critical part of the display is the estimated query execution + The most critical part of the display is the estimated statement execution cost, which is the planner's guess at how long it will take to run the - query (measured in units of disk page fetches). Actually two numbers - are shown: the start-up time before the first tuple can be returned, and - the total time to return all the tuples. For most queries the total time - is what matters, but in contexts such as an EXISTS sub-query the planner + statement (measured in units of disk page fetches). Actually two numbers + are shown: the start-up time before the first row can be returned, and + the total time to return all the rows. For most queries the total time + is what matters, but in contexts such as a subquery in EXISTS, the planner will choose the smallest start-up time instead of the smallest total time - (since the executor will stop after getting one tuple, anyway). - Also, if you limit the number of tuples to return with a LIMIT clause, + (since the executor will stop after getting one row, anyway). + Also, if you limit the number of rows to return with a LIMIT clause, the planner makes an appropriate interpolation between the endpoint costs to estimate which plan is really the cheapest. - - - In order to allow the PostgreSQL query - planner to make reasonably informed decisions when optimizing - queries, the ANALYZE statement should be run - to record statistics about the distribution of data within the - table. If you have not done this (or if the statistical distribution - of the data in the table has changed significantly since the last - time ANALYZE was run), the estimated costs - are unlikely to conform to the real properties of the query, - and consequently an inferior query plan may be chosen. - - - - The ANALYZE option causes the query to be actually executed, not only + The ANALYZE option causes the statement to be actually executed, not only planned. The total elapsed time expended within each plan node (in milliseconds) and total number of rows it actually returned are added to the display. This is useful for seeing whether the planner's estimates are close to reality. - + - Keep in mind that the query is actually executed when ANALYZE is used. - Although EXPLAIN will discard any output that a SELECT - would return, - other side-effects of the query will happen as usual. - If you wish to use EXPLAIN ANALYZE on an INSERT, - UPDATE, DELETE, or EXECUTE query without letting the query affect your - data, use this approach: - + Keep in mind that the statement is actually executed when + ANALYZE is used. Although + EXPLAIN will discard any output that a + SELECT would return, other side effects of the + statement will happen as usual. If you wish to use + EXPLAIN ANALYZE on an + INSERT, UPDATE, + DELETE, or EXECUTE statement + without letting the command affect your data, use this approach: + BEGIN; EXPLAIN ANALYZE ...; ROLLBACK; - + - + + + + + Parameter + + + + ANALYZE + + + Carry out the command and show the actual run times. + + + + + + VERBOSE + + + Show the full internal representation of the plan tree, rather + than just a summary. Usually this option is only useful for + debugging PostgreSQL. The + VERBOSE output is either pretty-printed or + not, depending on the setting of the + explain_pretty_print configuration parameter. + + + + + + statement + + + Any SELECT, INSERT, UPDATE, + DELETE, EXECUTE, or DECLARE + statement, whose execution plan you wish to see. + + + + + + + + Diagnostics - The VERBOSE option emits the full internal representation of the plan tree, - rather than just a summary. - Usually this option is only useful for debugging - PostgreSQL. The VERBOSE dump is either - pretty-printed or not, depending on the setting of the - configuration parameter. + EXPLAIN prints the execution plan of the + specified statement from the PostgreSQL + planner. + - - - 1998-04-15 - - - Notes - - - There is only sparse documentation on the optimizer's use of cost - information in PostgreSQL. - Refer to for more information. - - + + Notes + + + There is only sparse documentation on the optimizer's use of cost + information in PostgreSQL. Refer to + for more information. + + + + In order to allow the PostgreSQL query + planner to make reasonably informed decisions when optimizing + queries, the ANALYZE statement should be run to + record statistics about the distribution of data within the + table. If you have not done this (or if the statistical + distribution of the data in the table has changed significantly + since the last time ANALYZE was run), the + estimated costs are unlikely to conform to the real properties of + the query, and consequently an inferior query plan may be chosen. + + + + Prior to PostgreSQL 7.3, the plan was + emitted in the form of a NOTICE message. Now it + appears as a query result (formatted like a table with a single + text column). + - - - Usage - + + Examples - To show a query plan for a simple query on a table with a single - int4 column and 10000 rows: + To show the plan for a simple query on a table with a single + integer column and 10000 rows: - + EXPLAIN SELECT * FROM foo; - + QUERY PLAN --------------------------------------------------------- Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4) (1 row) - - + - If there is an index and we use a query with an indexable WHERE condition, - EXPLAIN will show a different plan: + If there is an index and we use a query with an indexable + WHERE condition, EXPLAIN + might show a different plan: - + EXPLAIN SELECT * FROM foo WHERE i = 4; - + QUERY PLAN -------------------------------------------------------------- Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4) Index Cond: (i = 4) (2 rows) - - + And here is an example of a query plan for a query using an aggregate function: - + EXPLAIN SELECT sum(i) FROM foo WHERE i < 10; - + QUERY PLAN --------------------------------------------------------------------- Aggregate (cost=23.93..23.93 rows=1 width=4) -> Index Scan using fi on foo (cost=0.00..23.92 rows=6 width=4) Index Cond: (i < 10) (3 rows) - - + - Here is an example of using EXPLAIN EXECUTE to display the query - plan for a prepared query: + Here is an example of using EXPLAIN EXECUTE to + display the execution plan for a prepared query: - + PREPARE query(int, int) AS SELECT sum(bar) FROM test WHERE id > $1 AND id < $2 GROUP BY foo; EXPLAIN ANALYZE EXECUTE query(100, 200); - + QUERY PLAN ------------------------------------------------------------------------------------------------------------------------- HashAggregate (cost=39.53..39.53 rows=1 width=8) (actual time=0.66..0.67 rows=7 loops=1) @@ -264,38 +221,28 @@ EXPLAIN ANALYZE EXECUTE query(100, 200); Index Cond: ((id > $1) AND (id < $2)) Total runtime: 0.85 msec (4 rows) - - + - Note that the specific numbers shown, and even the selected query - strategy, may vary between PostgreSQL - releases due to planner improvements. In addition, the - ANALYZE command uses random sampling to estimate - data statistics; therefore, it is possible - for cost estimates to change after a fresh run of + Of course, the specific numbers shown here depend on the actual + contents of the tables involved. Also note that the numbers, and + even the selected query strategy, may vary between + PostgreSQL releases due to planner + improvements. In addition, the ANALYZE command + uses random sampling to estimate data statistics; therefore, it is + possible for cost estimates to change after a fresh run of ANALYZE, even if the actual distribution of data in the table has not changed. - - - Compatibility - - - - - 1998-09-01 - - - SQL92 - - - There is no EXPLAIN statement defined in SQL92. - - + + Compatibility + + + There is no EXPLAIN statement defined in the SQL standard. + diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 5457a950ed..7ba370d659 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,5 +1,5 @@ @@ -43,10 +43,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } Description - The GRANT command gives specific permissions on + The GRANT command gives specific privileges on an object (table, view, sequence, database, function, procedural language, or schema) to - one or more users or groups of users. These permissions are added + one or more users or groups of users. These privileges are added to those already granted, if any. @@ -55,18 +55,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } privileges are to be granted to all users, including those that may be created later. PUBLIC may be thought of as an implicitly defined group that always includes all users. - Note that any particular user will have the sum + Any particular user will have the sum of privileges granted directly to him, privileges granted to any group he is presently a member of, and privileges granted to PUBLIC. - There is no need to grant privileges to the creator of an object, - as the creator has all privileges by default. (The creator could, + There is no need to grant privileges to the owner of an object (usually the user that created it), + as the owner has all privileges by default. (The owner could, however, choose to revoke some of his own privileges for safety.) - Note that the right to drop an object, or to alter it in any way is - not described by a grantable right; it is inherent in the creator, + The right to drop an object, or to alter it in any way is + not described by a grantable right; it is inherent in the owner, and cannot be granted or revoked. @@ -84,7 +84,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } TEMP table creation privilege for databases; EXECUTE privilege for functions; and USAGE privilege for languages. - The object creator may of course revoke these privileges. (For maximum + The object owner may of course revoke these privileges. (For maximum security, issue the REVOKE in the same transaction that creates the object; then there is no window in which another user may use the object.) @@ -252,7 +252,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } - It should be noted that database superusers can access + It should be noted that database superusers can access all objects regardless of object privilege settings. This is comparable to the rights of root in a Unix system. As with root, it's unwise to operate as a superuser @@ -267,17 +267,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } - Use 's \dp command + Use 's \z command to obtain information about existing privileges, for example: -lusitania=> \dp mytable +=> \z mytable + Access privileges for database "lusitania" Schema | Table | Access privileges --------+---------+--------------------------------------- public | mytable | {=r/postgres,miriam=arwdRxt/postgres,"group todos=arw/postgres"} (1 row) - The entries shown by \dp are interpreted thus: + The entries shown by \z are interpreted thus: =xxxx -- privileges granted to PUBLIC uname=xxxx -- privileges granted to a user @@ -305,14 +306,14 @@ lusitania=> \dp mytable GRANT SELECT ON mytable TO PUBLIC; -GRANT SELECT,UPDATE,INSERT ON mytable TO GROUP todos; +GRANT SELECT, UPDATE, INSERT ON mytable TO GROUP todos; If the Access privileges column is empty for a given object, -it means the object has default privileges (that is, its privileges field -is NULL). Default privileges always include all privileges for the owner, +it means the object has default privileges (that is, its privileges columm +is null). Default privileges always include all privileges for the owner, and may include some privileges for PUBLIC depending on the object type, as explained above. The first GRANT or REVOKE on an object @@ -325,7 +326,7 @@ will instantiate the default privileges (producing, for example, Examples - Grant insert privilege to all users on table films: + Grant insert privilege to all users on table films: GRANT INSERT ON films TO PUBLIC; @@ -344,37 +345,35 @@ GRANT ALL PRIVILEGES ON kinds TO manuel; Compatibility - - SQL92 - - The PRIVILEGES key word in ALL - PRIVILEGES is required. SQL does not - support setting the privileges on more than one table per command. + According to the SQL standard, the PRIVILEGES + key word in ALL PRIVILEGES is required. The + SQL standard does not support setting the privileges on more than + one object per command. - The SQL syntax for GRANT - allows setting privileges for individual columns within a table: + The SQL standard allows setting privileges for individual columns + within a table: -GRANT privilege [, ...] +GRANT privileges ON table [ ( column [, ...] ) ] [, ...] TO { PUBLIC | username [, ...] } [ WITH GRANT OPTION ] - SQL allows to grant the USAGE privilege on - other kinds of objects: CHARACTER SET, COLLATION, TRANSLATION, DOMAIN. + The SQL standard provides for a USAGE privilege + on other kinds of objects: character sets, collations, + translations, domains. - The TRIGGER privilege was introduced in SQL99. The RULE privilege - is a PostgreSQL extension. + The RULE privilege, and privileges on + databases, schemas, languages, and sequences are PostgreSQL + extensions. - - diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index fa1f945068..d2e29a8757 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -1,5 +1,5 @@ @@ -8,246 +8,207 @@ PostgreSQL documentation INSERT SQL - Language Statements + - - INSERT - - - create new rows in a table - + INSERT + create new rows in a table + - - 2000-08-08 - - + INSERT INTO table [ ( column [, ...] ) ] - { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) | SELECT query } - - - - - Inputs - - - - - - - table - - - The name (optionally schema-qualified) of an existing table. - - - - - - column - - - The name of a column in table. - - - - - - DEFAULT VALUES - - - All columns will be filled by null values or by values specified - when the table was created using DEFAULT clauses. - - - - - - expression - - - A valid expression or value to assign to column. - - - - - - DEFAULT - - - This column will be filled in by the column DEFAULT clause, or NULL if - a default is not available. - - - - - - query - - - A valid query. Refer to the SELECT statement for a further description - of valid arguments. - - - - - - - - - - Outputs - - - - - - -INSERT oid 1 - - - - Message returned if only one row was inserted. - oid - is the numeric OID of the inserted row. - - - - - -INSERT 0 # - - - - Message returned if more than one rows were inserted. - # - is the number of rows inserted. - - - - - - + { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) | query } + - - - Description - + + Description INSERT allows one to insert new rows into a table. One can insert a single row at a time or several rows as a result of a query. - The columns in the target list may be listed in any order. + The columns in the target list may be listed in any order. Each column not present in the target list will be inserted - using a default value, either a declared DEFAULT value - or NULL. PostgreSQL will reject the new - column if a NULL is inserted into a column declared NOT NULL. + using a default value, either a declared default value + or null. - If the expression for each column - is not of the correct data type, automatic type coercion will be - attempted. + If the expression for each column is not of the correct data type, + automatic type conversion will be attempted. - You must have insert privilege to a table in order to append - to it, as well as select privilege on any table specified - in a WHERE clause. + You must have INSERT privilege to a table in + order to insert into it. If you use the query clause to insert rows from a + query, you also need to have SELECT privilege on + any table used in the query. - - - Usage - + + Parameters + + + + table + + + The name (optionally schema-qualified) of an existing table. + + + + + + column + + + The name of a column in table. + + + + + + DEFAULT VALUES + + + All columns will be filled their default values. + + + + + + expression + + + An expression or value to assign to column. + + + + + + DEFAULT + + + This column will be filled with its default value. + + + + + + query + + + A query (SELECT statement) that supplies the + rows to be inserted. Refer to the SELECT + statement for a description of the syntax. + + + + + + + + Diagnostics + + + + INSERT oid 1 + + + Message returned if only one row was inserted. + oid is the + OID of the inserted row. + + + + + + INSERT 0 count + + + Message returned if more than one rows were inserted. + count is the number of rows inserted. + + + + + + + + Examples + Insert a single row into table films: - + INSERT INTO films VALUES - ('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute'); - + ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes'); + - In this second example the last column len is - omitted and therefore it will have the default value of NULL: + In this second example, the last column len is + omitted and therefore it will have the default value of null: - + INSERT INTO films (code, title, did, date_prod, kind) - VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama'); - + VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama'); + - In the third example, we use the DEFAULT values for the date columns - rather than specifying an entry. + The third example uses the DEFAULT clause for + the date columns rather than specifying a value: - + INSERT INTO films VALUES - ('UA502','Bananas',105,DEFAULT,'Comedy',INTERVAL '82 minute'); + ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes'); INSERT INTO films (code, title, did, date_prod, kind) VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama'); - - - - - Insert a single row into table distributors; note that - only column name is specified, so the omitted - column did will be assigned its default value: - - -INSERT INTO distributors (name) VALUES ('British Lion'); - + - Insert several rows into table films from table tmp: + This examples inserts several rows into table + films from table tmp: - + INSERT INTO films SELECT * FROM tmp; - + - Insert into arrays: + This example inserts into array columns: - + -- Create an empty 3x3 gameboard for noughts-and-crosses --- (all of these queries create the same board attribute) +-- (all of these commands create the same board) INSERT INTO tictactoe (game, board[1:3][1:3]) VALUES (1,'{{"","",""},{},{"",""}}'); INSERT INTO tictactoe (game, board[3][3]) VALUES (2,'{}'); INSERT INTO tictactoe (game, board) VALUES (3,'{{,,},{,,},{,,}}'); - + - - - Compatibility - - - - - SQL92 - - - INSERT is fully compatible with SQL92. - Possible limitations in features of the - query - clause are documented for - . - - + + Compatibility + + + INSERT conforms fully to the SQL standard. + Possible limitations of the query clause are documented under + . + diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 8bcb730991..154224d0d2 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -1,5 +1,5 @@ @@ -8,121 +8,54 @@ PostgreSQL documentation LISTEN SQL - Language Statements + - - LISTEN - - - listen for a notification - + LISTEN + listen for a notification + - - 1999-07-20 - - + LISTEN name - - - - - 1998-10-07 - - - Inputs - - - - - - name - - - Name of notify condition. - - - - - - - - - - 1998-09-24 - - - Outputs - - - - - - -LISTEN - - - - Message returned upon successful completion of registration. - - - - - -WARNING: Async_Listen: We are already listening on name - - - - If this backend is already registered for that notify condition. - - - - - - + - - - 1998-10-07 - - - Description - + + Description - LISTEN registers the current - PostgreSQL backend as a - listener on the notify condition - name. + LISTEN registers the current session as a + listener on the notification condition name. - Whenever the command - NOTIFY name - is invoked, either by this backend or another one connected to - the same database, all the backends currently listening on that notify - condition are notified, and each will in turn notify its connected - frontend application. See the discussion of NOTIFY - for more information. + Whenever the command NOTIFY name is invoked, either + by this session or another one connected to the same database, all + the sessions currently listening on that notification condition are + notified, and each will in turn notify its connected client + application. See the discussion of NOTIFY for + more information. - A backend can be unregistered for a given notify condition with the - UNLISTEN command. Also, a backend's listen registrations - are automatically cleared when the backend process exits. + A session can be unregistered for a given notify condition with the + UNLISTEN command. A session's listen + registrations are automatically cleared when the session ends. - The method a frontend application must use to detect notify events depends on + The method a client application must use to detect notification events depends on which PostgreSQL application programming interface it uses. With the libpq library, the application issues LISTEN as an ordinary SQL command, and then must - periodically call the routine PQnotifies to find out - whether any notify events have been received. Other interfaces such as + periodically call the function PQnotifies to find out + whether any notification events have been received. Other interfaces such as libpgtcl provide higher-level methods for handling notify events; indeed, with libpgtcl the application programmer should not even issue LISTEN or UNLISTEN directly. See the - documentation for the library you are using for more details. + documentation for the interface you are using for more details. @@ -131,64 +64,67 @@ WARNING: Async_Listen: We are already listening on name + + + Name of a notify condition (any identifier). + + + + + - - - 1998-10-07 - - - Notes - - - - name - can be any string valid as a name; - it need not correspond to the name of any actual table. If - notifyname - is enclosed in double-quotes, it need not even be a syntactically - valid name, but can be any string up to 63 characters long. - - - In some previous releases of - PostgreSQL, - name - had to be enclosed in double-quotes when it did not correspond to any existing - table name, even if syntactically valid as a name. That is no longer required. - - + + Diagnostics + + + + LISTEN + + + Message returned upon successful completion of registration. + + + + + + WARNING: Async_Listen: We are already listening on name + + + Message returned if this session is already registered for that notification condition. + + + + - - - Usage - + + Examples + Configure and execute a listen/notify sequence from psql: LISTEN virtual; NOTIFY virtual; - Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. - - - Compatibility - - - - - 1998-09-01 - - - SQL92 - - - There is no LISTEN in SQL92. - - + + Compatibility + + + There is no LISTEN statement in the SQL + standard. + diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index 0c80e0f024..056322f58e 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -1,5 +1,5 @@ @@ -23,11 +23,11 @@ LOAD 'filename' Description - Loads a shared library file into the PostgreSQL - backend's address space. If the file had been loaded previously, + This command loads a shared library file into the PostgreSQL + server's address space. If the file had been loaded previously, it is first unloaded. This command is primarily useful to unload and reload a shared library file that has been changed since the - backend first loaded it. To make use of the shared library, + server first loaded it. To make use of the shared library, function(s) in it need to be declared using the command. diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index 8b5072af4f..c39cb154b8 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -1,5 +1,5 @@ @@ -8,251 +8,25 @@ PostgreSQL documentation LOCK SQL - Language Statements + - - LOCK - - - explicitly lock a table - + LOCK + lock a table + - - 2001-07-09 - - -LOCK [ TABLE ] name [, ...] -LOCK [ TABLE ] name [, ...] IN lockmode MODE + +LOCK [ TABLE ] name [, ...] [ IN lockmode MODE ] where lockmode is one of: - ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE | - SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE - - - - - 1999-06-09 - - - - Inputs - - - - - - name - - - The name (optionally schema-qualified) of an existing table to lock. - - - - - - ACCESS SHARE MODE - - - This is the least restrictive lock mode. It conflicts only with - ACCESS EXCLUSIVE mode. It is used to protect a table from being - modified by concurrent ALTER TABLE, - DROP TABLE and VACUUM FULL - commands. - - - - - The SELECT command acquires a - lock of this mode on referenced tables. In general, any query - that only reads a table and does not modify it will acquire - this lock mode. - - - - - - - ROW SHARE MODE - - - Conflicts with EXCLUSIVE and ACCESS EXCLUSIVE lock modes. - - - - - The SELECT FOR UPDATE command acquires a - lock of this mode on the target table(s) (in addition to - ACCESS SHARE locks on any other tables - that are referenced but not selected ). - - - - - - - ROW EXCLUSIVE MODE - - - Conflicts with SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE and - ACCESS EXCLUSIVE modes. - - - - - The commands UPDATE, - DELETE, and INSERT - acquire this lock mode on the target table (in addition to - ACCESS SHARE locks on any other referenced - tables). In general, this lock mode will be acquired by any - query that modifies the data in a table. - - - - - - - SHARE UPDATE EXCLUSIVE MODE - - - Conflicts with SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, - EXCLUSIVE and - ACCESS EXCLUSIVE modes. This mode protects a table against - concurrent schema changes and VACUUM runs. - - - - - Acquired by VACUUM (without - ). - - - - - - - SHARE MODE - - - Conflicts with ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, - SHARE ROW EXCLUSIVE, EXCLUSIVE and - ACCESS EXCLUSIVE modes. This mode protects a table against - concurrent data changes. - - - - - Acquired by CREATE INDEX. - - - - - - - SHARE ROW EXCLUSIVE MODE - - - Conflicts with ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, - SHARE ROW EXCLUSIVE, EXCLUSIVE and ACCESS EXCLUSIVE modes. - - - - - This lock mode is not automatically acquired by any - PostgreSQL command. - - - - - - - EXCLUSIVE MODE - - - Conflicts with ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, - SHARE, SHARE ROW EXCLUSIVE, - EXCLUSIVE and ACCESS EXCLUSIVE modes. - This mode allows only concurrent ACCESS SHARE, i.e., only reads - from the table can proceed in parallel with a transaction holding - this lock mode. - - - - - This lock mode is not automatically acquired by any - PostgreSQL command. - - - - - - - ACCESS EXCLUSIVE MODE - - - Conflicts with all lock modes. This mode guarantees that the - holder is the only transaction accessing the table in any way. - - - - - Acquired by ALTER TABLE, - DROP TABLE, and VACUUM FULL - statements. - This is also the default lock mode for LOCK TABLE - statements that do not specify a mode explicitly. - - - - - - - - - - - 1998-09-24 - - - Outputs - - - - - - -LOCK TABLE - - - - The lock was successfully acquired. - - - - - - -ERROR name: Table does not exist. - - - - Message returned if name - does not exist. - - - - - - + ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE + | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE + - - - 1998-09-24 - - - Description - + + Description LOCK TABLE obtains a table-level lock, waiting if @@ -263,109 +37,114 @@ ERROR name: Table does not exist. - When acquiring locks automatically for commands that reference tables, - PostgreSQL always uses the least restrictive - lock mode possible. LOCK TABLE + When acquiring locks automatically for commands that reference + tables, PostgreSQL always uses the least + restrictive lock mode possible. LOCK TABLE provides for cases when you might need more restrictive locking. - - - - For example, suppose an application runs a transaction at READ COMMITTED - isolation level and needs to ensure that data in a table remains stable - for the duration of the - transaction. To achieve this you could obtain SHARE lock mode over the + For example, suppose an application runs a transaction at the + isolation level read committed and needs to ensure that data in a + table remains stable for the duration of the transaction. To + achieve this you could obtain SHARE lock mode over the table before querying. This will prevent concurrent data changes - and ensure subsequent reads of the table see a stable - view of committed data, because SHARE lock mode conflicts with the ROW - EXCLUSIVE lock acquired by writers, and your - LOCK TABLE name IN SHARE MODE - statement will wait until any concurrent holders of ROW EXCLUSIVE mode - commit or roll back. Thus, once you obtain the lock, there are no - uncommitted writes outstanding; furthermore none can begin until you - release the lock. - - - - To achieve a similar effect when running a transaction - at the SERIALIZABLE isolation level, you have to execute the - LOCK TABLE - statement before executing any DML statement. A serializable - transaction's view of data will be frozen when its first DML statement - begins. A later LOCK will still prevent concurrent writes - --- but it - won't ensure that what the transaction reads corresponds to the latest - committed values. - - + and ensure subsequent reads of the table see a stable view of + committed data, because SHARE lock mode conflicts with + the ROW EXCLUSIVE lock acquired by writers, and your + LOCK TABLE name IN SHARE MODE + statement will wait until any concurrent holders of ROW + EXCLUSIVE mode locks commit or roll back. Thus, once you + obtain the lock, there are no uncommitted writes outstanding; + furthermore none can begin until you release the lock. - + - If a transaction of this sort is going to - change the data in the table, then it should use SHARE ROW EXCLUSIVE lock - mode instead of SHARE mode. This ensures that only one transaction of - this type runs at a time. Without this, a deadlock is possible: two - transactions might both acquire SHARE mode, and then be unable to also - acquire ROW EXCLUSIVE mode to actually perform their updates. (Note that - a transaction's own locks never conflict, so a transaction can acquire - ROW EXCLUSIVE mode when it holds SHARE mode --- but not if anyone else - holds SHARE mode.) + To achieve a similar effect when running a transaction at the + isolation level serializable, you have to execute the LOCK + TABLE statement before executing any data modification + statement. A serializable transaction's view of data will be + frozen when its first data modification statement begins. A later + LOCK TABLE will still prevent concurrent writes --- but it + won't ensure that what the transaction reads corresponds to the + latest committed values. - Two general rules may be followed to prevent deadlock conditions: + If a transaction of this sort is going to change the data in the + table, then it should use SHARE ROW EXCLUSIVE lock mode + instead of SHARE mode. This ensures that only one + transaction of this type runs at a time. Without this, a deadlock + is possible: two transactions might both acquire SHARE + mode, and then be unable to also acquire ROW EXCLUSIVE + mode to actually perform their updates. (Note that a transaction's + own locks never conflict, so a transaction can acquire ROW + EXCLUSIVE mode when it holds SHARE mode --- but not + if anyone else holds SHARE mode.) To avoid deadlocks, + make sure all transactions acquire locks on the same objects in the + same order, and if multiple lock modes are involved for a single + object, then transactions should always acquire the most + restrictive mode first. - - - - Transactions have to acquire locks on the same objects in the same order. - - - - For example, if one application updates row R1 and than updates - row R2 (in the same transaction) then the second application shouldn't - update row R2 if it's going to update row R1 later (in a single transaction). - Instead, it should update rows R1 and R2 in the same order as the first - application. - - - - - - If multiple lock modes are involved for a single object, - then transactions should always acquire the most restrictive mode first. - - - - An example for this rule was given previously when discussing the - use of SHARE ROW EXCLUSIVE mode rather than SHARE mode. - - - - - - PostgreSQL does detect deadlocks and will - rollback at least one waiting transaction to resolve the deadlock. - If it is not practical to code an application to follow the above rules - strictly, an alternative solution is to be prepared to retry transactions - when they are aborted by deadlocks. + More information about the lock modes and locking strategies can be + found in . + - - When locking multiple tables, the command LOCK a, b; is - equivalent to LOCK a; LOCK b;. The tables are locked one-by-one - in the order specified in the - LOCK command. - + + Parameters + + + + name + + + The name (optionally schema-qualified) of an existing table to + lock. + + + + The command LOCK a, b; is equivalent to + LOCK a; LOCK b;. The tables are locked one-by-one in + the order specified in the LOCK command. + + + + + + lockmode + + + The lock mode specifies which locks this lock conflicts with. + Lock modes are described in . + + + + If no lock mode is specified, then ACCESS + EXCLUSIVE, the most restrictive mode, is used. + + + + + - - - 1999-06-08 - - - Notes - + + Diagnostics + + + + LOCK TABLE + + + Message returned if the lock was successfully acquired. + + + + + + + + Notes LOCK ... IN ACCESS SHARE MODE requires SELECT @@ -375,81 +154,32 @@ ERROR name: Table does not exist. LOCK is useful only inside a transaction block - (BEGIN...COMMIT), since the lock is dropped + (BEGIN/COMMIT pair), since the lock is dropped as soon as the transaction ends. A LOCK command appearing outside any transaction block forms a self-contained transaction, so the lock will be dropped as soon as it is obtained. - RDBMS locking uses the following standard terminology: - - - - EXCLUSIVE - - - An exclusive lock prevents other locks of the same type from being - granted. - - - - - - SHARE - - - A shared lock allows others to also hold the same type of lock, - but prevents the corresponding EXCLUSIVE lock from being granted. - - - - - - ACCESS - - - Locks table schema. - - - - - - ROW - - - Locks individual rows. - - - - + LOCK TABLE only deals with table-level locks, and so + the mode names involving ROW are all misnomers. These + mode names should generally be read as indicating the intention of + the user to acquire row-level locks within the locked table. Also, + ROW EXCLUSIVE mode is a sharable table lock. Keep in + mind that all the lock modes have identical semantics so far as + LOCK TABLE is concerned, differing only in the rules + about which modes conflict with which. - - - PostgreSQL does not follow this terminology - exactly. LOCK TABLE only deals with table-level locks, and - so the mode names involving ROW are all misnomers. These mode names - should generally be read as indicating the intention of the user to - acquire row-level locks within the locked table. Also, - ROW EXCLUSIVE mode does not follow this naming convention accurately, - since it is a sharable table lock. Keep in mind that all the lock modes - have identical semantics so far as LOCK TABLE is concerned, - differing only in the rules about which modes conflict with which. - - - - - - Usage - + + Examples - Obtain a SHARE lock on a primary key table when going to perform + Obtain a SHARE lock on a primary key table when going to perform inserts into a foreign key table: - + BEGIN WORK; LOCK TABLE films IN SHARE MODE; SELECT id FROM films @@ -458,50 +188,42 @@ SELECT id FROM films INSERT INTO films_user_comments VALUES (_id_, 'GREAT! I was waiting for it for so long!'); COMMIT WORK; - + - Take a SHARE ROW EXCLUSIVE lock on a primary key table when going to perform + Take a SHARE ROW EXCLUSIVE lock on a primary key table when going to perform a delete operation: - + BEGIN WORK; LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE; DELETE FROM films_user_comments WHERE id IN (SELECT id FROM films WHERE rating < 5); DELETE FROM films WHERE rating < 5; COMMIT WORK; - + - - - Compatibility - + + Compatibility - - - 1998-09-24 - - - SQL92 - - - There is no LOCK TABLE in SQL92, - which instead uses SET TRANSACTION to specify - concurrency levels on transactions. We support that too; see - for details. - + + There is no LOCK TABLE in the SQL standard, + which instead uses SET TRANSACTION to specify + concurrency levels on transactions. PostgreSQL supports that too; + see for details. + - - Except for ACCESS SHARE, ACCESS EXCLUSIVE, and SHARE UPDATE EXCLUSIVE lock - modes, the PostgreSQL lock modes and the - LOCK TABLE syntax are compatible with those - present in Oracle(TM). - - + + Except for ACCESS SHARE, ACCESS EXCLUSIVE, + and SHARE UPDATE EXCLUSIVE lock modes, the + PostgreSQL lock modes and the + LOCK TABLE syntax are compatible with those + present in Oracle. + diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index e24420e229..82cd153179 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -1,5 +1,5 @@ @@ -8,113 +8,53 @@ PostgreSQL documentation NOTIFY SQL - Language Statements + - - NOTIFY - - - generate a notification - + NOTIFY + generate a notification + - - 1999-07-20 - - + NOTIFY name - - - - - 1998-10-07 - - - Inputs - - - - - - notifyname - - - Notify condition to be signaled. - - - - - - - - - - 1998-10-07 - - - Outputs - - - - - - -NOTIFY - - - - Acknowledgement that notify command has executed. - - - - - Notify events - - - Events are delivered to listening frontends; whether and how each frontend - application reacts depends on its programming. - - - - - - + - - - 1998-10-07 - - - Description - + + Description + - The NOTIFY command sends a notify event to each - frontend application that has previously executed - LISTEN notifyname - for the specified notify condition in the current database. + The NOTIFY command sends a notification event to each + client application that has previously executed + LISTEN name + for the specified notification name in the current database. + - The information passed to the frontend for a notify event includes the notify - condition name and the notifying backend process's PID. It is up to the - database designer to define the condition names that will be used in a given + The information passed to the client for a notifiation event includes the notification + name and the notifying session's server process PID. It is up to the + database designer to define the notification names that will be used in a given database and what each one means. + - Commonly, the notify condition name is the same as the name of some table in - the database, and the notify event essentially means I changed this table, + Commonly, the notification name is the same as the name of some table in + the database, and the notify event essentially means, I changed this table, take a look at it to see what's new. But no such association is enforced by the NOTIFY and LISTEN commands. For - example, a database designer could use several different condition names + example, a database designer could use several different notification names to signal different sorts of changes to a single table. + NOTIFY provides a simple form of signal or - IPC (interprocess communication) mechanism for a collection of processes + interprocess communication mechanism for a collection of processes accessing the same PostgreSQL database. Higher-level mechanisms can be built by using tables in the database to - pass additional data (beyond a mere condition name) from notifier to + pass additional data (beyond a mere notification name) from notifier to listener(s). + When NOTIFY is used to signal the occurrence of changes to a particular table, a useful programming technique is to put the @@ -122,86 +62,91 @@ NOTIFY In this way, notification happens automatically when the table is changed, and the application programmer can't accidentally forget to do it. + NOTIFY interacts with SQL transactions in some important ways. Firstly, if a NOTIFY is executed inside a transaction, the notify events are not delivered until and unless the transaction is committed. This is appropriate, since if the transaction - is aborted we would like all the commands within it to have had no + is aborted, all the commands within it have had no effect, including NOTIFY. But it can be disconcerting if one - is expecting the notify events to be delivered immediately. Secondly, if - a listening backend receives a notify signal while it is within a transaction, - the notify event will not be delivered to its connected frontend until just + is expecting the notification events to be delivered immediately. Secondly, if + a listening session receives a notification signal while it is within a transaction, + the notification event will not be delivered to its connected client until just after the transaction is completed (either committed or aborted). Again, the - reasoning is that if a notify were delivered within a transaction that was + reasoning is that if a notification were delivered within a transaction that was later aborted, one would want the notification to be undone somehow---but - the backend cannot take back a notify once it has sent it to the frontend. - So notify events are only delivered between transactions. The upshot of this + the server cannot take back a notification once it has sent it to the client. + So notification events are only delivered between transactions. The upshot of this is that applications using NOTIFY for real-time signaling should try to keep their transactions short. + NOTIFY behaves like Unix signals in one important - respect: if the same condition name is signaled multiple times in quick - succession, recipients may get only one notify event for several executions + respect: if the same notification name is signaled multiple times in quick + succession, recipients may get only one notification event for several executions of NOTIFY. So it is a bad idea to depend on the number - of notifies received. Instead, use NOTIFY to wake up + of notifications received. Instead, use NOTIFY to wake up applications that need to pay attention to something, and use a database object (such as a sequence) to keep track of what happened or how many times it happened. + - It is common for a frontend that sends NOTIFY to be - listening on the same notify name itself. In that case it will get back a - notify event, just like all the other listening frontends. Depending on the - application logic, this could result in useless work---for example, - re-reading a database table to find the same updates that that frontend just - wrote out. In PostgreSQL 6.4 and later, it is - possible to avoid such extra work by noticing whether the notifying backend - process's PID (supplied in the notify event message) is the same as one's own - backend's PID (available from libpq). When they are the same, the notify - event is one's own work bouncing back, and can be ignored. (Despite what was - said in the preceding paragraph, this is a safe technique. - PostgreSQL keeps self-notifies separate from notifies - arriving from other backends, so you cannot miss an outside notify by ignoring - your own notifies.) + It is common for a client that executes NOTIFY + to be listening on the same notification name itself. In that case + it will get back a notification event, just like all the other + listening sessions. Depending on the application logic, this could + result in useless work, for example, reading a database table to + find the same updates that that session just wrote out. It is + possible to avoid such extra work by noticing whether the notifying + session's server process PID (supplied in the + notification event message) is the same as one's own session's + PID (available from libpq). When they + are the same, the notification event is one's own work bouncing + back, and can be ignored. (Despite what was said in the preceding + paragraph, this is a safe technique. + PostgreSQL keeps self-notifiications + separate from notifications arriving from other sessions, so you + cannot miss an outside notification by ignoring your own + notifications.) + + + + Parameters + + + + name + + + Name of the notification to be signaled (any identifier). + + + + + + + + Diagnostics - - - 1998-10-07 - - - Notes - - - name - can be any string valid as a name; - it need not correspond to the name of any actual table. If - name - is enclosed in double-quotes, it need not even be a syntactically - valid name, but can be any string up to 63 characters long. - - - In some previous releases of - PostgreSQL, - name - had to be enclosed in double-quotes when it did not correspond to any existing - table name, even if syntactically valid as a name. That is no longer required. - - - In PostgreSQL releases prior to 6.4, the backend - PID delivered in a notify message was always the PID of the frontend's own - backend. So it was not possible to distinguish one's own notifies from other - clients' notifies in those earlier releases. - - + + + NOTIFY + + + Message returned when the commmand has executed. + + + + - - - Usage - + + Examples + Configure and execute a listen/notify sequence from psql: @@ -214,23 +159,13 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. - - - Compatibility - - - - - 1998-09-24 - - - SQL92 - - - There is no NOTIFY statement in - SQL92. - - + + Compatibility + + + There is no NOTIFY statement in the SQL + standard. + diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index 7540173091..9f58b7a5ce 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -1,5 +1,5 @@ @@ -8,197 +8,158 @@ PostgreSQL documentation PREPARE SQL - Language Statements + - - PREPARE - - - create a prepared query - + PREPARE + prepare a statement for execution + - - 2002-08-12 - - - PREPARE plan_name [ (datatype [, ...] ) ] AS query - - - - - 2002-08-12 - - - Inputs - - - - - - plan_name - - - An arbitrary name given to this particular prepared query. It - must be unique within a single session, and is used to execute - or remove a previously prepared query. - - - - - datatype - - - The data-type of a parameter to the prepared query. - To refer to the parameters in the prepared query itself, - use $1, $2, etc. - - - - - query - - - Any SELECT, INSERT, UPDATE, - or DELETE query. - - - - - - - - - - 2002-08-12 - - - Outputs - - - - - - - PREPARE - - - - The query has been prepared successfully. - - - - - - - + +PREPARE plan_name [ (datatype [, ...] ) ] AS statement + - - - 2002-08-12 - - - Description - + + Description + - PREPARE creates a prepared query. A prepared - query is a server-side object that can be used to optimize + PREPARE creates a prepared statement. A prepared + statement is a server-side object that can be used to optimize performance. When the PREPARE statement is - executed, the specified query is parsed, rewritten, and - planned. When a subsequent EXECUTE statement is - issued, the prepared query need only be executed. Thus, the + executed, the specified statement is parsed, rewritten, and + planned. When an EXECUTE command is subsequently + issued, the prepared statement need only be executed. Thus, the parsing, rewriting, and planning stages are only performed once, - instead of every time the query is executed. + instead of every time the statement is executed. - Prepared queries can take parameters: values that are - substituted into the query when it is executed. To specify the - parameters to a prepared query, include a list of data-types with - the PREPARE statement. In the query itself, you - can refer to the parameters by position using + Prepared statements can take parameters: values that are + substituted into the statement when it is executed. To include + parameters in a prepared statement, supply a list of data types in + the PREPARE statement, and, in the statement to + be prepared itself, refer to the parameters by position using $1, $2, etc. When executing - the query, specify the actual values for these parameters in the - EXECUTE statement -- refer to - for more information. + the statement, specify the actual values for these parameters in + the EXECUTE statement. Refer to for more + information about that. - Prepared queries are stored locally (in the current backend), and - only exist for the duration of the current database session. When - the client exits, the prepared query is forgotten, and so it must be - re-created before being used again. This also means that a single - prepared query cannot be used by multiple simultaneous database - clients; however, each client can create their own prepared query + Prepared statements are only stored in and for the duration of + the current database session. When + the session ends, the prepared statement is forgotten, and so it must be + recreated before being used again. This also means that a single + prepared statement cannot be used by multiple simultaneous database + clients; however, each client can create their own prepared statement to use. - Prepared queries have the largest performance advantage when a - single backend is being used to execute a large number of similar - queries. The performance difference will be particularly - significant if the queries are complex to plan or rewrite. For + Prepared statements have the largest performance advantage when a + single session is being used to execute a large number of similar + statements. The performance difference will be particularly + significant if the statements are complex to plan or rewrite, for example, if the query involves a join of many tables or requires - the application of several rules. If the query is relatively simple + the application of several rules. If the statement is relatively simple to plan and rewrite but relatively expensive to execute, the - performance advantage of prepared queries will be less noticeable. + performance advantage of prepared statements will be less noticeable. + - - - 2002-08-12 - - - Notes - - - - In some situations, the query plan produced by - PostgreSQL for a prepared query may be - inferior to the plan produced if the query were submitted and - executed normally. This is because when the query is planned (and - the optimizer attempts to determine the optimal query plan), the - actual values of any parameters specified in the query are - unavailable. PostgreSQL collects - statistics on the distribution of data in the table, and can use - constant values in a query to make guesses about the likely - result of executing the query. Since this data is unavailable when - planning prepared queries with parameters, the chosen plan may be - sub-optimal. To examine the query plan - PostgreSQL has chosen for a prepared - query, use EXPLAIN EXECUTE. - - - - For more information on query planning and the statistics - collected by PostgreSQL for query - optimization purposes, see the documentation. - - + + Parameters + + + + plan_name + + + An arbitrary name given to this particular prepared + statement. It must be unique within a single session and is + subsequently used to execute or deallocate a previously prepared + statement. + + + + + + datatype + + + The data type of a parameter to the prepared statement. To + refer to the parameters in the prepared statement itself, use + $1, $2, etc. + + + + + + statement + + + Any SELECT, INSERT, UPDATE, + or DELETE statement. + + + + - - - Compatibility - - - - - 2002-08-12 - - - SQL92 - - - SQL92 includes a PREPARE statement, but it is - only for use in embedded SQL clients. The - PREPARE statement implemented by - PostgreSQL also uses a somewhat - different syntax. - - + + Diagnostics + + + + PREPARE + + + Message returned if the statement has been prepared successfully. + + + + + + + + Notes + + + In some situations, the query plan produced by for a prepared + statement may be inferior to the plan produced if the statement + were submitted and executed normally. This is because when the + statement is planned and the planer attempts to determine the + optimal query plan, the actual values of any parameters specified + in the statement are + unavailable. PostgreSQL collects + statistics on the distribution of data in the table, and can use + constant values in a statement to make guesses about the likely + result of executing the statement. Since this data is unavailable + when planning prepared statements with parameters, the chosen plan + may be suboptimal. To examine the query plan + PostgreSQL has chosen for a prepared + statement, use EXPLAIN EXECUTE. + + + + For more information on query planning and the statistics collected + by PostgreSQL for that purpose, see + the + documentation. + + + + + Compatibility + + + The SQL standard includes a PREPARE statement, + but it is only for use in embedded SQL. This version of the + PREPARE statement also uses a somewhat different + syntax. + diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index cd666c8216..591542ac1e 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -1,5 +1,5 @@ @@ -8,124 +8,31 @@ PostgreSQL documentation REINDEX SQL - Language Statements + - - REINDEX - - - rebuild corrupted indexes - + REINDEX + rebuild indexes + - - 2000-03-30 - - + REINDEX { DATABASE | TABLE | INDEX } name [ FORCE ] - - - - - 2000-03-30 - - - Inputs - - - - - - DATABASE - - - Recreate all system indexes of a specified database. Indexes on - user tables are not included. This form of REINDEX can - only be used in standalone mode (see below). - - - - - TABLE - - - Recreate all indexes of a specified table. - - - - - INDEX - - - Recreate a specified index. - - - - - name - - - The name of the specific database/table/index to be reindexed. - Table and index names may be schema-qualified. - - - - - FORCE - - - Force rebuild of system indexes. Without this keyword - REINDEX skips system indexes that are not marked invalid. - FORCE is irrelevant for REINDEX INDEX, or when reindexing - user indexes. - - - - - - - - - - 2000-03-30 - - - Outputs - - - - - - -REINDEX - - - - Message returned if the table is successfully reindexed. - - - - - - + - - - 2000-03-30 - - - Description - + + Description + REINDEX rebuilds an index based on the data stored in the table, replacing the old copy of the index. There are two main reasons to use REINDEX: - + An index has become corrupted, and no longer contains valid - data. Although in theory this should never be necessary, in + data. Although in theory this should never happen, in practice indexes may become corrupted due to software bugs or hardware failures. REINDEX provides a recovery method. @@ -135,146 +42,161 @@ REINDEX The index in question contains a lot of dead index pages that - are not being reclaimed. This can occur with B+-tree indexes + are not being reclaimed. This can occur with B-tree indexes in PostgreSQL under certain access patterns. REINDEX provides a way to reduce the space consumption of the index by writing a new version of the index without the dead pages. See - for more information. The rest of this reference page - mostly discusses how to use REINDEX to - recover from index corruption. + for more information. - + - If you suspect corruption of an index on a user table, you can - simply rebuild that index, or all indexes on the table, using - REINDEX INDEX or REINDEX TABLE. + If you suspect corruption of an index on a user table, you can + simply rebuild that index, or all indexes on the table, using + REINDEX INDEX or REINDEX + TABLE. Another approach to dealing with a corrupted + user-table index is just to drop and recreate it. This may in fact + be preferable if you would like to maintain some semblance of + normal operation on the table meanwhile. REINDEX + acquires exclusive lock on the table, while CREATE + INDEX only locks out writes not reads of the table. - - - Another approach to dealing with a corrupted user-table index is - just to drop and recreate it. This may in fact be preferable if - you would like to maintain some semblance of normal operation on - the table meanwhile. REINDEX acquires exclusive lock - on the table, while CREATE INDEX only locks out writes - not reads of the table. - - - - Things are more difficult if you need to recover from corruption of an - index on a system table. In this case it's important for the backend - doing the recovery to not have used any of the suspect indexes itself. - (Indeed, in this sort of scenario you may find that backends are - crashing immediately at start-up, due to reliance on the corrupted - indexes.) To recover safely, the postmaster must be shut down and a - stand-alone PostgreSQL backend must be - started instead, giving it - the command-line options -O and -P (these options allow system table - modifications and prevent use of system indexes, respectively). Then - issue REINDEX DATABASE, REINDEX TABLE, - REINDEX INDEX, or depending on how much you want to reconstruct. - If in doubt, use REINDEX DATABASE FORCE to force reconstruction - of all system indexes in the database. Then quit the standalone backend - and restart the postmaster. + Things are more difficult if you need to recover from corruption of + an index on a system table. In this case it's important for the + system to not have used any of the suspect indexes itself. + (Indeed, in this sort of scenario you may find that server + processes are crashing immediately at start-up, due to reliance on + the corrupted indexes.) To recover safely, the server must be shut + down and a stand-alone PostgreSQL server + must be started instead with the command-line options + and . (These options allow + system table modifications and prevent use of system indexes, + respectively.) Then, REINDEX DATABASE, + REINDEX TABLE, or REINDEX INDEX can be + issued, depending on how much you want to reconstruct. If in + doubt, use REINDEX DATABASE FORCE to force + reconstruction of all system indexes in the database. Then quit + the standalone server session and restart the real server. - Since this is likely the only situation when most people will ever use - a standalone backend, some usage notes might be in order: + See the reference page for more + information about how to interact with the stand-alone server + interface. + + + + + Parameters - + + + DATABASE - Start the backend with a command like - -postgres -D $PGDATA -O -P my_database - - Provide the correct path to the database area with + + + TABLE - You can issue any SQL command, not only REINDEX. + Recreate all indexes of a specified table. + + + INDEX - Be aware that the standalone backend treats newline as the command - entry terminator; there is no intelligence about semicolons, - as there is in psql. To continue a command - across multiple lines, you must type backslash just before each - newline except the last one. - Also, you won't have any of the conveniences of command-line editing - (no command history, for example). + Recreate a specified index. + + + name - To quit the backend, type EOF (ControlD, usually). + The name of the specific database, table, or index to be + reindexed. Table and index names may be schema-qualified. + - + + FORCE + + + Force rebuild of system indexes. Without this key word, + REINDEX skips system indexes that are not marked + invalid. FORCE is irrelevant for REINDEX + INDEX or when reindexing user indexes. + + + + + + + + Diagnostics - See the reference page for more information. - + + + REINDEX + + + Message returned if the indexes were successfully recreated. + + + + - - - Usage - + + Examples + - Recreate the indexes on the table mytable: + Recreate the indexes on the table my_table: - - REINDEX TABLE mytable; - + +REINDEX TABLE my_table; + Rebuild a single index: - - REINDEX INDEX my_index; - + +REINDEX INDEX my_index; + - Rebuild all system indexes (this will only work in a standalone backend): + Rebuild all system indexes (this will only work in a stand-alone + server session): - - REINDEX DATABASE my_database FORCE; - + +REINDEX DATABASE my_database FORCE; + - - - Compatibility - - - - - 2000-03-30 - - - SQL92 - - - There is no REINDEX in SQL92. - - + + Compatibility + + + There is no REINDEX command in the SQL standard. + diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index e2ec87d5e7..22cb395a75 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -1,5 +1,5 @@ @@ -53,19 +53,19 @@ REVOKE [ GRANT OPTION FOR ] Description - REVOKE allows the creator of an object to revoke - previously granted permissions from one or more users or groups of users. - The key word PUBLIC refers to the implicitly defined - group of all users. + The REVOKE command revokes previously granted + privileges from one or more users or groups of users. The key word + PUBLIC refers to the implicitly defined group of + all users. Note that any particular user will have the sum of privileges granted directly to him, privileges granted to any group he is presently a member of, and privileges granted to - PUBLIC. Thus, for example, revoking SELECT privilege + PUBLIC. Thus, for example, revoking SELECT privilege from PUBLIC does not necessarily mean that all users - have lost SELECT privilege on the object: those who have it granted + have lost SELECT privilege on the object: those who have it granted directly or via a group will still have it. @@ -138,15 +138,12 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel; Compatibility - - SQL92 - The compatibility notes of the command apply analogously to REVOKE. The syntax summary is: -REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES } +REVOKE [ GRANT OPTION FOR ] privileges ON object [ ( column [, ...] ) ] FROM { PUBLIC | username [, ...] } { RESTRICT | CASCADE } @@ -154,7 +151,6 @@ REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES } One of RESTRICT or CASCADE is required. - diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index 2f14ead684..dc5b063c49 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -1,5 +1,5 @@ @@ -8,129 +8,95 @@ PostgreSQL documentation ROLLBACK SQL - Language Statements + - - ROLLBACK - - - abort the current transaction - + ROLLBACK + abort the current transaction + - - 1999-07-20 - - + ROLLBACK [ WORK | TRANSACTION ] - - - - - 1998-09-24 - - - Inputs - - - None. - - - - - - 1998-09-24 - - - Outputs - - - - - - -ROLLBACK - - - - Message returned if successful. - - - - - - -WARNING: ROLLBACK: no transaction in progress - - - - If there is not any transaction currently in progress. - - - - - - + - - - 1998-09-24 - - - Description - + + Description ROLLBACK rolls back the current transaction and causes all the updates made by the transaction to be discarded. + + + + Parameters - - - 1998-09-24 - - - Notes - - - Use - to successfully terminate a transaction. - is a - synonym for ROLLBACK. - - + + + WORK + TRANSACTION + + + Optional key words. They have no effect. + + + + - - - Usage - + + Diagnostics + + + + ROLLBACK + + + Message returned if successful. + + + + + + WARNING: ROLLBACK: no transaction in progress + + + If there is not any transaction currently in progress. + + + + + + + + Notes + - To abort all changes: + Use to + successfully terminate a transaction. + + - -ROLLBACK WORK; - + + Examples + + + To abort all changes: + +ROLLBACK; + - - - Compatibility - + + Compatibility - - - 1998-09-24 - - - SQL92 - - - SQL92 only specifies the two forms ROLLBACK - and ROLLBACK WORK. Otherwise full compatibility. - - + + The SQL standard only specifies the two forms + ROLLBACK and ROLLBACK + WORK. Otherwise, this command is fully conforming. + diff --git a/doc/src/sgml/ref/start_transaction.sgml b/doc/src/sgml/ref/start_transaction.sgml index 087a0df177..5b9abefddd 100644 --- a/doc/src/sgml/ref/start_transaction.sgml +++ b/doc/src/sgml/ref/start_transaction.sgml @@ -1,13 +1,9 @@ - - 2002-07-26 - - START TRANSACTION SQL - Language Statements @@ -19,58 +15,9 @@ PostgreSQL documentation - + START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ] - - - - - 1998-09-27 - - - Inputs - - - - None. - - - - - - 1998-09-27 - - - Outputs - - - - - - - -START TRANSACTION - - - - Message returned if successful. - - - - - -WARNING: BEGIN: already a transaction in progress - - - - If there is already a transaction in progress when the - command is issued. - - - - - - + @@ -84,15 +31,50 @@ WARNING: BEGIN: already a transaction in progress respects, the behavior of this command is identical to the command. + + + + Parameters + + See under about the meaning of the + parameters. + + + + + Diagnostics + + + + START TRANSACTION + + + Message returned if successful. + + + + + + WARNING: BEGIN: already a transaction in progress + + + Message returned if there was already a transaction in progress + when the command was issued. + + + + - + Compatibility - SQL99; but see also the compatibility section of . + This command conforms to the SQL standard; but see also the + compatibility section of . diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index e8691bc4ea..b5b9d84ddc 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -1,5 +1,5 @@ @@ -8,76 +8,21 @@ PostgreSQL documentation TRUNCATE SQL - Language Statements + - - TRUNCATE - - - empty a table - + TRUNCATE + empty a table + - - 1999-07-20 - - + TRUNCATE [ TABLE ] name - - - - - 1998-09-08 - - - Inputs - - - - - - name - - - The name (optionally schema-qualified) of the table to be truncated. - - - - - - - - - - 1998-09-08 - - - Outputs - - - - - - -TRUNCATE TABLE - - - - Message returned if the table is successfully truncated. - - - - - - + - - - 1998-09-08 - - - Description - + + Description + TRUNCATE quickly removes all rows from a table. It has the same effect as an unqualified @@ -85,36 +30,55 @@ TRUNCATE TABLE table it is faster. This is most useful on large tables. + + + Parameter + + + + name + + + The name (optionally schema-qualified) of the table to be truncated. + + + + + + + + Diagnostics + + + + TRUNCATE TABLE + + + Message returned if the table was successfully truncated. + + + + + + + + Examples - - - Usage - Truncate the table bigtable: - + TRUNCATE TABLE bigtable; - + - - - Compatibility - - - - - 1998-09-08 - - - SQL92 - - - There is no TRUNCATE in SQL92. - - + + Compatibility + + + There is no TRUNCATE command in the SQL standard. + diff --git a/doc/src/sgml/ref/unlisten.sgml b/doc/src/sgml/ref/unlisten.sgml index 599b6bfcf2..4c3799177b 100644 --- a/doc/src/sgml/ref/unlisten.sgml +++ b/doc/src/sgml/ref/unlisten.sgml @@ -1,5 +1,5 @@ @@ -8,93 +8,30 @@ PostgreSQL documentation UNLISTEN SQL - Language Statements + - - UNLISTEN - - - stop listening for a notification - + UNLISTEN + stop listening for a notification + - - 1998-10-19 - - -UNLISTEN { notifyname | * } - - - - - 1998-10-19 - - - Inputs - - - - - - notifyname - - - Name of previously registered notify condition. - - - - - * - - - All current listen registrations for this backend are cleared. - - - - - - - - - - 1998-10-19 - - - Outputs - - - - - - -UNLISTEN - - - - Acknowledgment that statement has executed. - - - - - - + +UNLISTEN { name | * } + - - - 1998-10-19 - - - Description - + + Description - UNLISTEN - is used to remove an existing NOTIFY registration. - UNLISTEN cancels any existing registration of the current - PostgreSQL session as a listener on the notify - condition notifyname. - The special condition wildcard * cancels all listener registrations - for the current session. + UNLISTEN is used to remove an existing + registration for NOTIFY events. + UNLISTEN cancels any existing registration of + the current PostgreSQL session as a + listener on the notification name. The special wildcard + * cancels all listener registrations for the + current session. @@ -103,41 +40,69 @@ UNLISTEN { notifyname | * } discussion of the use of LISTEN and NOTIFY. + + + + Parameters + + + + name + + + Name of a notification (any identifier). + + + + + + * + + + All current listen registrations for this session are cleared. + + + + + + + + Diagnostics + + + + UNLISTEN + + + Message returned when the command has executed. + + + + + + + + Notes + + + You unlisten something you were not listening for; no warning or error will appear. + - - - 1998-10-19 - - - Notes - - - notifyname - need not be a valid class name but can be any string valid - as a name up to 64 characters long. - - - The backend does not complain if you unlisten something you were not - listening for. - Each backend will automatically execute UNLISTEN * when - exiting. - - + + At the end of each session, UNLISTEN * ist + automatically executed. + - - - Usage - + + Examples - To subscribe to an existing registration: + To make a registration: LISTEN virtual; -LISTEN NOTIFY virtual; -NOTIFY Asynchronous NOTIFY 'virtual' from backend with pid '8448' received @@ -148,30 +113,18 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received UNLISTEN virtual; -UNLISTEN NOTIFY virtual; -NOTIFY --- notice no NOTIFY event is received +-- no NOTIFY event is received - - - Compatibility - - - - - 1998-10-19 - - - SQL92 - - - There is no UNLISTEN in SQL92. - - + + Compatibility + + + There is no UNLISTEN command in the SQL standard. + diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 3825be5bc1..af7d8cce30 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,5 +1,5 @@ @@ -8,204 +8,136 @@ PostgreSQL documentation UPDATE SQL - Language Statements + - - UPDATE - - - update rows of a table - + UPDATE + update rows of a table + - - 1999-07-20 - - -UPDATE [ ONLY ] table SET col = expression [, ...] + +UPDATE [ ONLY ] table SET column = expression [, ...] [ FROM fromlist ] [ WHERE condition ] - - - - - 1998-09-24 - - - Inputs - - - - - - table - - - The name (optionally schema-qualified) of an existing table. If - ONLY is specified, only that table is updated. 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 - - - The name of a column in table. - - - - - expression - - - A valid expression or value to assign to column. - - - - - fromlist - - - A PostgreSQL - non-standard extension to allow columns - from other tables to appear in the WHERE condition. - - - - - condition - - - Refer to the SELECT statement for a further description - of the WHERE clause. - - - - - - - - - - 1998-09-24 - - - Outputs - - - - - - -UPDATE # - - - - Message returned if successful. - The # - means the number of rows updated. - If # - is 0 no rows are updated. - - - - - - + - - - 1998-09-24 - - - Description - - - UPDATE changes the values of the columns specified for - all rows which satisfy condition. Only the columns - to be modified need appear as columns in the statement. - + + Description - Array references use the same syntax found in - . - That is, either single array elements, a range of array - elements or the entire array may be replaced with a single - query. + UPDATE changes the values of the specified + columns in all rows that satisfy the condition. Only the columns to + be modified need appear as columns in the statement. - You must have write access to the table in order to modify - it, as well as read access to any table whose values are - mentioned in the WHERE condition. + By default, UPDATE will update rows in the + specified table and all its subtables. If you wish to only update + the specific table mentioned, you must use the ONLY + clause. - By default UPDATE will update tuples in the table specified - and all its sub-tables. If you wish to only update the - specific table mentioned, you should use the ONLY clause. + You must have the UPDATE privilege on the table + to update it, as well as the SELECT + privilege to any table whose values are read in the condition. - - - Usage - + + Parameters + + + + table + + + The name (optionally schema-qualified) of the table to update. + + + + + + column + + + The name of a column in table. + + + + + + expression + + + An expression or value to assign to the column. + + + + + + fromlist + + + A list of table expressions, allowing columns from other tables + to appear in the WHERE condition. + + + + + + condition + + + A value expression that returns a value of type + boolean that determines the rows which are to be + updated. + + + + + + + + Diagnostics + + + + UPDATE count + + + Message returned if successful. The value count is the number of rows + updated. If count + is 0, no rows were updated. + + + + + + + + Examples - Change word Drama with Dramatic on column kind: + Change the word Drama to Dramatic in the + column kind of the table films: -UPDATE films -SET kind = 'Dramatic' -WHERE kind = 'Drama'; -SELECT * -FROM films -WHERE kind = 'Dramatic' OR kind = 'Drama'; - - code | title | did | date_prod | kind | len --------+---------------+-----+------------+----------+------- - BL101 | The Third Man | 101 | 1949-12-23 | Dramatic | 01:44 - P_302 | Becket | 103 | 1964-02-03 | Dramatic | 02:28 - M_401 | War and Peace | 104 | 1967-02-12 | Dramatic | 05:57 - T_601 | Yojimbo | 106 | 1961-06-16 | Dramatic | 01:50 - DA101 | Das Boot | 110 | 1981-11-11 | Dramatic | 02:29 +UPDATE filme SET kind = 'Dramatic' WHERE kind = 'Drama'; - - - Compatibility - - - - - 1998-09-24 - - - SQL92 - - - SQL92 defines a different syntax for - the positioned UPDATE statement: - - -UPDATE table SET column = expression [, ...] - WHERE CURRENT OF cursor - - - where cursor - identifies an open cursor. - - + + Compatibility + + + This command conforms to the SQL standard. The + FROM clause is a PostgreSQL extension. + diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index c55f23945e..3f532c0244 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -1,5 +1,5 @@ @@ -8,161 +8,26 @@ PostgreSQL documentation VACUUM SQL - Language Statements + - - VACUUM - - - garbage-collect and optionally analyze a database - + VACUUM + garbage-collect and optionally analyze a database + - - 2001-08-26 - - + VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ table ] VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ table [ (column [, ...] ) ] ] - - - - - 2001-07-10 - - - Inputs - - - - - - FULL - - - Selects full vacuum, which may reclaim more space, - but takes much longer and exclusively locks the table. - - - - - FREEZE - - - Selects aggressive freezing of tuples. - - - - - VERBOSE - - - Prints a detailed vacuum activity report for each table. - - - - - ANALYZE - - - Updates statistics used by the optimizer to - determine the most efficient way to execute a query. - - - - - table - - - The name (optionally schema-qualified) of a specific table to - vacuum. Defaults to all tables in the current database. - - - - - column - - - The name of a specific column to analyze. Defaults to all columns. - - - - - - - - - - 1998-10-04 - - - Outputs - - - - - - -VACUUM - - - - The command is complete. - - - - - - -INFO: --Relation table-- - - - - The report header for table. - - - - - - -INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0; - Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188; - Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74. - Elapsed 0/0 sec. - - - - The analysis for table itself. - - - - - - -INFO: Index index: Pages 28; - Tuples 1000: Deleted 3000. Elapsed 0/0 sec. - - - - The analysis for an index on the target table. - - - - - - + - - - 2001-07-10 - - - Description - + + Description + VACUUM reclaims storage occupied by deleted tuples. In normal PostgreSQL operation, tuples that - are deleted or obsoleted by UPDATE are not physically removed from + are deleted or obsoleted by an update are not physically removed from their table; they remain present until a VACUUM is done. Therefore it's necessary to do VACUUM periodically, especially on frequently-updated tables. @@ -201,32 +66,137 @@ INFO: Index index: Pages 28; are no other open transactions in the same database, then it is guaranteed that all tuples in the database are frozen and will not be subject to transaction ID wraparound problems, no matter how long the - database is left un-vacuumed. + database is left unvacuumed. FREEZE is not recommended for routine use. Its only intended usage is in connection with preparation of user-defined template databases, or other databases that are completely read-only and will not receive routine maintenance VACUUM operations. See for details. + + + + Parameters + + + + FULL + + + Selects full vacuum, which may reclaim more + space, but takes much longer and exclusively locks the table. + + + + + + FREEZE + + + Selects aggressive freezing of tuples. + + + + + + VERBOSE + + + Prints a detailed vacuum activity report for each table. + + + + + + ANALYZE + + + Updates statistics used by the planner to determine the most + efficient way to execute a query. + + + + + + table + + + The name (optionally schema-qualified) of a specific table to + vacuum. Defaults to all tables in the current database. + + + - - - 2001-07-10 - - - Notes - + + column + + + The name of a specific column to analyze. Defaults to all columns. + + + + + + + + Diagnostics + + + + VACUUM + + + The command is complete. + + + + + + INFO: --Relation table-- + + + The report header for table. + + + + + + INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0; + Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188; + Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74. + Elapsed 0/0 sec. + + + The analysis for table itself. + + + + + + INFO: Index index: Pages 28; + Tuples 1000: Deleted 3000. Elapsed 0/0 sec. + + + The analysis for an index on the target table. + + + + + + + + Notes We recommend that active production databases be - VACUUM-ed frequently (at least nightly), in order to + vacuumed frequently (at least nightly), in order to remove expired rows. After adding or deleting a large number - of records, it may be a good idea to issue a VACUUM + of rows, it may be a good idea to issue a VACUUM ANALYZE command for the affected table. This will update the system catalogs with the results of all recent changes, and allow the - PostgreSQL query optimizer to make better - choices in planning user queries. + PostgreSQL query planner to make better + choices in planning queries. @@ -236,20 +206,17 @@ INFO: Index index: Pages 28; to occupy less disk space. VACUUM FULL will usually shrink the table more than a plain VACUUM would. - - - - - Usage - + + Examples + The following is an example from running VACUUM on a table in the regression database: - -regression=> VACUUM VERBOSE ANALYZE onek; + +=> VACUUM VERBOSE ANALYZE onek; INFO: --Relation onek-- INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000. CPU 0.00s/0.11u sec elapsed 0.12 sec. @@ -265,26 +232,16 @@ INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0. Total CPU 0.05s/0.45u sec elapsed 0.59 sec. INFO: Analyzing onek VACUUM - + - - - Compatibility - - - - - 1998-10-04 - - - SQL92 - - - There is no VACUUM statement in SQL92. - - + + Compatibility + + + There is no VACUUM statement in the SQL standard. +