rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More cleanup of Diagnostics sections.

This commit is contained in:
Tom Lane 2003-09-12 00:12:47 +00:00
parent fbb39c059e
commit e90b841915
29 changed files with 346 additions and 771 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/ref/alter_group.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -45,7 +45,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

4
doc/src/sgml/ref/alter_language.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -35,7 +35,7 @@ ALTER LANGUAGE <replaceable>name</replaceable> RENAME TO <replaceable>newname</r
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

4
doc/src/sgml/ref/alter_schema.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -36,7 +36,7 @@ ALTER SCHEMA <replaceable>name</replaceable> RENAME TO <replaceable>newname</rep
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

4
doc/src/sgml/ref/cluster.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -74,7 +74,7 @@ CLUSTER
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

11
doc/src/sgml/ref/clusterdb.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -48,16 +48,17 @@ PostgreSQL documentation
<application>clusterdb</application> is a wrapper around the SQL <application>clusterdb</application> is a wrapper around the SQL
command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">. command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">.
There is no effective difference between clustering databases via There is no effective difference between clustering databases via
this or other methods. The database server must be running at the this utility and via other methods for accessing the server.
targeted host. Also, any default settings and environment
variables used by the <application>libpq</application> front-end
library will apply.
</para> </para>
<para> <para>
In case of difficulty, see <xref linkend="SQL-CLUSTER" In case of difficulty, see <xref linkend="SQL-CLUSTER"
endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for
discussions of potential problems and error messages. 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>
</refsect1> </refsect1>

8
doc/src/sgml/ref/commit.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -12,8 +12,8 @@ PostgreSQL documentation
<refnamediv> <refnamediv>
<refname>COMMIT</refname> <refname>COMMIT</refname>
<refpurpose>commit the current transaction</refpurpose> <refpurpose>commit the current transaction</refpurpose>
</refnamediv> </refnamediv>
<indexterm zone="sql-commit"> <indexterm zone="sql-commit">
<primary>COMMIT</primary> <primary>COMMIT</primary>
</indexterm> </indexterm>
@ -74,7 +74,7 @@ COMMIT;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Compatibility</title> <title>Compatibility</title>

99
doc/src/sgml/ref/create_database.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -36,6 +36,12 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<productname>PostgreSQL</productname> database. <productname>PostgreSQL</productname> database.
</para> </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> <para>
Normally, the creator becomes the owner of the new database. Normally, the creator becomes the owner of the new database.
Superusers can create databases owned by other users using the Superusers can create databases owned by other users using the
@ -63,6 +69,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
a leading slash a leading slash
(e.g., <filename>/usr/local/pgsql/data</filename>), (e.g., <filename>/usr/local/pgsql/data</filename>),
are allowed as well. are allowed as well.
In either case, the final path name must be absolute and must not
contain any single quotes.
</para> </para>
<para> <para>
@ -86,7 +94,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -146,80 +154,22 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</para> </para>
</refsect1> </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>
</variablelist>
</refsect1>
<refsect1> <refsect1>
<title>Notes</title> <title>Notes</title>
<para>
<command>CREATE DATABASE</> cannot be executed inside a transaction
block.
</para>
<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> <para>
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database. Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
</para> </para>
@ -231,7 +181,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<para> <para>
There are security issues involved with using alternate database 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. linkend="manage-ag-alternate-locs"> for more information.
</para> </para>

45
doc/src/sgml/ref/create_sequence.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -196,49 +196,6 @@ SELECT * FROM <replaceable>seqname</replaceable>;
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>

49
doc/src/sgml/ref/create_view.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -90,39 +90,6 @@ class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="P
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>
@ -137,6 +104,20 @@ CREATE VIEW vista AS SELECT text 'Hello World'
<para> <para>
Use the <command>DROP VIEW</command> statement to drop views. Use the <command>DROP VIEW</command> statement to drop views.
</para> </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>
<refsect1> <refsect1>

60
doc/src/sgml/ref/createdb.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -48,12 +48,21 @@ PostgreSQL documentation
<para> <para>
<application>createdb</application> is a wrapper around the <application>createdb</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE" <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE"
endterm="SQL-CREATEDATABASE-title">. The database server must be endterm="SQL-CREATEDATABASE-title">.
running on the targeted host. There is nothing special about creating There is no effective difference between creating databases via
databases via this or other methods. Also, any default settings and this utility and via other methods for accessing the server.
environment variables used by the <application>libpq</application>
front-end library will apply.
</para> </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> </refsect1>
@ -212,45 +221,6 @@ PostgreSQL documentation
</refsect1> </refsect1>
<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> <refsect1>
<title>Environment</title> <title>Environment</title>

