diff options
29 files changed, 344 insertions, 769 deletions
diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml index b9819f4a526..31e94d76efc 100644 --- a/doc/src/sgml/ref/alter_group.sgml +++ b/doc/src/sgml/ref/alter_group.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.12 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -45,7 +45,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/alter_language.sgml b/doc/src/sgml/ref/alter_language.sgml index 61595252ebf..b0374a2c49e 100644 --- a/doc/src/sgml/ref/alter_language.sgml +++ b/doc/src/sgml/ref/alter_language.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -35,7 +35,7 @@ ALTER LANGUAGE <replaceable>name</replaceable> RENAME TO <replaceable>newname</r </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/alter_schema.sgml b/doc/src/sgml/ref/alter_schema.sgml index 473b57314d4..6f61cc5672e 100644 --- a/doc/src/sgml/ref/alter_schema.sgml +++ b/doc/src/sgml/ref/alter_schema.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -36,7 +36,7 @@ ALTER SCHEMA <replaceable>name</replaceable> RENAME TO <replaceable>newname</rep </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 1eaa97e2e1e..54efd0c4be0 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.28 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -74,7 +74,7 @@ CLUSTER </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml index 8d4e082ec07..7be6d0959da 100644 --- a/doc/src/sgml/ref/clusterdb.sgml +++ b/doc/src/sgml/ref/clusterdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.13 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.14 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -48,16 +48,17 @@ PostgreSQL documentation <application>clusterdb</application> is a wrapper around the SQL command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">. There is no effective difference between clustering databases via - this or other methods. The database server must be running at the - targeted host. Also, any default settings and environment - variables used by the <application>libpq</application> front-end - library will apply. + this utility and via other methods for accessing the server. </para> <para> In case of difficulty, see <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. </para> </refsect1> diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index 1c72ea0b459..4b026ccfd50 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.17 2003/09/09 18:28:52 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -12,8 +12,8 @@ PostgreSQL documentation <refnamediv> <refname>COMMIT</refname> <refpurpose>commit the current transaction</refpurpose> - </refnamediv> - + </refnamediv> + <indexterm zone="sql-commit"> <primary>COMMIT</primary> </indexterm> @@ -74,7 +74,7 @@ COMMIT; </programlisting> </para> </refsect1> - + <refsect1> <title>Compatibility</title> diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index ddde0df3347..9441c9841bd 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.35 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.36 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -37,6 +37,12 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> </para> <para> + To create a database, you must be a superuser or have the special + <literal>CREATEDB</> privilege. + See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">. + </para> + + <para> Normally, the creator becomes the owner of the new database. Superusers can create databases owned by other users using the <literal>OWNER</> clause. They can even create databases owned by @@ -63,6 +69,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> a leading slash (e.g., <filename>/usr/local/pgsql/data</filename>), are allowed as well. + In either case, the final path name must be absolute and must not + contain any single quotes. </para> <para> @@ -86,7 +94,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> @@ -147,78 +155,20 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>CREATE DATABASE</computeroutput></term> - <listitem> - <para> - Message returned if the database was successfully created. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term> - <listitem> - <para> - You must have the special <literal>CREATEDB</> privilege to create databases. - See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term> - <listitem> - <para> - This occurs if a database with the specified name already - exists. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: database path may not contain single quotes</computeroutput></term> - <listitem> - <para> - The database location - <replaceable class="parameter">dbpath</replaceable> cannot contain - single quotes. This is required so that the shell commands that - create the database directory can execute safely. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: CREATE DATABASE: may not be called in a transaction block</computeroutput></term> - <listitem> - <para> - If you have an explicit transaction block in progress you cannot call - <command>CREATE DATABASE</command>. You must finish the transaction first. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term> - <term><computeroutput>ERROR: Could not initialize database directory.</computeroutput></term> - <listitem> - <para> - These are most likely related to insufficient permissions on the data - directory, a full disk, or other file system problems. The user under - which the database server is running must have access to the location. - </para> - </listitem> - </varlistentry> + <title>Notes</title> - </variablelist> - </refsect1> + <para> + <command>CREATE DATABASE</> cannot be executed inside a transaction + block. + </para> - <refsect1> - <title>Notes</title> + <para> + Errors along the line of <quote>could not initialize database directory</> + are most likely related to insufficient permissions on the data + directory, a full disk, or other file system problems. When using an + alternate location, the user under + which the database server is running must have access to the location. + </para> <para> Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database. @@ -231,7 +181,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> <para> There are security issues involved with using alternate database - locations specified with absolute path names. See <xref + locations specified with absolute path names; this is why the feature + is not enabled by default. See <xref linkend="manage-ag-alternate-locs"> for more information. </para> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 5a9210fbcd3..089695b1bbc 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -197,49 +197,6 @@ SELECT * FROM <replaceable>seqname</replaceable>; </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>CREATE SEQUENCE</computeroutput></term> - <listitem> - <para> - Message returned if the sequence was successfully created. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists</computeroutput></term> - <listitem> - <para> - A sequence, table, view, or index of the specified name already exists. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term> - <term><computeroutput>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)</computeroutput></term> - <listitem> - <para> - The specified starting value is out of range. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term> - <listitem> - <para> - The minimum and maximum values are inconsistent. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> <para> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 6bf9434a1b1..a8d4a20f09a 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.23 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -91,39 +91,6 @@ class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="P </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>CREATE VIEW</computeroutput></term> - <listitem> - <para> - Message returned if the view was successfully created. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type</computeroutput></term> - <listitem> - <para> - The view will be created having a column with an unknown type if - you do not specify it. For example, the following command gives - this warning: -<programlisting> -CREATE VIEW vista AS SELECT 'Hello World' -</programlisting> - whereas this command does not: -<programlisting> -CREATE VIEW vista AS SELECT text 'Hello World' -</programlisting> - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> <para> @@ -137,6 +104,20 @@ CREATE VIEW vista AS SELECT text 'Hello World' <para> Use the <command>DROP VIEW</command> statement to drop views. </para> + + <para> + Be careful that the names and types of the view's columns will be + assigned the way you want. For example, +<programlisting> +CREATE VIEW vista AS SELECT 'Hello World'; +</programlisting> + is bad form in two ways: the column name defaults to <literal>?column?</>, + and the column datatype defaults to <type>unknown</>. If you want a + string literal in a view's result, use something like +<programlisting> +CREATE VIEW vista AS SELECT text 'Hello World' AS hello; +</programlisting> + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 0af10c05843..1c7e0ec4af8 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -48,12 +48,21 @@ PostgreSQL documentation <para> <application>createdb</application> is a wrapper around the <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE" - endterm="SQL-CREATEDATABASE-title">. The database server must be - running on the targeted host. There is nothing special about creating - databases via this or other methods. Also, any default settings and - environment variables used by the <application>libpq</application> - front-end library will apply. + endterm="SQL-CREATEDATABASE-title">. + There is no effective difference between creating databases via + this utility and via other methods for accessing the server. </para> + + <para> + In case of difficulty, see <xref linkend="SQL-CREATEDATABASE" + endterm="sql-createdatabase-title"> and <xref linkend="APP-PSQL"> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. + </para> + </refsect1> @@ -213,45 +222,6 @@ PostgreSQL documentation <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>CREATE DATABASE</computeroutput></term> - <listitem> - <para>The database was successfully created.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>createdb: Database creation failed.</computeroutput></term> - <listitem> - <para>(Says it all.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term> - <listitem> - <para> - The comment/description for the database could not be created. - The database itself will have been created already. You can use the - <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to - create the comment later on. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - If there is an error condition, the backend error message will be displayed. - See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE"> - for possibilities. - </para> - </refsect1> - - - <refsect1> <title>Environment</title> <variablelist> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index 0e6935f536b..484f7fbe11f 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.36 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.37 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -49,17 +49,19 @@ PostgreSQL documentation <para> <application>createuser</application> is a wrapper around the <acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER" - endterm="SQL-CREATEUSER-title">. The database server must be - running on the targeted host. There is nothing special - about creating users via this or other methods. Also, any - default settings and environment variables used by the - <application>libpq</application> front-end library will apply. + endterm="SQL-CREATEUSER-title">. + There is no effective difference between creating users via + this utility and via other methods for accessing the server. </para> <para> - Passwords can only be added later or changed using the - <acronym>SQL</acronym> command <xref linkend="SQL-ALTERUSER" - endterm="SQL-ALTERUSER-title">. + In case of difficulty, see <xref linkend="SQL-CREATEUSER" + endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. </para> </refsect1> @@ -101,6 +103,7 @@ PostgreSQL documentation <para> The new user is not allowed to create other users (i.e., the new user is a regular user, not a superuser). + This is the default. </para> </listitem> </varlistentry> @@ -121,6 +124,7 @@ PostgreSQL documentation <listitem> <para> The new user is not allowed to create databases. + This is the default. </para> </listitem> </varlistentry> @@ -142,7 +146,7 @@ PostgreSQL documentation <listitem> <para> Encrypts the user's password stored in the database. If not - specified, the default is used. + specified, the default password behavior is used. </para> </listitem> </varlistentry> @@ -164,7 +168,7 @@ PostgreSQL documentation <listitem> <para> Does not encrypt the user's password stored in the database. If - not specified, the default is used. + not specified, the default password behavior is used. </para> </listitem> </varlistentry> @@ -273,38 +277,6 @@ PostgreSQL documentation <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>CREATE USER</computeroutput></term> - <listitem> - <para> - The user was successfully created. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>createuser: creation of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term> - <listitem> - <para> - Something went wrong. The user was not created. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - If there is an error condition, the backend error message will be displayed. - See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> - for possibilities. - </para> - </refsect1> - - - <refsect1> <title>Examples</title> <para> diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 1a3e3ccaffe..a1884b5ee0b 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.27 2003/09/11 21:42:20 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.28 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -44,9 +44,10 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS format. Once the information comes back in text form, the client application may need to convert it to a binary format to manipulate it. In addition, data in the text format is often larger in size - than in the binary format. Binary cursors return the data in the - native binary representation. Nevertheless, if you intend to - display the data as text anyway, retrieving it in text form will + than in the binary format. Binary cursors return the data in a + binary representation that may be more easily manipulated. + Nevertheless, if you intend to display the data as text anyway, + retrieving it in text form will save you some effort on the client side. </para> @@ -54,7 +55,8 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS As an example, if a query returns a value of one from an integer column, you would get a string of <literal>1</> with a default cursor whereas with a binary cursor you would get - a 4-byte value containing the internal representation of the value. + a 4-byte field containing the internal representation of the value + (in big-endian byte order). </para> <para> @@ -64,16 +66,16 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS format. </para> - <para> - The string representation is architecture-neutral whereas binary - representation can differ between different machine architectures. - <emphasis><productname>PostgreSQL</productname> does not resolve - byte ordering or representation issues for binary - cursors.</emphasis> Therefore, if your client machine and server - machine use different representations (e.g., - <quote>big-endian</quote> versus <quote>little-endian</quote>), you - will probably not want your data returned in binary format. - </para> + <note> + <para> + When the client application uses the <quote>extended query</> protocol + to issue a <command>FETCH</> command, the Bind protocol message + specifies whether data is to be retrieved in text or binary format. + This choice overrides the way that the cursor is defined. The concept + of a binary cursor as such is thus obsolete when using extended query + protocol --- any cursor can be treated as either text or binary. + </para> + </note> </refsect1> <refsect1> @@ -84,8 +86,7 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS <term><replaceable class="parameter">cursorname</replaceable></term> <listitem> <para> - The name of the cursor to be used in subsequent - <command>FETCH</command> operations. + The name of the cursor to be created. </para> </listitem> </varlistentry> @@ -193,47 +194,17 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>DECLARE CURSOR</computeroutput></term> - <listitem> - <para> - The message returned if the cursor was successfully defined. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: cursor "<replaceable class="parameter">cursorname</replaceable>" already exists</computeroutput></term> - <listitem> - <para> - This error occurs if a cursor with the same name already exists. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks</computeroutput></term> - <listitem> - <para> - This error occurs if the cursor is not declared within a - transaction block, and <literal>WITH HOLD</literal> is not - specified. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> <para> - If <literal>WITH HOLD</literal> is not specified, the cursor + Unless <literal>WITH HOLD</literal> is specified, the cursor created by this command can only be used within the current - transaction. Use + transaction. Thus, <command>DECLARE</> without <literal>WITH + HOLD</literal> is useless outside a transaction block: the cursor would + survive only to the completion of the statement. Therefore + <productname>PostgreSQL</productname> reports an error if this + command is used outside a transaction block. + Use <xref linkend="sql-begin" endterm="sql-begin-title">, <xref linkend="sql-commit" endterm="sql-commit-title"> and diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index fea6a268abb..c0a58bd7ff7 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.18 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.19 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -52,7 +52,7 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE <para> You must have the <literal>DELETE</literal> privilege on the table to delete from it, as well as the <literal>SELECT</literal> - privilege to any table whose values are read in the <replaceable + privilege for any table whose values are read in the <replaceable class="parameter">condition</replaceable>. </para> </refsect1> @@ -84,22 +84,20 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE </refsect1> <refsect1> - <title>Diagnostics</title> + <title>Outputs</title> - <variablelist> - <varlistentry> - <term><computeroutput>DELETE <replaceable class="parameter">count</replaceable></computeroutput></term> - <listitem> - <para> - Message returned if rows are successfully deleted. The - <replaceable class="parameter">count</replaceable> is the number - of rows deleted. If <replaceable - class="parameter">count</replaceable> is 0, no rows were - deleted. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + On successful completion, a <command>DELETE</> command returns a command + tag of the form +<screen> +DELETE <replaceable class="parameter">count</replaceable> +</screen> + The <replaceable class="parameter">count</replaceable> is the number + of rows deleted. If <replaceable class="parameter">count</replaceable> is + 0, no rows matched the <replaceable + class="parameter">condition</replaceable> (this is not considered + an error). + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index 1224b4142ec..afb26d6a49a 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.17 2003/08/31 17:32:22 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -31,6 +31,9 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable> <command>DROP DATABASE</command> drops a database. It removes the catalog entries for the database and deletes the directory containing the data. It can only be executed by the database owner. + Also, it cannot be executed while you or anyone else are connected + to the target database. (Connect to <literal>template1</literal> or any + other database to issue this command.) </para> <para> @@ -54,43 +57,13 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>DROP DATABASE</computeroutput></term> - <listitem> - <para> - This message is returned if the command was successful. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>DROP DATABASE: cannot be executed on the currently open database</computeroutput></term> - <listitem> - <para> - You cannot be connected to the database you are about to remove. - Instead, connect to <literal>template1</literal> or any other - database and run this command again. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>DROP DATABASE: may not be called in a transaction block</computeroutput></term> - <listitem> - <para> - You must finish the transaction in progress before you can call this command. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> + <para> + <command>DROP DATABASE</> cannot be executed inside a transaction + block. + </para> + <para> This command cannot be executed while connected to the target database. Thus, it might be more convenient to use the program diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml index 143efbca9bd..b125c23a8e7 100644 --- a/doc/src/sgml/ref/drop_user.sgml +++ b/doc/src/sgml/ref/drop_user.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -50,39 +50,6 @@ DROP USER <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>DROP USER</computeroutput></term> - <listitem> - <para> - Message returned if the user was successfully deleted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term> - <listitem> - <para> - Message returned if the specified user does not exist. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed</computeroutput></term> - <listitem> - <para> - You must drop the database first or change its ownership. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> <para> @@ -91,6 +58,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable> same functionality as this command (in fact, it calls this command) but can be run from the command shell. </para> + + <para> + To drop a user who owns a database, first drop the database or change + its ownership. + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index 725eaf8991f..e1c28fe2931 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -41,12 +41,21 @@ PostgreSQL documentation <para> <application>dropdb</application> is a wrapper around the <acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE" - endterm="SQL-DROPDATABASE-title">. The database server must be - running on the targeted host. There is nothing special - about dropping databases via this or other methods. Also, any - default settings and environment variables used by the - <application>libpq</application> front-end library will apply. + endterm="SQL-DROPDATABASE-title">. + There is no effective difference between dropping databases via + this utility and via other methods for accessing the server. </para> + + <para> + In case of difficulty, see <xref linkend="SQL-DROPDATABASE" + endterm="sql-dropdatabase-title"> and <xref linkend="APP-PSQL"> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. + </para> + </refsect1> @@ -100,7 +109,7 @@ PostgreSQL documentation </para> <para> - <application>createdb</application> also accepts the following + <application>dropdb</application> also accepts the following command-line arguments for connection parameters: <variablelist> @@ -154,33 +163,6 @@ PostgreSQL documentation <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>DROP DATABASE</computeroutput></term> - <listitem> - <para>The database was successfully removed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>dropdb: Database removal failed.</computeroutput></term> - <listitem> - <para>Something didn't work out.</para> - </listitem> - </varlistentry> - </variablelist> - - <para> - If there is an error condition, the backend error message will be displayed. - See <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> - for possibilities. - </para> - </refsect1> - - - <refsect1> <title>Environment</title> <variablelist> diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index 27d67f9ba88..5c26050db96 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.28 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -43,12 +43,21 @@ PostgreSQL documentation <para> <application>dropuser</application> is a wrapper around the <acronym>SQL</acronym> command <xref linkend="SQL-DROPUSER" - endterm="SQL-DROPUSER-title">. The database server must be running - on the targeted host. There is nothing special about removing - users via this or other methods. Also, any default settings and - environment variables used by the <application>libpq</application> - front-end library will apply. + endterm="SQL-DROPUSER-title">. + There is no effective difference between dropping users via + this utility and via other methods for accessing the server. </para> + + <para> + In case of difficulty, see <xref linkend="SQL-DROPUSER" + endterm="sql-dropuser-title"> and <xref linkend="APP-PSQL"> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. + </para> + </refsect1> @@ -103,7 +112,7 @@ PostgreSQL documentation </para> <para> - <application>createuser</application> also accepts the following + <application>dropuser</application> also accepts the following command-line arguments for connection parameters: <variablelist> @@ -177,38 +186,6 @@ PostgreSQL documentation <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>DROP USER</computeroutput></term> - <listitem> - <para> - The user was successfully removed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>dropuser: deletion of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term> - <listitem> - <para> - Something went wrong. The user was not removed. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - If there is an error condition, the backend error message will be displayed. - See <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> - and <xref linkend="APP-PSQL"> for possibilities. - </para> - </refsect1> - - - <refsect1> <title>Examples</title> <para> diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml index 7772184ae83..115d25f0053 100644 --- a/doc/src/sgml/ref/end.sgml +++ b/doc/src/sgml/ref/end.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.11 2003/09/11 21:42:20 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.12 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -30,9 +30,10 @@ END [ WORK | TRANSACTION ] <para> <command>END</command> 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 - <productname>PostgreSQL</productname> extension that is equivalent - to <xref linkend="sql-commit" endterm="sql-commit-title">. + to be durable if a crash occurs. This command is a + <productname>PostgreSQL</productname> extension + that is equivalent to <xref linkend="sql-commit" + endterm="sql-commit-title">. </para> </refsect1> @@ -51,31 +52,7 @@ END [ WORK | TRANSACTION ] </varlistentry> </variablelist> </refsect1> - - <refsect1> - <title>Diagnostics</title> - <variablelist> - <varlistentry> - <term><computeroutput>COMMIT</computeroutput></term> - <listitem> - <para> - Message returned if the transaction was successfully committed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>WARNING: COMMIT: no transaction in progress</computeroutput></term> - <listitem> - <para> - Message if there is no transaction in progress. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> <title>Notes</title> @@ -83,6 +60,11 @@ END [ WORK | TRANSACTION ] Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to abort a transaction. </para> + + <para> + Issuing <command>END</> when not inside a transaction does + no harm, but it will provoke a warning message. + </para> </refsect1> <refsect1> @@ -106,6 +88,16 @@ END; specified in the SQL standard. </para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-begin" endterm="sql-begin-title"></member> + <member><xref linkend="sql-commit" endterm="sql-commit-title"></member> + <member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member> + </simplelist> + </refsect1> </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index bb9016d69a6..754863881d0 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.29 2003/09/09 18:28:53 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.30 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -80,7 +80,7 @@ ROLLBACK; </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index 9c1050b835e..5f3639d4c7f 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.32 2003/09/09 18:28:53 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -45,7 +45,7 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one <title>Description</title> <para> - <command>FETCH</command> retrieves rows using a cursor. + <command>FETCH</command> retrieves rows using a previously-created cursor. </para> <para> @@ -281,6 +281,23 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one </refsect1> <refsect1> + <title>Outputs</title> + + <para> + On successful completion, a <command>FETCH</> command returns a command + tag of the form +<screen> +FETCH <replaceable class="parameter">count</replaceable> +</screen> + The <replaceable class="parameter">count</replaceable> is the number + of rows fetched (possibly zero). Note that in + <application>psql</application>, the command tag will not actually be + displayed, since <application>psql</application> displays the fetched + rows instead. + </para> + </refsect1> + + <refsect1> <title>Notes</title> <para> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 76160d6dbec..40ecaccdaf8 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.24 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.25 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -119,30 +119,21 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable </refsect1> <refsect1> - <title>Diagnostics</title> + <title>Outputs</title> - <variablelist> - <varlistentry> - <term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term> - <listitem> - <para> - Message returned if only one row was inserted. - <returnvalue><replaceable>oid</replaceable></returnvalue> is the - <acronym>OID</acronym> of the inserted row. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>INSERT 0 <replaceable>count</replaceable></computeroutput></term> - <listitem> - <para> - Message returned if more than one rows were inserted. - <replaceable>count</replaceable> is the number of rows inserted. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + On successful completion, an <command>INSERT</> command returns a command + tag of the form +<screen> +INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable> +</screen> + The <replaceable class="parameter">count</replaceable> is the number + of rows inserted. If <replaceable class="parameter">count</replaceable> + is exactly one, and the target table has OIDs, then + <replaceable class="parameter">oid</replaceable> is the + <acronym>OID</acronym> assigned to the inserted row. Otherwise + <replaceable class="parameter">oid</replaceable> is zero. + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 7de13387dbd..8029b5ed036 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -31,6 +31,9 @@ LISTEN <replaceable class="PARAMETER">name</replaceable> <command>LISTEN</command> registers the current session as a listener on the notification condition <replaceable class="PARAMETER">name</replaceable>. + If the current session is already registered as a listener for + this notification condition, a warning message appears and nothing + is done. </para> <para> @@ -86,30 +89,6 @@ LISTEN <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>LISTEN</computeroutput></term> - <listitem> - <para> - Message returned upon successful completion of registration. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETER">name</replaceable></computeroutput></term> - <listitem> - <para> - Message returned if this session is already registered for that notification condition. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Examples</title> <para> @@ -117,7 +96,7 @@ LISTEN <replaceable class="PARAMETER">name</replaceable> <programlisting> LISTEN virtual; NOTIFY virtual; -Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. +Asynchronous notification "virtual" received from server process with PID 8448. </programlisting> </para> </refsect1> diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 471e0529790..c13cdc9ead3 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -41,12 +41,16 @@ MOVE [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <r </refsect1> <refsect1> - <title>Diagnostics</title> + <title>Outputs</title> <para> - The count returned in <command>MOVE</command>'s status string is - the count of the number of rows that would have been returned by - the equivalent <command>FETCH</command> command. + On successful completion, a <command>MOVE</> command returns a command + tag of the form +<screen> +MOVE <replaceable class="parameter">count</replaceable> +</screen> + The <replaceable class="parameter">count</replaceable> is the number + of rows moved over (possibly zero). </para> </refsect1> diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 07c6f2bfc02..77aecf70310 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.38 2003/09/11 17:31:45 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.39 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -419,73 +419,52 @@ PostgreSQL documentation <refsect1> <title>Diagnostics</title> - <para> - <variablelist> - <varlistentry> - <term><computeroutput>semget: No space left on device</computeroutput></term> - <listitem> - <para> - If you see this message, you probably need to configure - your kernel for shared memory and semaphores as described in <xref linkend="kernel-resources">. - If you run multiple instances of - <command>postmaster</command> - on a single host, or have a kernel with particularly small shared memory - and/or semaphore limits, you may have to reconfigure your kernel to increase - its shared memory or semaphore parameters. - </para> + <para> + A failure message mentioning <literal>semget</> or <literal>shmget</> + probably indicates you need to configure your kernel to provide adequate + shared memory and semaphores. For more discussion see <xref + linkend="kernel-resources">. + </para> - <tip> - <para> - You may be able to postpone - reconfiguring your kernel by decreasing <option>-B</option> to reduce - the shared memory consumption of <productname>PostgreSQL</>, - and/or by reducing <option>-N</option> to reduce the semaphore - consumption. - </para> - </tip> - </listitem> - </varlistentry> + <tip> + <para> + You may be able to postpone reconfiguring your kernel by decreasing + <varname>shared_buffers</varname> to reduce the shared memory consumption + of <productname>PostgreSQL</>, and/or by reducing + <varname>max_connections</varname> to reduce the semaphore consumption. + </para> + </tip> - <varlistentry> - <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term> - <listitem> - <para> - If you see this message, you should make certain that there is no - other <command>postmaster</command> - process already running on the same port number. The easiest way to - determine this is by using the command + <para> + A failure message suggesting that another postmaster is already running + should be checked carefully, for example by using the command <screen> <prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput> </screen> or <screen> -<prompt>$</prompt> <userinput>ps -e | grep postmaster</userinput> +<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput> </screen> - depending on your system. - </para> + depending on your system. If you are certain that no conflicting + postmaster is running, you may remove the lock file mentioned in the + message and try again. + </para> - <para> - If you - are sure that no other - <command>postmaster</command> - processes are running and you still get this error, try specifying a - different port using the - <literal>-p</literal> - option. You may also get this error if you terminate the - <command>postmaster</command> - and immediately restart it using the same port; in this case, you must - simply wait a few seconds until the operating system closes the port - before trying again. Finally, you may get this error if you specify - a port number that your operating system considers to be reserved. - For example, many versions of Unix consider port numbers under 1024 to - be <quote>trusted</quote> - and only permit the Unix superuser to access them. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + A failure message indicating inability to bind to a port may indicate + that that port is already in use by some non-PostgreSQL process. + You may also get this error if you terminate the + <command>postmaster</command> + and immediately restart it using the same port; in this case, you must + simply wait a few seconds until the operating system closes the port + before trying again. Finally, you may get this error if you specify + a port number that your operating system considers to be reserved. + For example, many versions of Unix consider port numbers under 1024 to + be <quote>trusted</quote> + and only permit the Unix superuser to access them. </para> + </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index cf9f0468ade..1bdb3d0ebb4 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.81 2003/08/31 17:32:24 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.82 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -225,48 +225,6 @@ SELECT setseed(<replaceable>value</replaceable>); </refsect1> <refsect1> - <title>Diagnostics</title> - - <variablelist> - <varlistentry> - <term><computeroutput>SET</computeroutput></term> - <listitem> - <para> - Message returned if successful. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: '<replaceable>name</replaceable>' is not a valid option name</computeroutput></term> - <listitem> - <para> - The parameter you tried to set does not exist. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: '<replaceable>name</replaceable>': permission denied</computeroutput></term> - <listitem> - <para> - You must be a superuser to alter certain settings. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>ERROR: '<replaceable>name</replaceable>' cannot be changed after server start</computeroutput></term> - <listitem> - <para> - Some parameters are fixed once the server is started. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> <title>Notes</title> <para> diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index 3fca8691035..fc65f65db55 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.12 2003/09/09 18:28:53 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -36,7 +36,7 @@ TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable> </refsect1> <refsect1> - <title>Parameter</title> + <title>Parameters</title> <variablelist> <varlistentry> diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 01917b362df..10d5886b3b2 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.25 2003/09/11 21:42:20 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.26 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -118,21 +118,20 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea </refsect1> <refsect1> - <title>Diagnostics</title> + <title>Outputs</title> - <variablelist> - <varlistentry> - <term><computeroutput>UPDATE <replaceable class="parameter">count</replaceable></computeroutput></term> - <listitem> - <para> - Message returned if successful. The value <replaceable - class="parameter">count</replaceable> is the number of rows - updated. If <replaceable class="parameter">count</replaceable> - is 0, no rows were updated. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + On successful completion, an <command>UPDATE</> command returns a command + tag of the form +<screen> +UPDATE <replaceable class="parameter">count</replaceable> +</screen> + The <replaceable class="parameter">count</replaceable> is the number + of rows updated. If <replaceable class="parameter">count</replaceable> is + 0, no rows matched the <replaceable + class="parameter">condition</replaceable> (this is not considered + an error). + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 7102a3d0d33..aab2f74bf14 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.32 2003/08/31 17:32:24 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -143,49 +143,13 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER"> </refsect1> <refsect1> - <title>Diagnostics</title> + <title>Outputs</title> - <variablelist> - <varlistentry> - <term><computeroutput>VACUUM</computeroutput></term> - <listitem> - <para> - The command is complete. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>INFO: --Relation <replaceable class="PARAMETER">table</replaceable>--</computeroutput></term> - <listitem> - <para> - The report header for <replaceable class="PARAMETER">table</replaceable>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>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.</computeroutput></term> - <listitem> - <para> - The analysis for <replaceable class="PARAMETER">table</replaceable> itself. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28; - Tuples 1000: Deleted 3000. Elapsed 0/0 sec.</computeroutput></term> - <listitem> - <para> - The analysis for an index on the target table. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + When <literal>VERBOSE</> is specified, <command>VACUUM</> emits + progress messages to indicate which table is currently being + processed. Various statistics about the tables are printed as well. + </para> </refsect1> <refsect1> @@ -216,25 +180,37 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER"> <title>Examples</title> <para> - The following is an example from running <command>VACUUM</command> on a table - in the regression database: + The following is an example from running <command>VACUUM</command> on a + table in the regression database: <programlisting> -=> 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. -INFO: Index onek_unique2: Pages 16; Tuples 1000: Deleted 3000. - CPU 0.00s/0.10u sec elapsed 0.10 sec. -INFO: Index onek_hundred: Pages 13; Tuples 1000: Deleted 3000. - CPU 0.00s/0.10u sec elapsed 0.10 sec. -INFO: Index onek_stringu1: Pages 31; Tuples 1000: Deleted 3000. - CPU 0.01s/0.09u sec elapsed 0.10 sec. -INFO: Removed 3000 tuples in 70 pages. - CPU 0.02s/0.04u sec elapsed 0.07 sec. -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 +regression=# VACUUM VERBOSE ANALYZE onek; +INFO: vacuuming "public.onek" +INFO: index "onek_unique1" now contains 1000 tuples in 14 pages +DETAIL: 3000 index tuples were removed. +0 index pages have been deleted, 0 are currently reusable. +CPU 0.01s/0.08u sec elapsed 0.18 sec. +INFO: index "onek_unique2" now contains 1000 tuples in 16 pages +DETAIL: 3000 index tuples were removed. +0 index pages have been deleted, 0 are currently reusable. +CPU 0.00s/0.07u sec elapsed 0.23 sec. +INFO: index "onek_hundred" now contains 1000 tuples in 13 pages +DETAIL: 3000 index tuples were removed. +0 index pages have been deleted, 0 are currently reusable. +CPU 0.01s/0.08u sec elapsed 0.17 sec. +INFO: index "onek_stringu1" now contains 1000 tuples in 48 pages +DETAIL: 3000 index tuples were removed. +0 index pages have been deleted, 0 are currently reusable. +CPU 0.01s/0.09u sec elapsed 0.59 sec. +INFO: "onek": removed 3000 tuples in 108 pages +DETAIL: CPU 0.01s/0.06u sec elapsed 0.07 sec. +INFO: "onek": found 3000 removable, 1000 nonremovable tuples in 143 pages +DETAIL: 0 dead tuples cannot be removed yet. +There were 0 unused item pointers. +0 pages are entirely empty. +CPU 0.07s/0.39u sec elapsed 1.56 sec. +INFO: analyzing "public.onek" +INFO: "onek": 36 pages, 1000 rows sampled, 1000 estimated total rows VACUUM </programlisting> </para> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 31390050c29..63d7b4d3ee4 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.31 2003/08/31 17:32:24 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.32 2003/09/12 00:12:47 tgl Exp $ PostgreSQL documentation --> @@ -55,13 +55,19 @@ PostgreSQL documentation <application>vacuumdb</application> is a wrapper around the SQL command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">. There is no effective difference between vacuuming databases via - this or other methods. The database server must be running at the - targeted host. Also, any default settings and environment + this utility and via other methods for accessing the server. + </para> + + <para> + In case of difficulty, see <xref linkend="SQL-VACUUM" + endterm="sql-vacuum-title"> and <xref linkend="APP-PSQL"> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment variables used by the <application>libpq</application> front-end library will apply. </para> - <para> <application>vacuumdb</application> might need to connect several times to the <productname>PostgreSQL</productname> server, asking @@ -231,37 +237,6 @@ PostgreSQL documentation <refsect1> - <title>Diagnostics</title> - - <para> - <variablelist> - <varlistentry> - <term><computeroutput>VACUUM</computeroutput></term> - <listitem> - <para> - The database was successfully vacuumed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><computeroutput>vacuumdb: Vacuum failed.</computeroutput></term> - <listitem> - <para> - Something went wrong. <application>vacuumdb</application> is only a wrapper - script. See <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> - and <xref linkend="APP-PSQL"> for a detailed - discussion of error messages and potential problems. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect1> - - - <refsect1> <title>Environment</title> <variablelist> |