From 2a5b6a7c9bf40b0983e78d6027eba19b34cb90bd Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 11 Sep 2003 21:42:20 +0000 Subject: [PATCH] This patch fixes a few missed GUC variables that were still upper case, makes a few more small improvements to runtime.sgml, and makes some SGML conventions more consistent. Neil Conway --- doc/src/sgml/docguide.sgml | 11 +- doc/src/sgml/ecpg.sgml | 28 ++--- doc/src/sgml/extend.sgml | 20 ++-- doc/src/sgml/features.sgml | 13 ++- doc/src/sgml/history.sgml | 6 +- doc/src/sgml/indices.sgml | 12 +- doc/src/sgml/information_schema.sgml | 152 +++++++++++++------------ doc/src/sgml/installation.sgml | 17 +-- doc/src/sgml/intro.sgml | 43 +++---- doc/src/sgml/libpq.sgml | 14 ++- doc/src/sgml/plpgsql.sgml | 15 ++- doc/src/sgml/protocol.sgml | 8 +- doc/src/sgml/ref/copy.sgml | 8 +- doc/src/sgml/ref/create_function.sgml | 4 +- doc/src/sgml/ref/create_index.sgml | 6 +- doc/src/sgml/ref/declare.sgml | 8 +- doc/src/sgml/ref/end.sgml | 8 +- doc/src/sgml/ref/grant.sgml | 6 +- doc/src/sgml/ref/load.sgml | 4 +- doc/src/sgml/ref/lock.sgml | 4 +- doc/src/sgml/ref/pg_dump.sgml | 4 +- doc/src/sgml/ref/pg_restore.sgml | 4 +- doc/src/sgml/ref/reindex.sgml | 13 ++- doc/src/sgml/ref/select.sgml | 21 ++-- doc/src/sgml/ref/set_constraints.sgml | 7 +- doc/src/sgml/ref/set_session_auth.sgml | 6 +- doc/src/sgml/ref/set_transaction.sgml | 4 +- doc/src/sgml/ref/update.sgml | 5 +- doc/src/sgml/release.sgml | 6 +- doc/src/sgml/rules.sgml | 15 +-- doc/src/sgml/runtime.sgml | 105 +++++++++-------- doc/src/sgml/xfunc.sgml | 54 ++++----- 32 files changed, 336 insertions(+), 295 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index a1199d66ae..892a8ac72a 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ - + Documentation @@ -497,8 +497,9 @@ CATALOG "docbook-dsssl--1.xx/catalog Before you can build the documentation you need to run the configure script as you would when building - the PostgreSQL programs themselves. Check the output near the end - of the run, it should look something like this: + the PostgreSQL programs themselves. + Check the output near the end of the run, it should look something + like this: checking for onsgmls... onsgmls @@ -640,7 +641,7 @@ gmake man.tar.gz Print Output via <acronym>RTF</acronym> - You can also create a printable version of the PostgreSQL + You can also create a printable version of the PostgreSQL documentation by converting it to RTF and applying minor formatting corrections using an office suite. Depending on the capabilities of the particular office suite, you @@ -651,7 +652,7 @@ gmake man.tar.gz - It appears that current versions of the PostgreSQL documentation + It appears that current versions of the PostgreSQL documentation trigger some bug in or exceed the size limit of OpenJade. If the build process of the RTF version hangs for a long time and the output file still has size 0, then you may have diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index ae321f5190..d9856c6d55 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,5 +1,5 @@ @@ -1153,10 +1153,11 @@ struct condition. A successful state is indicated by the code 00000. Further information about the codes can be found XXX. The SQLSTATE codes are for the - most part defined in the SQL standard. The PostgreSQL server - natively supports SQLSTATE error codes; - therefore a high degree of consistency can be achieved by using - this error code scheme throughout all applications. + most part defined in the SQL standard. The + PostgreSQL server natively supports + SQLSTATE error codes; therefore a high degree + of consistency can be achieved by using this error code scheme + throughout all applications. @@ -1168,11 +1169,11 @@ struct affected zero rows, and no specific negative values. Therefore, this scheme can only achieve poor portability and does not have a hierarchical code assignment. Historically, the embedded SQL - processor for PostgreSQL has assigned some specific - SQLCODE values for its use, which are listed - below with their numeric value and their symbolic name. Remember - that these are not portable to other SQL implementations. To - simplify the porting of applications to the + processor for PostgreSQL has assigned + some specific SQLCODE values for its use, which + are listed below with their numeric value and their symbolic name. + Remember that these are not portable to other SQL implementations. + To simplify the porting of applications to the SQLSTATE scheme, the corresponding SQLSTATE is also listed. There is, however, no one-to-one or one-to-many mapping between the two schemes (indeed @@ -1291,9 +1292,10 @@ struct -208 (ECPG_EMPTY) - The statement sent to the PostgreSQL server was empty. (This - cannot normally happen in an embedded SQL program, so it may - point to an internal error.) (SQLSTATE YE002) + The statement sent to the PostgreSQL + server was empty. (This cannot normally happen in an embedded + SQL program, so it may point to an internal error.) (SQLSTATE + YE002) diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 412d4b19bb..1348d59d8f 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1,5 +1,5 @@ @@ -69,14 +69,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.24 2003/08/31 17:32:18 pete - The PostgreSQL server can moreover incorporate user-written code into - itself through dynamic loading. That is, the user can - specify an object code file (e.g., a shared library) that implements a new type or function, - and PostgreSQL will load it as required. Code written - in SQL is even more trivial to add to the server. - This ability to modify its operation on the fly makes - PostgreSQL uniquely suited for rapid prototyping of new - applications and storage structures. + The PostgreSQL server can moreover + incorporate user-written code into itself through dynamic loading. + That is, the user can specify an object code file (e.g., a shared + library) that implements a new type or function, and + PostgreSQL will load it as required. + Code written in SQL is even more trivial to add + to the server. This ability to modify its operation on the + fly makes PostgreSQL uniquely + suited for rapid prototyping of new applications and storage + structures. diff --git a/doc/src/sgml/features.sgml b/doc/src/sgml/features.sgml index 74151f7d82..4056d770f1 100644 --- a/doc/src/sgml/features.sgml +++ b/doc/src/sgml/features.sgml @@ -1,5 +1,5 @@ @@ -63,11 +63,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.18 2003/03/13 01:30:28 pe In the following two sections, we provide a list of those features that PostgreSQL supports, followed by a list of the features defined in SQL99 which are not yet supported in - PostgreSQL. Both of these lists are approximate: There may be minor - details that are nonconforming for a feature that is listed as - supported, and large parts of an unsupported feature may in fact be - implemented. The main body of the documentation always contains the - most accurate information about what does and does not work. + PostgreSQL. Both of these lists are + approximate: There may be minor details that are nonconforming for a + feature that is listed as supported, and large parts of an + unsupported feature may in fact be implemented. The main body of + the documentation always contains the most accurate information + about what does and does not work. diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml index 07b96ce6f4..f014933ac1 100644 --- a/doc/src/sgml/history.sgml +++ b/doc/src/sgml/history.sgml @@ -1,5 +1,5 @@ @@ -206,8 +206,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.21 2003/09/08 23:02:28 pet - Details about what has happened in PostgreSQL since then can be - found in . + Details about what has happened in PostgreSQL since + then can be found in . diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 50f934468a..dc640b91ed 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -1,4 +1,4 @@ - + Indexes @@ -194,11 +194,11 @@ CREATE INDEX name ON table - Testing has shown PostgreSQL's hash indexes to be similar or slower - than B-tree indexes, and the index size and build time for hash - indexes is much worse. Hash indexes also suffer poor performance - under high concurrency. For these reasons, hash index use is - presently discouraged. + Testing has shown PostgreSQL's hash + indexes to be similar or slower than B-tree indexes, and the + index size and build time for hash indexes is much worse. Hash + indexes also suffer poor performance under high concurrency. For + these reasons, hash index use is presently discouraged. diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index fb04ea8825..16e370777a 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -1,4 +1,4 @@ - + The Information Schema @@ -12,11 +12,13 @@ information about the objects defined in the current database. The information schema is defined in the SQL standard and can therefore be expected to be portable and remain stable --- unlike the system - catalogs, which are specific to PostgreSQL and are modelled after + catalogs, which are specific to + PostgreSQL and are modelled after implementation concerns. The information schema views do not, - however, contain information about PostgreSQL-specific features; to - inquire about those you need to query the system catalogs or other - PostgreSQL-specific views. + however, contain information about + PostgreSQL-specific features; to inquire + about those you need to query the system catalogs or other + PostgreSQL-specific views. @@ -319,12 +321,13 @@ - In PostgreSQL, you can only grant privileges on entire tables, not - individual columns. Therefore, this view contains the same - information as table_privileges, just - represented through one row for each column in each appropriate - table, but it only convers privilege types where column granularity - is possible: SELECT, INSERT, + In PostgreSQL, you can only grant + privileges on entire tables, not individual columns. Therefore, + this view contains the same information as + table_privileges, just represented through one + row for each column in each appropriate table, but it only convers + privilege types where column granularity is possible: + SELECT, INSERT, UPDATE, REFERENCES. If you want to make your applications fit for possible future developements, it is generally the right choice to use this view @@ -404,8 +407,8 @@ Note that the column grantee makes no distinction between users and groups. If you have users and groups with the same name, there is unfortunately no way to distinguish - them. A future version of PostgreSQL will possibly prohibit having - users and groups with the same name. + them. A future version of PostgreSQL + will possibly prohibit having users and groups with the same name. @@ -415,9 +418,9 @@ The view column_udt_usage identifies all columns that use data types owned by the current user. Note that in - PostgreSQL, built-in data types behave like user-defined types, so - they are included here as well. See also for details. + PostgreSQL, built-in data types behave + like user-defined types, so they are included here as well. See + also for details. @@ -595,7 +598,7 @@ If data_type identifies a character type, the maximum possible length in octets (bytes) of a datum (this - should not be of concern to PostgreSQL users); null for all + should not be of concern to PostgreSQL users); null for all other data types. @@ -800,24 +803,26 @@ Since data types can be defined in a variety of ways in SQL, and - PostgreSQL contains additional ways to define data types, their - representation in the information schema can be somewhat difficult. - The column data_type is supposed to identify the - underlying built-in type of the column. In PostgreSQL, this means - that the type is defined in the system catalog schema + PostgreSQL contains additional ways to + define data types, their representation in the information schema + can be somewhat difficult. The column data_type + is supposed to identify the underlying built-in type of the column. + In PostgreSQL, this means that the type + is defined in the system catalog schema pg_catalog. This column may be useful if the application can handle the well-known built-in types specially (for example, format the numeric types differently or use the data in the precision columns). The columns udt_name, udt_schema, and udt_catalog always identify the underlying data type of the column, even if the - column is based on a domain. (Since PostgreSQL treats built-in - types like user-defined types, built-in types appear here as well. - This is an extension of the SQL standard.) These columns should be - used if an application wants to process data differently according - to the type, because in that case it wouldn't matter if the column - is really based on a domain. If the column is based on a domain, - the identity of the domain is stored in the columns + column is based on a domain. (Since + PostgreSQL treats built-in types like + user-defined types, built-in types appear here as well. This is an + extension of the SQL standard.) These columns should be used if an + application wants to process data differently according to the + type, because in that case it wouldn't matter if the column is + really based on a domain. If the column is based on a domain, the + identity of the domain is stored in the columns domain_name, domain_schema, and domain_catalog. If you want to pair up columns with their associated data types and treat domains as @@ -1141,8 +1146,8 @@ The view domain_udt_usage identifies all columns that use data types owned by the current user. Note that in - PostgreSQL, built-in data types behave like user-defined types, so - they are included here as well. + PostgreSQL, built-in data types behave + like user-defined types, so they are included here as well.
@@ -1266,7 +1271,8 @@ If the domain has a character type, the maximum possible length in octets (bytes) of a datum (this should not be of concern to - PostgreSQL users); null for all other data types. + PostgreSQL users); null for all + other data types. @@ -2416,11 +2422,11 @@ ORDER BY c.ordinal_position; The view role_usage_grants is meant to identify USAGE privileges granted on various kinds of objects to a group that the current user is a member of. In - PostgreSQL, this currently only applies to domains, and since - domains do not have real privileges in PostgreSQL, this view is - empty. Futher information can be found under - usage_privileges. In the future, this view may - contain more useful information. + PostgreSQL, this currently only applies + to domains, and since domains do not have real privileges in + PostgreSQL, this view is empty. Futher + information can be found under usage_privileges. + In the future, this view may contain more useful information.
@@ -2582,8 +2588,8 @@ ORDER BY c.ordinal_position; Note that the column grantee makes no distinction between users and groups. If you have users and groups with the same name, there is unfortunately no way to distinguish - them. A future version of PostgreSQL will possibly prohibit having - users and groups with the same name. + them. A future version of PostgreSQL + will possibly prohibit having users and groups with the same name. @@ -2874,8 +2880,9 @@ ORDER BY c.ordinal_position; not the owner of the function). (According to the SQL standard, this column is only applicable if routine_body is SQL, but - in PostgreSQL it will contain whatever source text was - specified when the function was created.) + in PostgreSQL it will contain + whatever source text was specified when the function was + created.) @@ -3082,9 +3089,9 @@ ORDER BY c.ordinal_position; The table sql_features contains information about which formal features defined in the SQL standard are - supported by PostgreSQL. This is the same information that is - presented in . There you can also find - some additional background information. + supported by PostgreSQL. This is the + same information that is presented in . + There you can also find some additional background information.
@@ -3226,9 +3233,10 @@ ORDER BY c.ordinal_position; The table sql_languages contains one row for - each SQL language binding that is supported by PostgreSQL. - PostgreSQL supports direct SQL and embedded SQL in C; that is all - you will learn from this table. + each SQL language binding that is supported by + PostgreSQL. + PostgreSQL supports direct SQL and + embedded SQL in C; that is all you will learn from this table.
@@ -3313,8 +3321,8 @@ ORDER BY c.ordinal_position; The table sql_packages contains information about which features packages defined in the SQL standard are - supported by PostgreSQL. Refer to for - background information on feature packages. + supported by PostgreSQL. Refer to for background information on feature packages.
@@ -3375,12 +3383,13 @@ ORDER BY c.ordinal_position; The table sql_sizing contains information about - various size limits and maximum values in PostgreSQL. This - information is primarily intended for use in the context of the - ODBC interface; users of other interfaces will probably find this - information to be of little use. For this reason, the individual - sizing items are not described here; you will find them in the - description of the ODBC interface. + various size limits and maximum values in + PostgreSQL. This information is + primarily intended for use in the context of the ODBC interface; + users of other interfaces will probably find this information to be + of little use. For this reason, the individual sizing items are + not described here; you will find them in the description of the + ODBC interface.
@@ -3657,8 +3666,8 @@ ORDER BY c.ordinal_position; Note that the column grantee makes no distinction between users and groups. If you have users and groups with the same name, there is unfortunately no way to distinguish - them. A future version of PostgreSQL will possibly prohibit having - users and groups with the same name. + them. A future version of PostgreSQL + will possibly prohibit having users and groups with the same name. @@ -3875,21 +3884,23 @@ ORDER BY c.ordinal_position;
- Triggers in PostgreSQL have two incompatibilities with the SQL - standard that affect the representation in the information schema. - First, trigger names are local to the table in PostgreSQL, rather + Triggers in PostgreSQL have two + incompatibilities with the SQL standard that affect the + representation in the information schema. First, trigger names are + local to the table in PostgreSQL, rather than independent schema objects. Therefore there may be duplicate trigger names defined in one schema, as long as they belong to different tables. (trigger_catalog and trigger_schema are really the values pertaining to the table that the trigger is defined on.) Second, triggers can - be defined to fire on multiple events in PostgreSQL (e.g., - ON INSERT OR UPDATE), whereas the SQL standard - only allows one. If a trigger is defined to fire on multiple - events, it is represented as multiple rows in the information - schema, one for each type of event. As a consequence of these two - issues, the primary key of the view triggers is - really (trigger_catalog, trigger_schema, trigger_name, + be defined to fire on multiple events in + PostgreSQL (e.g., ON INSERT OR + UPDATE), whereas the SQL standard only allows one. If a + trigger is defined to fire on multiple events, it is represented as + multiple rows in the information schema, one for each type of + event. As a consequence of these two issues, the primary key of + the view triggers is really + (trigger_catalog, trigger_schema, trigger_name, event_object_name, event_manipulation) instead of (trigger_catalog, trigger_schema, trigger_name), which is what the SQL standard specifies. Nonetheless, if you @@ -3905,9 +3916,10 @@ ORDER BY c.ordinal_position; The view usage_privileges is meant to identify USAGE privileges granted on various kinds of - objects to the current user or by the current user. In PostgreSQL, - this currently only applies to domains, and since domains do not - have real privileges in PostgreSQL, this view shows implicit + objects to the current user or by the current user. In + PostgreSQL, this currently only applies + to domains, and since domains do not have real privileges in + PostgreSQL, this view shows implicit USAGE privileges granted to PUBLIC for all domains. In the future, this view may contain more useful information. diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 576207610f..02a77afcb6 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ - + <![%standalone-include[<productname>PostgreSQL</>]]> @@ -406,13 +406,14 @@ JAVACMD=$JAVA_HOME/bin/java To make the backup, you can use the <command>pg_dumpall</command> command from the version you are currently running. For best results, however, try to use the <command>pg_dumpall</command> - command from PostgreSQL &version;, since this version contains - bug fixes and improvements over older versions. While this - advice might seem idiosyncratic since you haven't installed the - new version yet, it is advisable to follow it if you plan to - install the new version in parallel with the old version. In - that case you can complete the installation normally and transfer - the data later. This will also decrease the downtime. + command from <productname>PostgreSQL</productname> &version;, + since this version contains bug fixes and improvements over older + versions. While this advice might seem idiosyncratic since you + haven't installed the new version yet, it is advisable to follow + it if you plan to install the new version in parallel with the + old version. In that case you can complete the installation + normally and transfer the data later. This will also decrease + the downtime. </para> </step> diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index c547c7a880..038eda4805 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -1,23 +1,26 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.21 2003/09/08 23:02:28 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.22 2003/09/11 21:42:20 momjian Exp $ --> <preface id="preface"> <title>Preface - This book is the official documentation of PostgreSQL. It is being - written by the PostgreSQL developers and other volunteers in - parallel to the development of the PostgreSQL software. It - describes all the functionality that the current version of - PostgreSQL officially supports. + This book is the official documentation of + PostgreSQL. It is being written by the + PostgreSQL developers and other + volunteers in parallel to the development of the + PostgreSQL software. It describes all + the functionality that the current version of + PostgreSQL officially supports. - To make the large amount of information about PostgreSQL manageable, - this book has been organized in several parts. Each part is - targeted at a different class of users, or at users in different - stages of their PostgreSQL experience: + To make the large amount of information about + PostgreSQL manageable, this book has been + organized in several parts. Each part is targeted at a different + class of users, or at users in different stages of their + PostgreSQL experience: @@ -38,16 +41,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.21 2003/09/08 23:02:28 peter describes the installation and - administration of the server. Everyone that runs a PostgreSQL - server, be it for private use or for others, should read this - part. + administration of the server. Everyone that runs a + PostgreSQL server, be it for private + use or for others, should read this part. describes the programming - interfaces for PostgreSQL client programs. + interfaces for PostgreSQL client + programs. @@ -111,8 +115,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.21 2003/09/08 23:02:28 peter - Also, PostgreSQL can be extended by the user in many ways, for - example by adding new + Also, PostgreSQL can be extended by the + user in many ways, for example by adding new @@ -137,9 +141,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.21 2003/09/08 23:02:28 peter - And because of the liberal license, PostgreSQL can be used, - modified, and distributed by everyone free of charge for any - purpose, be it private, commercial, or academic. + And because of the liberal license, + PostgreSQL can be used, modified, and + distributed by everyone free of charge for any purpose, be it + private, commercial, or academic. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 27bb09e820..7d91fdf808 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -2049,11 +2049,13 @@ unsigned char *PQescapeBytea(const unsigned char *from, from parameter binary string in memory allocated with malloc(). This memory must be freed using PQfreemem() when the result is no longer needed. - The return string has all special characters replaced - so that they can be properly processed by the PostgreSQL string literal - parser, and the bytea input function. A terminating zero - byte is also added. The single quotes that must surround - PostgreSQL string literals are not part of the result string. + The return string has all special characters replaced so that they + can be properly processed by the + PostgreSQL string literal parser, and + the bytea input function. A terminating zero byte is + also added. The single quotes that must surround + PostgreSQL string literals are not part + of the result string. diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index d4eedf13ad..99966c1d1e 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ @@ -2056,9 +2056,10 @@ RAISE level ' for more information. + log_min_messages and + client_min_messages configuration + variables. See for more + information. @@ -2448,7 +2449,8 @@ show errors; The RETURN key word in the function prototype (not the function body) becomes - RETURNS in PostgreSQL. + RETURNS in + PostgreSQL. @@ -2805,7 +2807,8 @@ END; This section explains a few other things to watch for when porting - Oracle PL/SQL functions to PostgreSQL. + Oracle PL/SQL functions to + PostgreSQL. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 09768a46cf..1819a33c07 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,10 +1,10 @@ - + Frontend/Backend Protocol - PostgreSQL uses a message-based protocol + PostgreSQL uses a message-based protocol for communication between frontends and backends (clients and servers). The protocol is supported over TCP/IP and also over Unix-domain sockets. Port number 5432 has been registered with IANA as @@ -14,7 +14,7 @@ This document describes version 3.0 of the protocol, implemented in - PostgreSQL 7.4 and later. For descriptions + PostgreSQL 7.4 and later. For descriptions of the earlier protocol versions, see previous releases of the PostgreSQL documentation. A single server can support multiple protocol versions. The initial @@ -165,7 +165,7 @@ Data of a particular datatype might be transmitted in any of several - different formats. As of PostgreSQL 7.4 + different formats. As of PostgreSQL 7.4 the only supported formats are text and binary, but the protocol makes provision for future extensions. The desired format for any value is specified by a format code. diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 24dc567acf..5df52ca36b 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -1,5 +1,5 @@ @@ -201,7 +201,7 @@ COPY table [ ( table [ ( @@ -382,7 +382,7 @@ CREATE FUNCTION add(integer, integer) RETURNS integer A CREATE FUNCTION command is defined in SQL99. - The PostgreSQL version is similar but + The PostgreSQL version is similar but not fully compatible. The attributes are not portable, neither are the different available languages. diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index 3081f68ac8..28140997f5 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -1,5 +1,5 @@ @@ -53,7 +53,7 @@ CREATE [ UNIQUE ] INDEX index_name - PostgreSQL provides the index methods + PostgreSQL provides the index methods B-tree, R-tree, hash, and GiST. The B-tree index method is an implementation of Lehman-Yao high-concurrency B-trees. The R-tree index method implements standard R-trees using Guttman's quadratic @@ -198,7 +198,7 @@ CREATE [ UNIQUE ] INDEX index_name Currently, only the B-tree and GiST index methods support multicolumn indexes. Up to 32 fields may be specified by default. (This limit can be altered when building - PostgreSQL.) Only B-tree currently + PostgreSQL.) Only B-tree currently supports unique indexes. diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 2bd6ed82af..1a3e3ccaff 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -1,5 +1,5 @@ @@ -105,9 +105,9 @@ DECLARE cursorname [ BINARY ] [ INS Indicates that data retrieved from the cursor should be unaffected by updates to the tables underlying the cursor while - the cursor exists. In PostgreSQL, all cursors are insensitive; - this key word currently has no effect and is present for - compatibility with the SQL standard. + the cursor exists. In PostgreSQL, + all cursors are insensitive; this key word currently has no + effect and is present for compatibility with the SQL standard. diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml index a56539f37b..7772184ae8 100644 --- a/doc/src/sgml/ref/end.sgml +++ b/doc/src/sgml/ref/end.sgml @@ -1,5 +1,5 @@ @@ -30,9 +30,9 @@ END [ WORK | TRANSACTION ] 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 . + to be durable if a crash occurs. It is a + PostgreSQL extension that is equivalent + to . diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index c0ee305517..d0fb343bbd 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,5 +1,5 @@ @@ -375,8 +375,8 @@ GRANT privileges The RULE privilege, and privileges on - databases, schemas, languages, and sequences are PostgreSQL - extensions. + databases, schemas, languages, and sequences are + PostgreSQL extensions. diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index c62c85f582..aef72fe646 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -1,5 +1,5 @@ @@ -50,7 +50,7 @@ LOAD 'filename' Compatibility - LOAD is a PostgreSQL + LOAD is a PostgreSQL extension. diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index 8c24cfb617..efa828954d 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -1,5 +1,5 @@ @@ -201,7 +201,7 @@ COMMIT WORK; There is no LOCK TABLE in the SQL standard, which instead uses SET TRANSACTION to specify - concurrency levels on transactions. PostgreSQL supports that too; + concurrency levels on transactions. PostgreSQL supports that too; see for details. diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 57eae7fcc9..80dd35041f 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ @@ -705,7 +705,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; The pg_dump utility first appeared in Postgres95 release 0.02. The non-plain-text output formats were introduced in - PostgreSQL release 7.1. + PostgreSQL release 7.1. diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 77d7860e4c..1600925af8 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -1,4 +1,4 @@ - + @@ -659,7 +659,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; The pg_restore utility first appeared in - PostgreSQL 7.1. + PostgreSQL 7.1. diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index b919f2c53c..29b96e462c 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -1,5 +1,5 @@ @@ -46,11 +46,12 @@ REINDEX { DATABASE | TABLE | INDEX } name The index in question contains a lot of dead index pages that - 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. + 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. diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 9bfe0e9093..f2b4c2c37c 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,5 +1,5 @@ @@ -798,10 +798,10 @@ FOR UPDATE [ OF table_name [, ...] FOR UPDATE may appear before - LIMIT for compatibility with PostgreSQL - versions before 7.3. It effectively executes after - LIMIT, however, and so that is the recommended - place to write it. + LIMIT for compatibility with + PostgreSQL versions before 7.3. It + effectively executes after LIMIT, however, and + so that is the recommended place to write it. @@ -1008,11 +1008,12 @@ SELECT d.* FROM distributors d; SELECT distributors.* FROM distributors d, distributors distributors; that he will actually get. To help detect this sort of mistake, - PostgreSQL will warn if the implicit-FROM - feature is used in a SELECT statement that also - contains an explicit FROM clause. Also, it is - possible to disable the implicit-FROM feature - by setting the ADD_MISSING_FROM parameter to false. + PostgreSQL will warn if the + implicit-FROM feature is used in a + SELECT statement that also contains an explicit + FROM clause. Also, it is possible to disable + the implicit-FROM feature by setting the + ADD_MISSING_FROM parameter to false. diff --git a/doc/src/sgml/ref/set_constraints.sgml b/doc/src/sgml/ref/set_constraints.sgml index 2a5f3ea8ea..dda6653809 100644 --- a/doc/src/sgml/ref/set_constraints.sgml +++ b/doc/src/sgml/ref/set_constraints.sgml @@ -1,4 +1,4 @@ - + SET CONSTRAINTS @@ -77,8 +77,9 @@ SET CONSTRAINTS { ALL | constraint This command complies with the behavior defined in the SQL - standard, except for the limitation that, in PostgreSQL, it only - applies to foreign-key constraints. + standard, except for the limitation that, in + PostgreSQL, it only applies to + foreign-key constraints. diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml index 1978b0bbab..41c88a9f95 100644 --- a/doc/src/sgml/ref/set_session_auth.sgml +++ b/doc/src/sgml/ref/set_session_auth.sgml @@ -1,4 +1,4 @@ - + SET SESSION AUTHORIZATION @@ -89,10 +89,10 @@ SELECT SESSION_USER, CURRENT_USER; The SQL standard allows some other expressions to appear in place of the literal username which are not - important in practice. PostgreSQL + important in practice. PostgreSQL allows identifier syntax ("username"), which SQL does not. SQL does not allow this command during a transaction; - PostgreSQL does not make this + PostgreSQL does not make this restriction because there is no reason to. The privileges necessary to execute this command are left implementation-defined by the standard. diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml index 12ebb2f61c..cbe41d7175 100644 --- a/doc/src/sgml/ref/set_transaction.sgml +++ b/doc/src/sgml/ref/set_transaction.sgml @@ -1,4 +1,4 @@ - + SET TRANSACTION @@ -122,7 +122,7 @@ SET default_transaction_isolation = 'value' Both commands are defined in the SQL standard. SERIALIZABLE is the default transaction - isolation level in the standard; in PostgreSQL the default is + isolation level in the standard; in PostgreSQL the default is ordinarily READ COMMITTED, but you can change it as described above. PostgreSQL does not provide the isolation levels READ UNCOMMITTED diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 160eb5ea18..01917b362d 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,5 +1,5 @@ @@ -164,7 +164,8 @@ UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT This command conforms to the SQL standard. The - FROM clause is a PostgreSQL extension. + FROM clause is a + PostgreSQL extension. diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index 6585e738ea..c67e93ba8d 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ @@ -10,8 +10,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.206 2003/08/27 03:35:35 mo Below is a subset of the changes that have gone into the - development branch of PostgreSQL since version 7.3. For a complete - list of changes, consult the CVS logs. + development branch of PostgreSQL since + version 7.3. For a complete list of changes, consult the CVS logs. + The Rule System @@ -8,16 +8,17 @@ - This chapter discusses the rule system in PostgreSQL. - Production rule systems are conceptually simple, but - there are many subtle points involved in actually using - them. + This chapter discusses the rule system in + PostgreSQL. Production rule systems + are conceptually simple, but there are many subtle points + involved in actually using them. Some other database systems define active database rules, which - are usually stored procedures and triggers. In PostgreSQL, these - can be implemented using functions and triggers as well. + are usually stored procedures and triggers. In + PostgreSQL, these can be implemented + using functions and triggers as well. diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 8a058ef2d5..fa222c1a06 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -797,7 +797,7 @@ SET ENABLE_SEQSCAN TO OFF; this much time, the server breaks the connection. This prevents hung clients from occupying a connection indefinitely. This option can only be set at server start or in the - postgresql.conf file. + postgresql.conf file. The default is 60. @@ -1028,9 +1028,9 @@ SET ENABLE_SEQSCAN TO OFF; - PostgreSQL procedural language libraries may be preloaded in - this way, typically by using the syntax - '$libdir/plXXX:plXXX_init' where + PostgreSQL procedural language + libraries may be preloaded in this way, typically by using the + syntax '$libdir/plXXX:plXXX_init' where XXX is pgsql, perl, tcl, or python. @@ -1228,11 +1228,11 @@ SET ENABLE_SEQSCAN TO OFF; These configuration parameters provide a crude method for influencing the query plans chosen by the query optimizer. If - the default plan chosen by the optimizer is not optimal, a - temporary solution may be found by using one of these - configuration parameters to force the optimizer to choose a - better plan. Other ways to improve the quality of the plans - chosen by the optimizer include configuring the , running ANALYZE more frequently, and increasing the @@ -1370,7 +1370,7 @@ SET ENABLE_SEQSCAN TO OFF; disk cache (that is, the portion of the kernel's disk cache that will be used for PostgreSQL data files). This is measured in disk pages, which are - normally 8192 bytes each. + normally 8192 bytes each. The default is 1000. @@ -1382,8 +1382,9 @@ SET ENABLE_SEQSCAN TO OFF; Sets the query planner's estimate of the cost of a nonsequentially fetched disk page. This is measured as a multiple of the cost of a sequential page fetch. A higher - value makes it more likely a sequential scan will be used, - a lower value makes it more likely an index scan will be used. + value makes it more likely a sequential scan will be used, a + lower value makes it more likely an index scan will be + used. The default is four. @@ -1394,7 +1395,7 @@ SET ENABLE_SEQSCAN TO OFF; Sets the query planner's estimate of the cost of processing each tuple during a query. This is measured as a fraction of - the cost of a sequential page fetch. + the cost of a sequential page fetch. The default is 0.01. @@ -1405,7 +1406,8 @@ SET ENABLE_SEQSCAN TO OFF; Sets the query planner's estimate of the cost of processing each index tuple during an index scan. This is measured as a - fraction of the cost of a sequential page fetch. + fraction of the cost of a sequential page fetch. The default + is 0.001. @@ -1416,7 +1418,7 @@ SET ENABLE_SEQSCAN TO OFF; Sets the planner's estimate of the cost of processing each operator in a WHERE clause. This is measured as a fraction of - the cost of a sequential page fetch. + the cost of a sequential page fetch. The default is 0.0025. @@ -1502,7 +1504,7 @@ SET ENABLE_SEQSCAN TO OFF; had a column-specific target set via ALTER TABLE SET STATISTICS. Larger values increase the time needed to do ANALYZE, but may improve the quality of the planner's - estimates. The default value is 10. + estimates. The default is 10. @@ -1650,8 +1652,8 @@ SET ENABLE_SEQSCAN TO OFF; Controls the amount of detail written in the server log for each - message that is logged. Valid values are terse, - default, and verbose, each adding more + message that is logged. Valid values are TERSE, + DEFAULT, and VERBOSE, each adding more fields to displayed messages. @@ -1813,14 +1815,15 @@ SET ENABLE_SEQSCAN TO OFF; debug_pretty_print (boolean) - These options enable various debugging output to be sent to the - client or server log. For each executed query, they print the resulting - parse tree, the query rewriter output, or the execution plan. - indents these displays to - produce a more readable but much longer output format. - or - must be DEBUG1 or lower to send output to the client - or server logs. + These options enable various debugging output to be sent to + the client or server log. For each executed query, they print + the resulting parse tree, the query rewriter output, or the + execution plan. debug_pretty_print indents + these displays to produce a more readable but much longer + output format. client_min_messages or + log_min_messages must be + DEBUG1 or lower to send output to the + client or server logs. These options are off by default. @@ -1845,7 +1848,7 @@ SET ENABLE_SEQSCAN TO OFF; Causes the duration of every completed statement to be logged. To use this option, enable log_statement and log_pid so you can link the statement to the - duration using the process ID. + duration using the process ID. The default is off. Only superusers can turn off this option if it is enabled by the administrator. @@ -1869,7 +1872,7 @@ SET ENABLE_SEQSCAN TO OFF; log_statement (boolean) - Causes each SQL statement to be logged. + Causes each SQL statement to be logged. The default is off. Only superusers can turn off this option if it is enabled by the administrator. @@ -1932,9 +1935,9 @@ SET ENABLE_SEQSCAN TO OFF; For each query, write performance statistics of the respective module to the server log. This is a crude profiling - instrument. - Only superusers can turn off this option if it is enabled by - the administrator. + instrument. All of these options are disabled by default. + Only superusers can turn off any of these options if they have + been enabled by the administrator. @@ -2127,7 +2130,8 @@ SET ENABLE_SEQSCAN TO OFF; Aborts any statement that takes over the specified number of - milliseconds. A value of zero turns off the timer. + milliseconds. A value of zero turns off the timer, which is + the default value. @@ -2300,8 +2304,9 @@ SET ENABLE_SEQSCAN TO OFF; explain_pretty_print (boolean) - Determines whether EXPLAIN VERBOSE uses the indented - or non-indented format for displaying detailed query-tree dumps. + Determines whether EXPLAIN VERBOSE uses the + indented or non-indented format for displaying detailed + query-tree dumps. The default is on. @@ -2357,9 +2362,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' Sets the maximum expression nesting depth of the parser. The - default value is high enough for any normal query, but you can - raise it if needed. (But if you raise it too high, you run - the risk of server crashes due to stack overflow.) + default value of 10000 is high enough for any normal query, + but you can raise it if needed. (But if you raise it too high, + you run the risk of server crashes due to stack overflow.) @@ -2409,7 +2414,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' The shared lock table is sized on the assumption that at most - max_locks_per_transaction * + max_locks_per_transaction * max_connections distinct objects will need to be locked at any one time. The default, 64, has historically proven sufficient, but you might need to raise this value if you @@ -2453,7 +2458,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' The regular expression flavor can be set to advanced, extended, or basic. - The usual default is advanced. The extended + The default is advanced. The extended setting may be useful for exact backwards compatibility with pre-7.4 releases of PostgreSQL. @@ -2533,13 +2538,13 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' Developer Options - The following options are intended for work on the PostgreSQL source, - and in some cases to assist with recovery of - severely damaged databases. There should be no reason to use them in - a production database setup. As such, they have been excluded from the - sample postgresql.conf file. - Note that many of these options require special - source compilation flags to work at all. + The following options are intended for work on the + PostgreSQL source, and in some cases + to assist with recovery of severely damaged databases. There + should be no reason to use them in a production database setup. + As such, they have been excluded from the sample + postgresql.conf file. Note that many of these + options require special source compilation flags to work at all. @@ -2580,9 +2585,9 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' Generates a great amount of debugging output for the LISTEN and NOTIFY - commands. - or - must be DEBUG1 or lower to send this output to the + commands. client_min_messages or + log_min_messages must be + DEBUG1 or lower to send this output to the client or server log, respectively. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 8d323c6879..ea446c9258 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ @@ -814,15 +814,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision To know how to write C-language functions, you need to know how - PostgreSQL internally represents base data types and how they can - be passed to and from functions. - Internally, PostgreSQL regards a - base type as a blob of memory. The user-defined - functions that you define over a type in turn define the - way that PostgreSQL can operate - on it. That is, PostgreSQL will - only store and retrieve the data from disk and use your - user-defined functions to input, process, and output the data. + PostgreSQL internally represents base + data types and how they can be passed to and from functions. + Internally, PostgreSQL regards a base + type as a blob of memory. The user-defined + functions that you define over a type in turn define the way that + PostgreSQL can operate on it. That + is, PostgreSQL will only store and + retrieve the data from disk and use your user-defined functions + to input, process, and output the data. @@ -1249,13 +1249,14 @@ CREATE FUNCTION concat_text(text, text) RETURNS text Here, DIRECTORY stands for the - directory of the shared library file (for instance the PostgreSQL - tutorial directory, which contains the code for the examples used - in this section). (Better style would be to use just - 'funcs' in the AS clause, after having - added DIRECTORY to the search path. - In any case, we may omit the system-specific extension for a - shared library, commonly .so or + directory of the shared library file (for instance the + PostgreSQL tutorial directory, which + contains the code for the examples used in this section). + (Better style would be to use just 'funcs' in the + AS clause, after having added + DIRECTORY to the search path. In any + case, we may omit the system-specific extension for a shared + library, commonly .so or .sl.) @@ -1483,15 +1484,16 @@ concat_text(PG_FUNCTION_ARGS) Before we turn to the more advanced topics, we should discuss - some coding rules for PostgreSQL C-language functions. While it - may be possible to load functions written in languages other than - C into PostgreSQL, this is usually - difficult (when it is possible at all) because other languages, - such as C++, FORTRAN, or Pascal often do not follow the same - calling convention as C. That is, other languages do not pass - argument and return values between functions in the same way. - For this reason, we will assume that your C-language functions - are actually written in C. + some coding rules for PostgreSQL + C-language functions. While it may be possible to load functions + written in languages other than C into + PostgreSQL, this is usually difficult + (when it is possible at all) because other languages, such as + C++, FORTRAN, or Pascal often do not follow the same calling + convention as C. That is, other languages do not pass argument + and return values between functions in the same way. For this + reason, we will assume that your C-language functions are + actually written in C. -- 2.40.0