58
doc/src/sgml/ref/createuser.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -49,17 +49,19 @@ PostgreSQL documentation
<para> <para>
<application>createuser</application> is a wrapper around the <application>createuser</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER" <acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER"
endterm="SQL-CREATEUSER-title">. The database server must be endterm="SQL-CREATEUSER-title">.
running on the targeted host. There is nothing special There is no effective difference between creating users via
about creating users via this or other methods. Also, any this utility and via other methods for accessing the server.
default settings and environment variables used by the
<application>libpq</application> front-end library will apply.
</para> </para>
<para> <para>
Passwords can only be added later or changed using the In case of difficulty, see <xref linkend="SQL-CREATEUSER"
<acronym>SQL</acronym> command <xref linkend="SQL-ALTERUSER" endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for
endterm="SQL-ALTERUSER-title">. 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>
</refsect1> </refsect1>
@ -101,6 +103,7 @@ PostgreSQL documentation
<para> <para>
The new user is not allowed to create other users (i.e., The new user is not allowed to create other users (i.e.,
the new user is a regular user, not a superuser). the new user is a regular user, not a superuser).
This is the default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -121,6 +124,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
The new user is not allowed to create databases. The new user is not allowed to create databases.
This is the default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -142,7 +146,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Encrypts the user's password stored in the database. If not Encrypts the user's password stored in the database. If not
specified, the default is used. specified, the default password behavior is used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -164,7 +168,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Does not encrypt the user's password stored in the database. If 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -272,38 +276,6 @@ PostgreSQL documentation
</refsect1> </refsect1>
<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> <refsect1>
<title>Examples</title> <title>Examples</title>

79
doc/src/sgml/ref/declare.sgml
View File

@ -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 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 format. Once the information comes back in text form, the client
application may need to convert it to a binary format to manipulate 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 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 than in the binary format. Binary cursors return the data in a
native binary representation. Nevertheless, if you intend to binary representation that may be more easily manipulated.
display the data as text anyway, retrieving it in text form will 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. save you some effort on the client side.
</para> </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, 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 you would get a string of <literal>1</> with a default cursor
whereas with a binary cursor you would get 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>
<para> <para>
@ -64,16 +66,16 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
format. format.
</para> </para>
<para> <note>
The string representation is architecture-neutral whereas binary <para>
representation can differ between different machine architectures. When the client application uses the <quote>extended query</> protocol
<emphasis><productname>PostgreSQL</productname> does not resolve to issue a <command>FETCH</> command, the Bind protocol message
byte ordering or representation issues for binary specifies whether data is to be retrieved in text or binary format.
cursors.</emphasis> Therefore, if your client machine and server This choice overrides the way that the cursor is defined. The concept
machine use different representations (e.g., of a binary cursor as such is thus obsolete when using extended query
<quote>big-endian</quote> versus <quote>little-endian</quote>), you protocol --- any cursor can be treated as either text or binary.
will probably not want your data returned in binary format. </para>
</para> </note>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -84,8 +86,7 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
<term><replaceable class="parameter">cursorname</replaceable></term> <term><replaceable class="parameter">cursorname</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of the cursor to be used in subsequent The name of the cursor to be created.
<command>FETCH</command> operations.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -192,48 +193,18 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
</para> </para>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>
<para> <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 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-begin" endterm="sql-begin-title">,
<xref linkend="sql-commit" endterm="sql-commit-title"> <xref linkend="sql-commit" endterm="sql-commit-title">
and and

32
doc/src/sgml/ref/delete.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -52,7 +52,7 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
<para> <para>
You must have the <literal>DELETE</literal> privilege on the table You must have the <literal>DELETE</literal> privilege on the table
to delete from it, as well as the <literal>SELECT</literal> 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>. class="parameter">condition</replaceable>.
</para> </para>
</refsect1> </refsect1>
@ -84,22 +84,20 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Outputs</title>
<variablelist> <para>
<varlistentry> On successful completion, a <command>DELETE</> command returns a command
<term><computeroutput>DELETE <replaceable class="parameter">count</replaceable></computeroutput></term> tag of the form
<listitem> <screen>
<para> DELETE <replaceable class="parameter">count</replaceable>
Message returned if rows are successfully deleted. The </screen>
<replaceable class="parameter">count</replaceable> is the number The <replaceable class="parameter">count</replaceable> is the number
of rows deleted. If <replaceable of rows deleted. If <replaceable class="parameter">count</replaceable> is
class="parameter">count</replaceable> is 0, no rows were 0, no rows matched the <replaceable
deleted. class="parameter">condition</replaceable> (this is not considered
</para> an error).
</listitem> </para>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1> <refsect1>

45
doc/src/sgml/ref/drop_database.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -31,6 +31,9 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
<command>DROP DATABASE</command> drops a database. It removes the <command>DROP DATABASE</command> drops a database. It removes the
catalog entries for the database and deletes the directory catalog entries for the database and deletes the directory
containing the data. It can only be executed by the database owner. 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>
<para> <para>
@ -53,44 +56,14 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>
<para>
<command>DROP DATABASE</> cannot be executed inside a transaction
block.
</para>
<para> <para>
This command cannot be executed while connected to the target This command cannot be executed while connected to the target
database. Thus, it might be more convenient to use the program database. Thus, it might be more convenient to use the program

40
doc/src/sgml/ref/drop_user.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -49,39 +49,6 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>
@ -91,6 +58,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
same functionality as this command (in fact, it calls this command) same functionality as this command (in fact, it calls this command)
but can be run from the command shell. but can be run from the command shell.
</para> </para>
<para>
To drop a user who owns a database, first drop the database or change
its ownership.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>

50
doc/src/sgml/ref/dropdb.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -41,12 +41,21 @@ PostgreSQL documentation
<para> <para>
<application>dropdb</application> is a wrapper around the <application>dropdb</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE" <acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE"
endterm="SQL-DROPDATABASE-title">. The database server must be endterm="SQL-DROPDATABASE-title">.
running on the targeted host. There is nothing special There is no effective difference between dropping databases via
about dropping databases via this or other methods. Also, any this utility and via other methods for accessing the server.
default settings and environment variables used by the
<application>libpq</application> front-end library will apply.
</para> </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> </refsect1>
@ -100,7 +109,7 @@ PostgreSQL documentation
</para> </para>
<para> <para>
<application>createdb</application> also accepts the following <application>dropdb</application> also accepts the following
command-line arguments for connection parameters: command-line arguments for connection parameters:
<variablelist> <variablelist>
@ -153,33 +162,6 @@ PostgreSQL documentation
</refsect1> </refsect1>
<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> <refsect1>
<title>Environment</title> <title>Environment</title>

55
doc/src/sgml/ref/dropuser.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -43,12 +43,21 @@ PostgreSQL documentation
<para> <para>
<application>dropuser</application> is a wrapper around the <application>dropuser</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-DROPUSER" <acronym>SQL</acronym> command <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title">. The database server must be running endterm="SQL-DROPUSER-title">.
on the targeted host. There is nothing special about removing There is no effective difference between dropping users via
users via this or other methods. Also, any default settings and this utility and via other methods for accessing the server.
environment variables used by the <application>libpq</application>
front-end library will apply.
</para> </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> </refsect1>
@ -103,7 +112,7 @@ PostgreSQL documentation
</para> </para>
<para> <para>
<application>createuser</application> also accepts the following <application>dropuser</application> also accepts the following
command-line arguments for connection parameters: command-line arguments for connection parameters:
<variablelist> <variablelist>
@ -176,38 +185,6 @@ PostgreSQL documentation
</refsect1> </refsect1>
<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> <refsect1>
<title>Examples</title> <title>Examples</title>

48
doc/src/sgml/ref/end.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -30,9 +30,10 @@ END [ WORK | TRANSACTION ]
<para> <para>
<command>END</command> commits the current transaction. All changes <command>END</command> commits the current transaction. All changes
made by the transaction become visible to others and are guaranteed made by the transaction become visible to others and are guaranteed
to be durable if a crash occurs. It is a to be durable if a crash occurs. This command is a
<productname>PostgreSQL</productname> extension that is equivalent <productname>PostgreSQL</productname> extension
to <xref linkend="sql-commit" endterm="sql-commit-title">. that is equivalent to <xref linkend="sql-commit"
endterm="sql-commit-title">.
</para> </para>
</refsect1> </refsect1>
@ -51,31 +52,7 @@ END [ WORK | TRANSACTION ]
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>
@ -83,6 +60,11 @@ END [ WORK | TRANSACTION ]
Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
abort a transaction. abort a transaction.
</para> </para>
<para>
Issuing <command>END</> when not inside a transaction does
no harm, but it will provoke a warning message.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -106,6 +88,16 @@ END;
specified in the SQL standard. specified in the SQL standard.
</para> </para>
</refsect1> </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> </refentry>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

4
doc/src/sgml/ref/explain.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -80,7 +80,7 @@ ROLLBACK;
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

21
doc/src/sgml/ref/fetch.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -45,7 +45,7 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
<title>Description</title> <title>Description</title>
<para> <para>
<command>FETCH</command> retrieves rows using a cursor. <command>FETCH</command> retrieves rows using a previously-created cursor.
</para> </para>
<para> <para>
@ -280,6 +280,23 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>

39
doc/src/sgml/ref/insert.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -119,30 +119,21 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Outputs</title>
<variablelist> <para>
<varlistentry> On successful completion, an <command>INSERT</> command returns a command
<term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term> tag of the form
<listitem> <screen>
<para> INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable>
Message returned if only one row was inserted. </screen>
<returnvalue><replaceable>oid</replaceable></returnvalue> is the The <replaceable class="parameter">count</replaceable> is the number
<acronym>OID</acronym> of the inserted row. of rows inserted. If <replaceable class="parameter">count</replaceable>
</para> is exactly one, and the target table has OIDs, then
</listitem> <replaceable class="parameter">oid</replaceable> is the
</varlistentry> <acronym>OID</acronym> assigned to the inserted row. Otherwise
<replaceable class="parameter">oid</replaceable> is zero.
<varlistentry> </para>
<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>
</refsect1> </refsect1>
<refsect1> <refsect1>

31
doc/src/sgml/ref/listen.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -31,6 +31,9 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<command>LISTEN</command> registers the current session as a <command>LISTEN</command> registers the current session as a
listener on the notification condition <replaceable listener on the notification condition <replaceable
class="PARAMETER">name</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>
<para> <para>
@ -85,30 +88,6 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
</variablelist> </variablelist>
</refsect1> </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> <refsect1>
<title>Examples</title> <title>Examples</title>
@ -117,7 +96,7 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<programlisting> <programlisting>
LISTEN virtual; LISTEN virtual;
NOTIFY virtual; NOTIFY virtual;
Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. Asynchronous notification "virtual" received from server process with PID 8448.
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>

14
doc/src/sgml/ref/move.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -41,12 +41,16 @@ MOVE [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <r
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Outputs</title>
<para> <para>
The count returned in <command>MOVE</command>'s status string is On successful completion, a <command>MOVE</> command returns a command
the count of the number of rows that would have been returned by tag of the form
the equivalent <command>FETCH</command> command. <screen>
MOVE <replaceable class="parameter">count</replaceable>
</screen>
The <replaceable class="parameter">count</replaceable> is the number
of rows moved over (possibly zero).
</para> </para>
</refsect1> </refsect1>

95
doc/src/sgml/ref/postmaster.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -419,73 +419,52 @@ PostgreSQL documentation
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Diagnostics</title>
<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>
<variablelist> <tip>
<varlistentry> <para>
<term><computeroutput>semget: No space left on device</computeroutput></term> You may be able to postpone reconfiguring your kernel by decreasing
<listitem> <varname>shared_buffers</varname> to reduce the shared memory consumption
<para> of <productname>PostgreSQL</>, and/or by reducing
If you see this message, you probably need to configure <varname>max_connections</varname> to reduce the semaphore consumption.
your kernel for shared memory and semaphores as described in <xref linkend="kernel-resources">. </para>
If you run multiple instances of </tip>
<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>
<tip> <para>
<para> A failure message suggesting that another postmaster is already running
You may be able to postpone should be checked carefully, for example by using the command
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>
<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
<screen> <screen>
<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput> <prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
</screen> </screen>
or or
<screen> <screen>
<prompt>$</prompt> <userinput>ps -e | grep postmaster</userinput> <prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
</screen> </screen>
depending on your system. depending on your system. If you are certain that no conflicting
</para> postmaster is running, you may remove the lock file mentioned in the
message and try again.
<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> </para>
<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>
<refsect1> <refsect1>

44
doc/src/sgml/ref/set.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -224,48 +224,6 @@ SELECT setseed(<replaceable>value</replaceable>);
</para> </para>
</refsect1> </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> <refsect1>
<title>Notes</title> <title>Notes</title>

4
doc/src/sgml/ref/truncate.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -36,7 +36,7 @@ TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameter</title> <title>Parameters</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

29
doc/src/sgml/ref/update.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -118,21 +118,20 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Outputs</title>
<variablelist> <para>
<varlistentry> On successful completion, an <command>UPDATE</> command returns a command
<term><computeroutput>UPDATE <replaceable class="parameter">count</replaceable></computeroutput></term> tag of the form
<listitem> <screen>
<para> UPDATE <replaceable class="parameter">count</replaceable>
Message returned if successful. The value <replaceable </screen>
class="parameter">count</replaceable> is the number of rows The <replaceable class="parameter">count</replaceable> is the number
updated. If <replaceable class="parameter">count</replaceable> of rows updated. If <replaceable class="parameter">count</replaceable> is
is 0, no rows were updated. 0, no rows matched the <replaceable
</para> class="parameter">condition</replaceable> (this is not considered
</listitem> an error).
</varlistentry> </para>
</variablelist>
</refsect1> </refsect1>
<refsect1> <refsect1>

96
doc/src/sgml/ref/vacuum.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -143,49 +143,13 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Outputs</title>
<variablelist> <para>
<varlistentry> When <literal>VERBOSE</> is specified, <command>VACUUM</> emits
<term><computeroutput>VACUUM</computeroutput></term> progress messages to indicate which table is currently being
<listitem> processed. Various statistics about the tables are printed as well.
<para> </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>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -216,25 +180,37 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
<title>Examples</title> <title>Examples</title>
<para> <para>
The following is an example from running <command>VACUUM</command> on a table The following is an example from running <command>VACUUM</command> on a
in the regression database: table in the regression database:
<programlisting> <programlisting>
=> VACUUM VERBOSE ANALYZE onek; regression=# VACUUM VERBOSE ANALYZE onek;
INFO: --Relation onek-- INFO: vacuuming "public.onek"
INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000. INFO: index "onek_unique1" now contains 1000 tuples in 14 pages
CPU 0.00s/0.11u sec elapsed 0.12 sec. DETAIL: 3000 index tuples were removed.
INFO: Index onek_unique2: Pages 16; Tuples 1000: Deleted 3000. 0 index pages have been deleted, 0 are currently reusable.
CPU 0.00s/0.10u sec elapsed 0.10 sec. CPU 0.01s/0.08u sec elapsed 0.18 sec.
INFO: Index onek_hundred: Pages 13; Tuples 1000: Deleted 3000. INFO: index "onek_unique2" now contains 1000 tuples in 16 pages
CPU 0.00s/0.10u sec elapsed 0.10 sec. DETAIL: 3000 index tuples were removed.
INFO: Index onek_stringu1: Pages 31; Tuples 1000: Deleted 3000. 0 index pages have been deleted, 0 are currently reusable.
CPU 0.01s/0.09u sec elapsed 0.10 sec. CPU 0.00s/0.07u sec elapsed 0.23 sec.
INFO: Removed 3000 tuples in 70 pages. INFO: index "onek_hundred" now contains 1000 tuples in 13 pages
CPU 0.02s/0.04u sec elapsed 0.07 sec. DETAIL: 3000 index tuples were removed.
INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0. 0 index pages have been deleted, 0 are currently reusable.
Total CPU 0.05s/0.45u sec elapsed 0.59 sec. CPU 0.01s/0.08u sec elapsed 0.17 sec.
INFO: Analyzing onek 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 VACUUM
</programlisting> </programlisting>
</para> </para>

45
doc/src/sgml/ref/vacuumdb.sgml
View File

@ -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 PostgreSQL documentation
--> -->
@ -55,13 +55,19 @@ PostgreSQL documentation
<application>vacuumdb</application> is a wrapper around the SQL <application>vacuumdb</application> is a wrapper around the SQL
command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">. command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">.
There is no effective difference between vacuuming databases via There is no effective difference between vacuuming databases via
this or other methods. The database server must be running at the this utility and via other methods for accessing the server.
targeted host. Also, any default settings and environment </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 variables used by the <application>libpq</application> front-end
library will apply. library will apply.
</para> </para>
<para> <para>
<application>vacuumdb</application> might need to connect several <application>vacuumdb</application> might need to connect several
times to the <productname>PostgreSQL</productname> server, asking times to the <productname>PostgreSQL</productname> server, asking
@ -230,37 +236,6 @@ PostgreSQL documentation
</refsect1> </refsect1>
<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> <refsect1>
<title>Environment</title> <title>Environment</title>