database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-12-21 05:21:08 +03:00
Code Activity

Clean up to ensure tag completion as required by the newest versions

Browse Source 
of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
This commit is contained in:
Thomas G. Lockhart
1998-12-29 02:24:47 +00:00
parent 6d7735e7f0
commit a75f2d21a8
115 changed files with 10587 additions and 8000 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
doc/src/sgml/ref/abort.sgml
View File

@@ -12,6 +12,7 @@ ABORT
<REFPURPOSE>
Aborts the current transaction
</REFPURPOSE>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-27</DATE>
@@ -29,6 +30,7 @@ Inputs
</TITLE>
<PARA>
None.
</para>
</REFSECT2>
@@ -49,7 +51,9 @@ Outputs
<LISTITEM>
<PARA>
Message returned if successful.
</para>
</listitem>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state
@@ -58,10 +62,11 @@ ABORT
<LISTITEM>
<PARA>
If there is not any transaction currently in progress.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -78,7 +83,7 @@ Description
This command is identical
in behavior to the <acronym>SQL92</acronym> command <command>ROLLBACK</command>,
and is present only for historical reasons.
</para>
<REFSECT2 ID="R2-SQL-ABORT-3">
<REFSECT2INFO>
<DATE>1998-09-27</DATE>
@@ -89,7 +94,8 @@ Notes
<para>
Use the <command>COMMIT</command> statement to successfully
terminate a transaction.
</para>
</refsect2>
</REFSECT1>
<REFSECT1 ID="R1-SQL-ABORT-2">
@@ -102,6 +108,7 @@ Usage
--
ABORT WORK;
</ProgramListing>
</para>
</REFSECT1>
@@ -109,7 +116,6 @@ ABORT WORK;
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-ABORT-4">
<REFSECT2INFO>
@@ -123,5 +129,7 @@ This command is a <productname>Postgres</productname> extension present
for historical reasons. <command>ROLLBACK</command> is the <acronym>SQL92</acronym>
equivalent command.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@ ALTER TABLE
<REFPURPOSE>
Modifies table properties
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -89,7 +90,7 @@ Inputs
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-ALTERTABLE-2">
@@ -131,9 +132,11 @@ Outputs
<LISTITEM>
<PARA>
Message returned if table or column is not available.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -153,6 +156,7 @@ Description
the affected table. Thus, the table or column will
remain of the same type and size after this command is
executed.
</para>
<PARA>
You must own the table in order to change its schema.
</PARA>
@@ -166,18 +170,19 @@ Notes
</TITLE>
<PARA>
The keyword COLUMN is noise and can be omitted.
</para>
<PARA>
<Quote>[*]</Quote> following a name of a table indicates that statement
should be run over that table and all tables below it in the
inheritance hierarchy.
The <citetitle>PostgreSQL User's Guide</citetitle> has further
information on inheritance.
</para>
<PARA>
Refer to CREATE TABLE for a further description
of valid arguments.
</para>
</REFSECT2>
</REFSECT1>
@@ -190,18 +195,21 @@ Usage
<ProgramListing>
ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
</ProgramListing>
</para>
<PARA>
To rename an existing column:
<ProgramListing>
ALTER TABLE distributors RENAME COLUMN address TO city;
</ProgramListing>
</para>
<PARA>
To rename an existing table:
<ProgramListing>
ALTER TABLE distributors RENAME TO suppliers;
</ProgramListing>
</para>
</REFSECT1>
@@ -220,11 +228,13 @@ SQL92
<PARA>
<command>ALTER TABLE/RENAME</command>
is a <productname>Postgres</productname> language extension.
</para>
<PARA>
SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
statement which are not yet directly supported by
<ProductName>Postgres</ProductName>:
</para>
<VARIABLELIST>
<VARLISTENTRY>
@@ -247,6 +257,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ]
the new definition. If any constraints on this column already
exist, they will be retained using a boolean AND with the new
constraint.
</para>
<PARA>
Currently, to set new default constraints on an existing column
@@ -284,6 +295,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
constraints can be destroyed.
If CASCADE is specified, Any constraints that are dependent on
this constraint are also dropped.
</para>
<PARA>
Currently, to remove a default value or constraints on an
@@ -295,7 +307,10 @@ DROP TABLE distributors;
CREATE TABLE distributors AS SELECT * FROM temp;
DROP TABLE temp;
</ProgramListing>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<Synopsis>
@@ -310,6 +325,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
objects can be destroyed.
If CASCADE is specified, all objects that are dependent on
this column are also dropped.
</para>
<PARA>
Currently, to remove an existing column the table must be
@@ -326,5 +342,9 @@ INSERT INTO distributors SELECT * FROM temp;
DROP TABLE temp;
</ProgramListing>
</PARA>
</listitem>
</varlistentry>
</VARIABLELIST>
</refsect2>
</refsect1>
</REFENTRY>

57
doc/src/sgml/ref/alter_user.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Modifies user account information
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
@@ -91,32 +92,35 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>ALTER USER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the alteration was successful.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Error message returned if the user specified doesn't
exist.
</variablelist>
</REFSECT2>
</REFSYNOPSISDIV>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>ALTER USER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the alteration was successful.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Error message returned if the user specified doesn't
exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-ALTERUSER-1">
<REFSECT1INFO>
<DATE>1998-09-08</DATE>
@@ -223,6 +227,7 @@ ALTER USER miriam IN GROUP sales, payroll;
The standard leaves
the definition of users to the implementation.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>

22
doc/src/sgml/ref/begin.sgml
View File

@@ -13,7 +13,7 @@
Begins a transaction
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
@@ -30,7 +30,8 @@ BEGIN [ WORK | TRANSACTION ]
Inputs
</TITLE>
<PARA>
None
None
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-BEGINWORK-2">
@@ -58,11 +59,14 @@ BEGIN [ WORK | TRANSACTION ]
<returnvalue>NOTICE: BeginTransactionBlock and not in default state</returnvalue>
</TERM>
<LISTITEM>
<PARA>
This indicates that a transaction was already in progress.
The current transaction is not affected.
</VARIABLELIST>
<PARA>
This indicates that a transaction was already in progress.
The current transaction is not affected.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -109,6 +113,7 @@ The current transaction is not affected.
to terminate a transaction.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-BEGINWORK-2">
<TITLE>
@@ -119,6 +124,7 @@ The current transaction is not affected.
<ProgramListing>
BEGIN WORK;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-BEGINWORK-3">
@@ -128,7 +134,7 @@ BEGIN WORK;
<PARA>
<command>BEGIN</command>
is a <productname>Postgres</productname> language extension.
</para>
<REFSECT2 ID="R2-SQL-BEGINWORK-4">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Close a cursor
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
@@ -41,6 +41,7 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CLOSE-2">
@@ -71,9 +72,11 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
This warning is given if
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not
declared or has already been closed.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

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

@@ -12,14 +12,14 @@
<REFPURPOSE>
Gives storage clustering advice to the backend
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CLUSTER-1">
<REFSECT2INFO>
@@ -102,9 +102,9 @@ CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE C
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CLUSTER-1">
@@ -139,7 +139,7 @@ to cluster the class specified
<TITLE>
Notes
</TITLE>
<PARA>
<para>
The table is actually copied to a temporary table in index
order, then renamed back to the original name. For this
@@ -191,39 +191,40 @@ SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ...
will not be preserved. From then on, <command>CLUSTER</command> should be
fast because most of the heap data has already been
ordered, and the existing index is used.
</para>
</para>
</refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-CLUSTER-2">
<TITLE>
Usage
</TITLE>
<PARA>
Cluster the employees relation on the basis of its salary attribute
</PARA>
<ProgramListing>
CLUSTER emp_ind ON emp
</ProgramListing>
<TITLE>
Usage
</TITLE>
<PARA>
Cluster the employees relation on the basis of its salary attribute
</PARA>
<ProgramListing>
CLUSTER emp_ind ON emp
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CLUSTER-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CLUSTER-4">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
Compatibility
</TITLE>
<PARA>
There is no <command>CLUSTER</command> statement in SQL92.
</PARA>
</refsect2>
<REFSECT2 ID="R2-SQL-CLUSTER-4">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>CLUSTER</command> statement in SQL92.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Commits the current transaction
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
@@ -30,8 +30,8 @@ COMMIT [ WORK | TRANSACTION ]
Inputs
</TITLE>
<PARA>
None
None
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-COMMIT-2">
@@ -57,12 +57,15 @@ Message returned if the transaction is successfully committed.
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE EndTransactionBlock and not inprogress/abort state</returnvalue>
</TERM>
<LISTITEM>
<PARA>
If there is no transaction in progress.
</VARIABLELIST>
</TERM>
<LISTITEM>
<PARA>
If there is no transaction in progress.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

115
doc/src/sgml/ref/copy.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Copies data between files and tables
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
@@ -92,20 +93,21 @@ Specifies that input comes from a pipe or terminal.
<LISTITEM>
<PARA>
Specifies that output goes to a pipe or terminal.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">delimiter</replaceable>
</TERM>
<LISTITEM>
<PARA>
A character that delimits the input or output fields.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">delimiter</replaceable>
</TERM>
<LISTITEM>
<PARA>
A character that delimits the input or output fields.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-COPY-2">
@@ -131,12 +133,15 @@ Specifies that output goes to a pipe or terminal.
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: <replaceable>error message</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The copy failed for the reason stated in the error message.
</VARIABLELIST>
</TERM>
<LISTITEM>
<PARA>
The copy failed for the reason stated in the error message.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -147,19 +152,18 @@ Specifies that output goes to a pipe or terminal.
<TITLE>
Description
</TITLE>
<PARA>
<para>
<command>COPY</command> moves data between
<productname>Postgres</productname> tables and
standard Unix files.
<para>
<command>COPY</command> instructs
the <productname>Postgres</productname> backend
to directly read from or write to a file. The file must be directly visible to
the backend and the name must be specified from the viewpoint of the backend.
If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
the backend.
<command>COPY</command> instructs
the <productname>Postgres</productname> backend
to directly read from or write to a file. The file must be directly visible to
the backend and the name must be specified from the viewpoint of the backend.
If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
the backend.
</para>
<REFSECT2 ID="R2-SQL-COPY-3">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
@@ -167,41 +171,42 @@ the backend.
<TITLE>
Notes
</TITLE>
<para>
The BINARY keyword will force all data to be
stored/read as binary objects rather than as text. It is
somewhat faster than the normal copy command, but is not
generally portable, and the files generated are somewhat larger,
although this factor is highly dependent on the data itself. By
default, a text copy uses a tab ("\t") character as a delimiter.
The delimiter may also be changed to any other single character
with the keyword phrase USING DELIMITERS. Characters
in data fields which happen to match the delimiter character will
be quoted.
</para>
<para>
<para>
The BINARY keyword will force all data to be
stored/read as binary objects rather than as text. It is
somewhat faster than the normal copy command, but is not
generally portable, and the files generated are somewhat larger,
although this factor is highly dependent on the data itself. By
default, a text copy uses a tab ("\t") character as a delimiter.
The delimiter may also be changed to any other single character
with the keyword phrase USING DELIMITERS. Characters
in data fields which happen to match the delimiter character will
be quoted.
</para>
<para>
You must have select access on any table whose values are read by
<command>COPY</command>, and either insert or update access to a
table into which values are being inserted by <command>COPY</command>.
The backend also needs appropriate Unix permissions for any file read
or written by <command>COPY</command>.
</para>
<para>
</para>
<para>
The keyword phrase USING DELIMITERS specifies a single character
to be used for all delimiters between columns. If multiple characters
are specified in the delimiter string, only the first character is
to be used for all delimiters between columns. If multiple characters
are specified in the delimiter string, only the first character is
used.
<tip>
<para>
Do not confuse <command>COPY</command> with the
<application>psql</application> instruction <command>\copy</command>.
</tip>
<tip>
<para>
Do not confuse <command>COPY</command> with the
<application>psql</application> instruction <command>\copy</command>.
</para>
</tip>
</para>
</REFSECT2>
</refsect1>
<refsect1 ID="R1-SQL-COPY-2">
<refsect1info>
<date>1998-05-04</date>

171
doc/src/sgml/ref/create_aggregate.sgml
View File

@@ -13,6 +13,7 @@
<REFPURPOSE>
Defines a new aggregate function
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
@@ -150,11 +151,11 @@ The initial value for the first transition function argument.
The initial value for the second transition function argument.
</para>
</listitem>
</varlistentry>
</variablelist>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
<REFSECT2INFO>
<DATE>1998-09-09</DATE>
@@ -163,20 +164,23 @@ The initial value for the second transition function argument.
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the command completes successfully.
</VARIABLELIST>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1">
<REFSECT1INFO>
<DATE>1998-09-09</DATE>
@@ -184,80 +188,80 @@ The initial value for the second transition function argument.
<TITLE>
Description
</TITLE>
<para>
<command>CREATE AGGREGATE</command>
allows a user or programmer to extend <productname>Postgres</productname>
functionality by defining new aggregate functions. Some aggregate functions
for base types such as <function>min(int4)</function>
and <function>avg(float8)</function> are already provided in the base
distribution. If one defines new types or needs an aggregate function not
already provided then <command>CREATE AGGREGATE</command>
can be used to provide the desired features.
<para>
<command>CREATE AGGREGATE</command>
allows a user or programmer to extend <productname>Postgres</productname>
functionality by defining new aggregate functions. Some aggregate functions
for base types such as <function>min(int4)</function>
and <function>avg(float8)</function> are already provided in the base
distribution. If one defines new types or needs an aggregate function not
already provided then <command>CREATE AGGREGATE</command>
can be used to provide the desired features.
</para>
<PARA>
An aggregate function can require up to three functions, two
state transition functions,
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
</programlisting>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
</programlisting>
and a final calculation function,
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
</programlisting>
<para>
<productname>Postgres</productname> creates up to two temporary variables
(referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
to hold intermediate results used as arguments to the transition functions.
<para>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
</programlisting>
</para>
<para>
<productname>Postgres</productname> creates up to two temporary variables
(referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
to hold intermediate results used as arguments to the transition functions.
</para>
<para>
These transition functions are required to have the following properties:
<itemizedlist>
<listitem>
<para>
The arguments to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
The return value must be of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and will be used as the first argument in the next call to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
The return value must be of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and will be used as the first argument in the next call to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
</para>
</listitem>
<listitem>
<para>
The argument and return value of
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para>
</listitem>
<listitem>
<para>
The arguments to the final-calculation-function
must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
and its return value must
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
and its return value must
be a <productname>Postgres</productname>
base type (not necessarily
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
which had been specified for BASETYPE).
base type (not necessarily
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
which had been specified for BASETYPE).
</para>
</listitem>
<listitem>
@@ -269,7 +273,7 @@ which had been specified for BASETYPE).
</listitem>
</itemizedlist>
</PARA>
<para>
An aggregate function may also require one or two initial conditions,
one for
@@ -301,41 +305,42 @@ which had been specified for BASETYPE).
well as a FINALFUNC (a division function) to produce its
answer. In any case, at least one state function must be
defined, and any SFUNC2 must have a corresponding INITCOND2.
</para>
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
<TITLE>
Usage
</TITLE>
<PARA>
Refer to the chapter on aggregate functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
on aggregate functions for
complete examples of usage.
Refer to the chapter on aggregate functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
on aggregate functions for
complete examples of usage.
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
<REFSECT2INFO>
<DATE>1998-09-09</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
<command>CREATE AGGREGATE</command>
is a <productname>Postgres</productname> language extension.
is a <productname>Postgres</productname> language extension.
There is no <command>CREATE AGGREGATE</command> in SQL92.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Creates a new database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -51,12 +52,13 @@ CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ WITH LOCATIO
(e.g. '<filename>/usr/local/pgsql/data</filename>').
In either case, the location must be pre-configured
by <command>initlocation</command>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
@@ -90,14 +92,17 @@ CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ WITH LOCATIO
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: Unable to create database directory <replaceable class="parameter">directory</replaceable>
</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
There was a problem with creating the required directory; this operation will
need permissions for the <literal>postgres</literal> user on the specified location.
</VARIABLELIST>
</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
There was a problem with creating the required directory; this operation will
need permissions for the <literal>postgres</literal> user on the specified location.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -128,7 +133,8 @@ need permissions for the <literal>postgres</literal> user on the specified locat
Use <command>DROP DATABASE</command> to remove a database.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEDATABASE-2">
<TITLE>
Usage
@@ -137,27 +143,27 @@ need permissions for the <literal>postgres</literal> user on the specified locat
To create a new database:
</PARA>
<ProgramListing>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</ProgramListing>
<PARA>
To create a new database in an alternate area <filename>~/private_db</filename>:
</PARA>
<ProgramListing>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: template1
<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
<computeroutput>CREATEDB</computeroutput>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: template1
<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
<computeroutput>CREATEDB</computeroutput>
</ProgramListing>
</REFSECT1>
@@ -190,7 +196,6 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO>

126
doc/src/sgml/ref/create_function.sgml
View File

@@ -12,7 +12,7 @@
<REFPURPOSE>
Defines a new function
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
@@ -66,30 +66,31 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">path</replaceable>
</TERM>
<LISTITEM>
<PARA>
May be either an SQL-query or an absolute path to an
object file.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">langname</replaceable>
</TERM>
<LISTITEM>
<PARA>
may be '<literal>C</literal>', '<literal>sql</literal>',
'<literal>internal</literal>'
or '<replaceable class="parameter">plname</replaceable>',
where '<replaceable class="parameter">plname</replaceable>'
is the name of a created procedural
language. See <command>CREATE LANGUAGE</command> for details.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</TERM>
<LISTITEM>
<PARA>
May be either an SQL-query or an absolute path to an
object file.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">langname</replaceable>
</TERM>
<LISTITEM>
<PARA>
may be '<literal>C</literal>', '<literal>sql</literal>',
'<literal>internal</literal>'
or '<replaceable class="parameter">plname</replaceable>',
where '<replaceable class="parameter">plname</replaceable>'
is the name of a created procedural
language. See <command>CREATE LANGUAGE</command> for details.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
@@ -100,16 +101,20 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This is returned if the command completes successfully.
</VARIABLELIST>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This is returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -122,8 +127,8 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
</TITLE>
<PARA>
<command>CREATE FUNCTION</command> allows a
<productname>Postgres</productname> user
to register a function
<productname>Postgres</productname> user
to register a function
with a database. Subsequently, this user is treated as the
owner of the function.
</PARA>
@@ -138,13 +143,14 @@ to register a function
<PARA>
Refer to the chapter on functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
for further information.
for further information.
</PARA>
<PARA>
Use <command>DROP FUNCTION</command>
to drop user-defined functions.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEFUNCTION-2">
<TITLE>
@@ -154,17 +160,17 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
To create a simple SQL function:
</PARA>
<ProgramListing>
CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql';
SELECT one() AS answer;
<computeroutput>
answer
------
1
</computeroutput>
CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql';
SELECT one() AS answer;
<computeroutput>
answer
------
1
</computeroutput>
</ProgramListing>
<para>
To create a C function, calling a routine from a user-created
@@ -173,18 +179,18 @@ answer
is correct. It is intended for use in a CHECK contraint.
</para>
<programlisting>
<userinput>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
<userinput>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
CREATE TABLE product
(
id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput>
CREATE TABLE product
(
id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput>
</programlisting>
</REFSECT1>

77
doc/src/sgml/ref/create_index.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Constructs a secondary index
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
@@ -139,21 +140,21 @@ SELECT am.amname AS acc_name,
</programlisting>
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">func_name</replaceable>
</TERM>
<LISTITEM>
<PARA>
A user-defined function, which returns a value that can
be indexed.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">func_name</replaceable>
</TERM>
<LISTITEM>
<PARA>
A user-defined function, which returns a value that can
be indexed.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEINDEX-2">
@@ -178,15 +179,17 @@ SELECT am.amname AS acc_name,
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This error occurs if it is impossible to create the index.
</VARIABLELIST>
<TERM>
<ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This error occurs if it is impossible to create the index.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -198,17 +201,18 @@ SELECT am.amname AS acc_name,
Description
</TITLE>
<PARA>
<command>CREATE INDEX</command> constructs an index
<replaceable class="parameter">index_name</replaceable>.
on the specified
<replaceable class="parameter">table</replaceable>.
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</tip>
<command>CREATE INDEX</command> constructs an index
<replaceable class="parameter">index_name</replaceable>.
on the specified
<replaceable class="parameter">table</replaceable>.
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</para>
</tip>
</para>
<para>
In the first syntax shown above, the key fields for the
index are specified as column names; a column may also have
@@ -247,7 +251,8 @@ But inappropriate use will result in slower performance.
to remove an index.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEINDEX-2">
<TITLE>
Usage

77
doc/src/sgml/ref/create_language.sgml
View File

@@ -12,7 +12,7 @@
<REFPURPOSE>
Defines a new language for functions
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
@@ -75,25 +75,26 @@ superuser privilege can use
procedures.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">comment</replaceable>
</TERM>
<LISTITEM>
<PARA>
The <function>LANCOMPILER</function> argument is the
string that will be
inserted in the <literal>LANCOMPILER</literal> attribute
of the new
<filename>pg_language</filename> entry. At present,
<productname>Postgres</productname> does not use
this attribute in any way.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">comment</replaceable>
</TERM>
<LISTITEM>
<PARA>
The <function>LANCOMPILER</function> argument is the
string that will be
inserted in the <literal>LANCOMPILER</literal> attribute
of the new
<filename>pg_language</filename> entry. At present,
<productname>Postgres</productname> does not use
this attribute in any way.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-2">
@@ -117,15 +118,19 @@ superuser privilege can use
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This error is returned if the function
<replaceable class="parameter">funcname</replaceable>()
is not found.
</VARIABLELIST>
<TERM>
<ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This error is returned if the function
<replaceable class="parameter">funcname</replaceable>()
is not found.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -206,6 +211,7 @@ Subsequently, functions and
file or anything else that tells the call handler what to
do in detail.
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
<REFSECT2INFO>
@@ -320,19 +326,20 @@ sql |postgres
of the dots to complete the PL call handler.
See <command>CREATE FUNCTION</command> for information on how to compile
it into a loadable module
.</para>
.</para>
<para>
The following commands then register the sample procedural
language:
<programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS opaque
<programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS opaque
AS '/usr/local/pgsql/lib/plsample.so'
LANGUAGE 'C';
CREATE PROCEDURAL LANGUAGE 'plsample'
CREATE PROCEDURAL LANGUAGE 'plsample'
HANDLER plsample_call_handler
LANCOMPILER 'PL/Sample';
</programlisting>
</programlisting>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-7">

152
doc/src/sgml/ref/create_operator.sgml
View File

@@ -12,7 +12,7 @@
<REFPURPOSE>
Defines a new user operator
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
@@ -155,16 +155,19 @@ Operator to use for sorting.
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the operator is successfully created.
</VARIABLELIST>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CREATE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the operator is successfully created.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -176,25 +179,25 @@ Operator to use for sorting.
Description
</TITLE>
<PARA>
<command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>.
The user who defines an operator becomes its owner.
</para>
<para>
The operator <replaceable class="parameter">name</replaceable>
is a sequence of up to thirty two (32) characters in any combination
from the following:
<literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ & | ` ? $ :
</literallayout>
<note>
<para>
No alphabetic characters are allowed in an operator name.
This enables <productname>Postgres</productname> to parse SQL input
into tokens without requiring spaces between each token.
</note>
</para>
<command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>.
The user who defines an operator becomes its owner.
</para>
<para>
The operator <replaceable class="parameter">name</replaceable>
is a sequence of up to thirty two (32) characters in any combination
from the following:
<literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ & | ` ? $ :
</literallayout>
<note>
<para>
No alphabetic characters are allowed in an operator name.
This enables <productname>Postgres</productname> to parse SQL input
into tokens without requiring spaces between each token.
</para>
</note>
</para>
<para>
The operator "!=" is mapped to "&lt;&gt;" on input, so they are
therefore equivalent.
@@ -206,26 +209,26 @@ into tokens without requiring spaces between each token.
unary operators only RIGHTARG should be defined.
</para>
<para>
Also, the
<replaceable class="parameter">func_name</replaceable> procedure must have
Also, the
<replaceable class="parameter">func_name</replaceable> procedure must have
been previously defined using <command>CREATE FUNCTION</command> and must
be defined to accept the correct number of arguments
(either one or two).
(either one or two).
</para>
<para>
The commutator operator is present so that
<productname>Postgres</productname> can
<productname>Postgres</productname> can
reverse the order of the operands if it wishes.
For example, the operator area-less-than, &lt;&lt;&lt;,
would have a commutator
operator, area-greater-than, &gt;&gt;&gt;.
Hence, the query optimizer could freely convert:
For example, the operator area-less-than, &lt;&lt;&lt;,
would have a commutator
operator, area-greater-than, &gt;&gt;&gt;.
Hence, the query optimizer could freely convert:
<programlisting>
"0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description
"0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description
</programlisting>
to
<programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
</para>
<para>
This allows the execution code to always use the latter
@@ -233,21 +236,21 @@ MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
what.
</para>
<para>
Suppose that an
Suppose that an
operator, area-equal, ===, exists, as well as an area not
equal, !==.
The negator operator allows the query optimizer to convert
<programlisting>
NOT MYBOXES.description === "0,0,1,1"::box
NOT MYBOXES.description === "0,0,1,1"::box
</programlisting>
to
<programlisting>
MYBOXES.description !== "0,0,1,1"::box
MYBOXES.description !== "0,0,1,1"::box
</programlisting>
</para>
<para>
If a commutator operator name is supplied,
<productname>Postgres</productname>
<productname>Postgres</productname>
searches for it in the catalog. If it is found and it
does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator
@@ -264,22 +267,22 @@ MYBOXES.description !== "0,0,1,1"::box
<para>
The next two specifications are present to support the
query optimizer in performing joins.
<productname>Postgres</productname> can always
<productname>Postgres</productname> can always
evaluate a join (i.e., processing a clause with two tuple
variables separated by an operator that returns a boolean)
by iterative substitution [WONG76].
In addition, <productname>Postgres</productname>
In addition, <productname>Postgres</productname>
is planning on implementing a hash-join algorithm along
the lines of [SHAP86]; however, it must know whether this
strategy is applicable.
For example, a hash-join
For example, a hash-join
algorithm is usable for a clause of the form:
<programlisting>
MYBOXES.description === MYBOXES2.description
MYBOXES.description === MYBOXES2.description
</programlisting>
but not for a clause of the form:
<programlisting>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
</programlisting>
The HASHES flag gives the needed information to the query
optimizer concerning whether a hash join strategy is
@@ -292,13 +295,13 @@ MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
sort both relations using the operator, &lt;&lt;&lt;. On the other
hand, merge-sort is not usable with the clause:
<programlisting>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
</programlisting>
</para>
<para>
If other join strategies are found to be practical,
<productname>Postgres</productname>
will change the optimizer and run-time system to use
<productname>Postgres</productname>
will change the optimizer and run-time system to use
them and will require additional specification when an
operator is defined. Fortunately, the research community
invents new join strategies infrequently, and the added
@@ -310,14 +313,14 @@ MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
the query optimizer can estimate result sizes. If a
clause of the form:
<programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
</programlisting>
is present in the qualification,
then <productname>Postgres</productname> may have to
then <productname>Postgres</productname> may have to
estimate the fraction of the instances in MYBOXES that
satisfy the clause. The function
<replaceable class="parameter">res_proc</replaceable>
must be a registered function (meaning it is already defined using
<replaceable class="parameter">res_proc</replaceable>
must be a registered function (meaning it is already defined using
define function(l)) which accepts one argument of the correct
data type and returns a floating point number. The
query optimizer simply calls this function, passing the
@@ -335,14 +338,14 @@ MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
<para>
The difference between the function
<programlisting>
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
</programlisting>
and the operator
<programlisting>
MYBOXES.description === "0,0,1,1"::box
MYBOXES.description === "0,0,1,1"::box
</programlisting>
is that <productname>Postgres</productname>
attempts to optimize operators and can
attempts to optimize operators and can
decide to use an index to restrict the search space when
operators are involved. However, there is no attempt to
optimize functions, and they are performed by brute force.
@@ -359,12 +362,13 @@ MYBOXES.description === "0,0,1,1"::box
</TITLE>
<PARA>
Refer to the chapter on operators in the
<citetitle>PostgreSQL User's Guide</citetitle>
<citetitle>PostgreSQL User's Guide</citetitle>
for further information.
Refer to <command>DROP OPERATOR</command> to delete
user-defined operators from a database.
user-defined operators from a database.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-2">
<TITLE>
@@ -374,19 +378,17 @@ user-defined operators from a database.
area-equality, for the BOX data type.
</PARA>
<ProgramListing>
CREATE OPERATOR === (
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
HASHES,
JOIN = area-join-procedure,
SORT = <<<, <<<)
</ProgramListing>
CREATE OPERATOR === (
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
HASHES,
JOIN = area-join-procedure,
SORT = <<<, <<<)
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-3">

15
doc/src/sgml/ref/create_rule.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Defines a new rule
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-11</DATE>
@@ -110,10 +111,11 @@ CREATE RULE <replaceable class="parameter">name</replaceable>
<LISTITEM>
<PARA>
Message returned if the rule is successfully created.
</VARLISTENTRY>
</VARIABLELIST>
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -216,8 +218,8 @@ select * from EMP
<para>
You must have rule definition access to a class in order
to define a rule on it. Use <command>GRANT</command>
and <command>REVOKE</command> to change permissions.
and <command>REVOKE</command> to change permissions.
</PARA>
</REFSECT2>
</refsect1>
@@ -307,6 +309,7 @@ create rule example_5 is
fail if the rule plus its various internal representations
exceed some value that is on the order of one page (8KB).
</PARA>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATERULE-4">
<TITLE>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Creates a new sequence number generator
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -197,8 +197,11 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
<LISTITEM>
<PARA>
If the minimum and maximum values are inconsistant.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -254,27 +257,28 @@ SELECT last_value FROM sequence_name;
</para>
<caution>
<para>
Unexpected results may be obtained if a cache setting greater than one
is used for a sequence object that will be used concurrently by multiple
backends. Each backend will allocate "cache" successive sequence values
during one access to the sequence object and increase the sequence
object's last_value accordingly. Then, the next cache-1 uses of nextval
within that backend simply return the preallocated values without touching
the shared object. So, numbers allocated but not used in the current session
will be lost. Furthermore, although multiple backends are guaranteed to
allocate distinct sequence values, the values may be generated out of
sequence when all the backends are considered. (For example, with a cache
setting of 10, backend A might reserve values 1..10 and return nextval=1,
then
backend B might reserve values 11..20 and return nextval=11 before backend
A has generated nextval=2.) Thus, with a cache setting of one it is safe
to assume that nextval values are generated sequentially; with a cache
setting greater than one you should only assume that the nextval values
are all distinct, not that they are generated purely sequentially.
Also, last_value will reflect the latest value reserved by any backend,
whether or not it has yet been returned by nextval.
</caution>
<para>
Unexpected results may be obtained if a cache setting greater than one
is used for a sequence object that will be used concurrently by multiple
backends. Each backend will allocate "cache" successive sequence values
during one access to the sequence object and increase the sequence
object's last_value accordingly. Then, the next cache-1 uses of nextval
within that backend simply return the preallocated values without touching
the shared object. So, numbers allocated but not used in the current session
will be lost. Furthermore, although multiple backends are guaranteed to
allocate distinct sequence values, the values may be generated out of
sequence when all the backends are considered. (For example, with a cache
setting of 10, backend A might reserve values 1..10 and return nextval=1,
then
backend B might reserve values 11..20 and return nextval=11 before backend
A has generated nextval=2.) Thus, with a cache setting of one it is safe
to assume that nextval values are generated sequentially; with a cache
setting greater than one you should only assume that the nextval values
are all distinct, not that they are generated purely sequentially.
Also, last_value will reflect the latest value reserved by any backend,
whether or not it has yet been returned by nextval.
</para>
</caution>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
<REFSECT2INFO>
@@ -324,16 +328,16 @@ INSERT INTO distributors VALUES (NEXTVAL('serial'),'nothing');
<para>
Set the sequence value after a COPY FROM:
<programlisting>
CREATE FUNCTION distributors_id_max() RETURNS INT4
AS 'SELECT max(id) FROM distributors'
LANGUAGE 'sql';
BEGIN;
COPY distributors FROM 'input_file';
SELECT setval('serial', distributors_id_max());
END;
CREATE FUNCTION distributors_id_max() RETURNS INT4
AS 'SELECT max(id) FROM distributors'
LANGUAGE 'sql';
BEGIN;
COPY distributors FROM 'input_file';
SELECT setval('serial', distributors_id_max());
END;
</programlisting>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATESEQUENCE-3">
@@ -342,7 +346,7 @@ END;
</TITLE>
<PARA>
<command>CREATE SEQUENCE</command> is a <productname>Postgres</productname>
language extension.
language extension.
</PARA>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-4">

793
doc/src/sgml/ref/create_table.sgml
View File

File diff suppressed because it is too large Load Diff

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Creates a new trigger
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
@@ -92,8 +93,11 @@ CREATE TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> { BEFORE | AFTE
<LISTITEM>
<PARA>
This message is returned if the trigger is successfully created.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -147,31 +151,31 @@ CREATE TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> { BEFORE | AFTE
<PARA>
Refer to <command>DROP TRIGGER</command> for information on how to
remove triggers.
</PARA>
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATETRIGGER-2">
<TITLE>
Usage
</TITLE>
<PARA>
Check if the specified distributor code exists in the distributors
table before appending or updating a row in the table films:
Check if the specified distributor code exists in the distributors
table before appending or updating a row in the table films:
</PARA>
<ProgramListing>
CREATE TRIGGER if_dist_exists
BEFORE INSERT OR UPDATE ON films FOR EACH ROW
EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
CREATE TRIGGER if_dist_exists
BEFORE INSERT OR UPDATE ON films FOR EACH ROW
EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
</ProgramListing>
<PARA>
Before cancelling a distributor or updating its code, remove every
reference to the table films:
Before cancelling a distributor or updating its code, remove every
reference to the table films:
</PARA>
<ProgramListing>
CREATE TRIGGER if_film_exists
BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
CREATE TRIGGER if_film_exists
BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
</ProgramListing>
</REFSECT1>
@@ -190,25 +194,27 @@ CREATE TRIGGER if_film_exists
SQL92
</TITLE>
<PARA>
There is no <command>CREATE TRIGGER</command> in <acronym>SQL92</acronym>.
There is no <command>CREATE TRIGGER</command> in <acronym>SQL92</acronym>.
</PARA>
<PARA>
The second example above may also be done by using a FOREIGN KEY
constraint as in:
</PARA>
<ProgramListing>
CREATE TABLE distributors (
CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40),
CONSTRAINT if_film_exists
FOREIGN KEY(did) REFERENCES films
ON UPDATE CASCADE ON DELETE CASCADE
);
</ProgramListing>
FOREIGN KEY(did) REFERENCES films
ON UPDATE CASCADE ON DELETE CASCADE
);
</ProgramListing>
<PARA>
However, foreign keys are not yet implemented (as of version 6.4) in
<productname>Postgres</productname>.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file

30
doc/src/sgml/ref/create_type.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Defines a new base data type
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
@@ -175,9 +176,11 @@ EXTERNALLENGTH <replaceable class="parameter">externallength</replaceable>
<LISTITEM>
<PARA>
Message returned if the type is successfully created.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -290,11 +293,13 @@ it with the fact that the data is not present></comment>
length. If you need a larger type you must create a Large
Object type. The interface for these types is discussed
at length in
<comment>This section reference needs replacing</comment>
<comment>This section reference needs replacing</comment>
Section 7, the large object interface. The
length of all large object types is always VARIABLE.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
@@ -302,10 +307,10 @@ it with the fact that the data is not present></comment>
type in a class definition:
</para>
<programlisting>
CREATE TYPE box (INTERNALLENGTH = 8,
INPUT = my_procedure_1, OUTPUT = my_procedure_2)
CREATE TABLE myboxes (id INT4, description box)
CREATE TYPE box (INTERNALLENGTH = 8,
INPUT = my_procedure_1, OUTPUT = my_procedure_2)
CREATE TABLE myboxes (id INT4, description box)
</programlisting>
<para>
This command creates a variable length array type with
@@ -339,6 +344,7 @@ it with the fact that the data is not present></comment>
with an underscore.
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-CREATETYPE-3">
<REFSECT2INFO>
<DATE>1998-09-21</DATE>
@@ -351,9 +357,9 @@ it with the fact that the data is not present></comment>
</PARA>
<PARA>
See also <command>CREATE FUNCTION</command>,
<command>CREATE OPERATOR</command> and the chapter on Large Objects
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</para>
<command>CREATE OPERATOR</command> and the chapter on Large Objects
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</para>
</REFSECT2>
</refsect1>
@@ -362,7 +368,6 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATETYPE-4">
<REFSECT2INFO>
@@ -375,7 +380,8 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
<command>CREATE TYPE</command> is an <acronym>SQL3</acronym> statement.
</PARA>
</REFSECT2>
</REFSECT2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Creates account information for a new user
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
@@ -126,10 +127,11 @@ CREATE USER<REPLACEABLE CLASS="PARAMETER"> username</REPLACEABLE>
a NULL value is stored in "<filename>pg_shadow</filename>"
for this attribute,
and the login will be valid for all time.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEUSER-2">
@@ -151,17 +153,19 @@ CREATE USER<REPLACEABLE CLASS="PARAMETER"> username</REPLACEABLE>
Message returned if the command completes successfully.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: removeUser: user "<replaceable class="parameter">username</replaceable>" does not exist</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
if "<replaceable class="parameter">username</replaceable>" not found.
</PARA>
<comment>I don't understand this and I don't know how to get
this error message.</comment>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: removeUser: user "<replaceable class="parameter">username</replaceable>" does not exist</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
if "<replaceable class="parameter">username</replaceable>" not found.
</PARA>
<comment>I don't understand this and I don't know how to get
this error message.</comment>
</listitem>
</varlistentry>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -226,6 +230,7 @@ this error message.</comment>
+--------------------------+--------------------------+-------+
</programlisting>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEUSER-2">
<TITLE>
@@ -275,8 +280,10 @@ this error message.</comment>
SQL92
</TITLE>
<PARA>
There is no CREATE USER statement in SQL92.
There is no CREATE USER statement in SQL92.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Constructs a virtual table
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
@@ -55,6 +56,7 @@ An SQL query which will provide the columns and rows of the view.
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEVIEW-2">
@@ -104,8 +106,11 @@ An SQL query which will provide the columns and rows of the view.
<programlisting>
CREATE VIEW vista AS SELECT 'Hello World'::text
</programlisting>
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -146,7 +151,8 @@ An SQL query which will provide the columns and rows of the view.
Currently, views are read only.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEVIEW-2">
<TITLE>
Usage

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

@@ -1,223 +1,266 @@
<REFENTRY ID="APP-CREATEDB">
<REFMETA>
<REFENTRYTITLE>
<application>createdb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>createdb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
createdb [ <replaceable class="parameter">dbname</replaceable> ]
createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -D <replaceable class="parameter">datadir</replaceable> ]
[ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
<varlistentry>
<term>
-D <replaceable class="parameter">datadir</replaceable>
</term>
<listitem>
<para>
Specifies the alternate database location for this database installation.
This is the location of the installation system tables, not the location
of this specific database, which may be different.
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
unique among all <productname>Postgres</productname> databases in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
<REFSECT2 ID="R2-APP-CREATEDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createdb</application> will create files in the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the new database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
<application>createdb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have permission to create new databases.
Contact your <productname>Postgres</productname> site administrator.
<varlistentry>
<term>
ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The database already exists.
<varlistentry>
<term>
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>createdb</application> internally runs
CREATE DATABASE from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-CREATEDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createdb</application> creates a new
<productname>Postgres</productname> database.
The person who executes this command becomes
the database administrator, or <acronym>DBA</acronym>,
for this database and is the only
person, other than the <productname>Postgres</productname> super-user,
who can destroy it.
<para>
<application>createdb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createdb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-CREATEDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
createdb demo
</programlisting>
To create the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
createdb -p 5000 -h eden demo
</programlisting>
<REFMETA>
<REFENTRYTITLE>
<application>createdb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>createdb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
createdb [ <replaceable class="parameter">dbname</replaceable> ]
createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -D <replaceable class="parameter">datadir</replaceable> ]
[ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D <replaceable class="parameter">datadir</replaceable>
</term>
<listitem>
<para>
Specifies the alternate database location for this database installation.
This is the location of the installation system tables, not the location
of this specific database, which may be different.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
unique among all <productname>Postgres</productname> databases in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-CREATEDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createdb</application> will create files in the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the new database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
<application>createdb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
You do not have permission to create new databases.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
The database already exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
<application>createdb</application> internally runs
CREATE DATABASE from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-CREATEDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createdb</application> creates a new
<productname>Postgres</productname> database.
The person who executes this command becomes
the database administrator, or <acronym>DBA</acronym>,
for this database and is the only
person, other than the <productname>Postgres</productname> super-user,
who can destroy it.
</para>
<para>
<application>createdb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createdb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
</refsect1>
<REFSECT1 ID="R1-APP-CREATEDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
createdb demo
</programlisting>
To create the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
createdb -p 5000 -h eden demo
</programlisting>
</para>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Create a new <productname>Postgres</productname> user
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
@@ -23,215 +24,267 @@ createuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replac
[ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Allows the user to create databases.
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Forbids the user to create databases.
<varlistentry>
<term>
-i <replaceable class="parameter">userid</replaceable>
</term>
<listitem>
<para>
Specifies the numeric identifier to be associated with this user.
This identifier must be unique among all <productname>Postgres</productname> users, and is not required
to match the operating system UID.
You will be prompted for an identifier if none is specified on the command line,
and it will suggest an identifier matching the UID.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Allows the user to create other users.
<varlistentry>
<term>
-U
</term>
<listitem>
<para>
Forbids the user to create other users.
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be created.
This name must be unique among all <productname>Postgres</productname> users.
You will be prompted for a name if none is specified on the command line.
</variablelist>
<REFSECT2 ID="R2-APP-CREATEUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createuser</application> will add an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createuser: database access failed.
<listitem>
<para>
<application>createuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createuser: database access failed.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
<varlistentry>
<term>
createuser: <replaceable class="parameter">username</replaceable> cannot create users.
<listitem>
<para>
You do not have permission to create new users; contact your
<productname>Postgres</productname> site administrator.
<varlistentry>
<term>
createuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
<varlistentry>
<term>
database access failed
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>createuser</application> internally runs
CREATE USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-CREATEUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createuser</application> creates a
new <productname>Postgres</productname> user.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can create
new <productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can create users.
<para>
<application>createuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
Once invoked, <application>createuser</application>
will ask a series of questions to obtain parameters not specified on
the command line. The new user's database login name and a numeric
user identifier must be specified.
<note>
<para>
The <productname>Postgres</productname> user identifier
does not need to be the same as the user's Unix UID. However, typically
they are assigned to be the same.
</note>
<para>
You must also describe the privileges of the new user for security purposes.
Specifically, you will be asked whether the new user should be able to
act as <productname>Postgres</productname> super-user,
whether the new user may create new databases and whether the new user
is allowed to create other new users.
<REFSECT2 ID="R2-APP-CREATEUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Allows the user to create databases.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Forbids the user to create databases.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-i <replaceable class="parameter">userid</replaceable>
</term>
<listitem>
<para>
Specifies the numeric identifier to be associated with this user.
This identifier must be unique among all <productname>Postgres</productname> users, and is not required
to match the operating system UID.
You will be prompted for an identifier if none is specified on the command line,
and it will suggest an identifier matching the UID.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Allows the user to create other users.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-U
</term>
<listitem>
<para>
Forbids the user to create other users.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be created.
This name must be unique among all <productname>Postgres</productname> users.
You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-CREATEUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createuser</application> will add an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createuser: database access failed.
</term>
<listitem>
<para>
<application>createuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createuser: database access failed.
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
createuser: <replaceable class="parameter">username</replaceable> cannot create users.
</term>
<listitem>
<para>
You do not have permission to create new users; contact your
<productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
createuser: user "<replaceable class="parameter">username</replaceable>" already exists
</term>
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
database access failed
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
<application>createuser</application> internally runs
CREATE USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-CREATEUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createuser</application> creates a
new <productname>Postgres</productname> user.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can create
new <productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can create users.
</para>
<para>
<application>createuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
Once invoked, <application>createuser</application>
will ask a series of questions to obtain parameters not specified on
the command line. The new user's database login name and a numeric
user identifier must be specified.
</para>
<note>
<para>
The <productname>Postgres</productname> user identifier
does not need to be the same as the user's Unix UID. However, typically
they are assigned to be the same.
</para>
</note>
<para>
You must also describe the privileges of the new user for security purposes.
Specifically, you will be asked whether the new user should be able to
act as <productname>Postgres</productname> super-user,
whether the new user may create new databases and whether the new user
is allowed to create other new users.
</para>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Defines a cursor for table access
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-04</DATE>
@@ -180,11 +181,11 @@ ERROR: Named portals may only be used in begin/end transaction blocks
<LISTITEM>
<PARA>
This error occurs if the cursor is not declared within a transaction block.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -215,19 +216,20 @@ backend was built. Since
BINARY cursors give you back the data in the native binary
representation. So binary cursors will tend to be a
little faster since they suffer less conversion overhead.
<para>
</para>
<para>
As an example, if a query returns a value of one from an integer column,
you would get a string of '1' with a default cursor
whereas with a binary cursor you would get
a 4-byte value equal to control-A ('^A').
<caution>
<para>
BINARY cursors should be used carefully. User applications such
as <application>psql</application> are not aware of binary cursors
and expect data to come back in a text format.
</caution>
<caution>
<para>
BINARY cursors should be used carefully. User applications such
as <application>psql</application> are not aware of binary cursors
and expect data to come back in a text format.
</para>
</caution>
</para>
<PARA>
However, string representation is architecture-neutral whereas binary
representation can differ between different machine architectures.
@@ -235,13 +237,14 @@ and expect data to come back in a text format.
representations (e.g. "big-endian" versus "little-endian"),
you will probably not want your data returned in
binary format.
<tip>
<para>
If you intend to display the data in
ASCII, getting it back in ASCII will save you some
effort on the client side.
</tip>
<tip>
<para>
If you intend to display the data in
ASCII, getting it back in ASCII will save you some
effort on the client side.
</para>
</tip>
</PARA>
<REFSECT2 ID="R2-SQL-DECLARE-3">
@@ -256,18 +259,19 @@ and expect data to come back in a text format.
</PARA>
<PARA>
<productname>Postgres</productname>
does not have an explicit <command>OPEN cursor</command>
does not have an explicit <command>OPEN cursor</command>
statement; a cursor is considered to be open when it is declared.
<note>
<para>
In <acronym>SQL92</acronym> cursors are only available in
embedded applications. <application>ecpg</application>, the
embedded SQL preprocessor for <productname>Postgres</productname>,
supports the <acronym>SQL92</acronym> conventions, including those
involving DECLARE and OPEN statements.
</note>
<note>
<para>
In <acronym>SQL92</acronym> cursors are only available in
embedded applications. <application>ecpg</application>, the
embedded SQL preprocessor for <productname>Postgres</productname>,
supports the <acronym>SQL92</acronym> conventions, including those
involving DECLARE and OPEN statements.
</para>
</note>
</PARA>
</REFSECT2>
</refsect1>
@@ -300,14 +304,16 @@ DECLARE liahona CURSOR
SQL92
</TITLE>
<PARA>
<acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
and in modules. <productname>Postgres</productname> permits cursors to be used
interactively.
<acronym>SQL92</acronym> allows embedded or modular cursors to
update database information.
All <productname>Postgres</productname> cursors are readonly.
The BINARY keyword is a <productname>Postgres</productname> extension.
<acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
and in modules. <productname>Postgres</productname> permits cursors to be used
interactively.
<acronym>SQL92</acronym> allows embedded or modular cursors to
update database information.
All <productname>Postgres</productname> cursors are readonly.
The BINARY keyword is a <productname>Postgres</productname> extension.
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file

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

@@ -13,7 +13,7 @@
Deletes rows from a table
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -82,10 +82,13 @@
<PARA>
If <replaceable class="parameter">count</replaceable> is 0,
no rows were deleted.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-DELETE-1">
<REFSECT1INFO>
@@ -118,7 +121,7 @@
Remove all films but musicals:
</PARA>
<ProgramListing>
DELETE FROM films WHERE kind &lt;&gt; 'Musical';
DETETE FROM films WHERE kind &lt;&gt; 'Musical';
SELECT * FROM films;
@@ -165,7 +168,7 @@ DELETE FROM <replaceable class="parameter">table</replaceable> WHERE CURRENT OF
</synopsis>
<para>
where <replaceable class="parameter">cursor</replaceable> identifies an open cursor. Interactive cursors in <productname>Postgres</productname> are read-only.
</para>
</para>
</refsect2>
</refsect1>
</REFENTRY>

433
doc/src/sgml/ref/destroydb.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
@@ -22,203 +23,247 @@ destroydb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replace
[ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-APP-DESTROYDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-i
</term>
<listitem>
<para>
Run in interactive mode.
Prompts for confirmation before destroying a database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be destroyed. The database
must be one of the existing <productname>Postgres</productname> databases
in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<REFSECT2 ID="R2-APP-DESTROYDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroydb</application> will remove files from the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the existing database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
<application>destroydb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-i
</term>
<listitem>
<para>
Run in interactive mode.
Prompts for confirmation before destroying a database.
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
You do not have permission to destroy (or create) databases.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
The database to be removed does not have an entry in the
<literal>pg_database</literal> class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
You are not the Database Administrator (DBA) for the specified database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
<application>destroydb</application> internally runs
<command>DESTROY DATABASE</command> from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be destroyed. The database
must be one of the existing <productname>Postgres</productname> databases
in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
<REFSECT2 ID="R2-APP-DESTROYDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroydb</application> will remove files from the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the existing database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
<application>destroydb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have permission to destroy (or create) databases.
Contact your <productname>Postgres</productname> site administrator.
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The database to be removed does not have an entry in the
<literal>pg_database</literal> class.
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You are not the Database Administrator (DBA) for the specified database.
<varlistentry>
<term>
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>destroydb</application> internally runs
<command>DESTROY DATABASE</command> from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-DESTROYDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroydb</application> destroys an existing
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
<para>
All references to
the database are removed, including the directory containing this
database and its associated files.
<para>
<application>destroydb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroydb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-DESTROYDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To destroy the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
destroydb demo
</programlisting>
<para>
To destroy the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
destroydb -p 5000 -h eden demo
</programlisting>
<REFSECT1 ID="R1-APP-DESTROYDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroydb</application> destroys an existing
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
</para>
<para>
All references to
the database are removed, including the directory containing this
database and its associated files.
</para>
<para>
<application>destroydb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroydb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
</refsect1>
<REFSECT1 ID="R1-APP-DESTROYDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To destroy the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
destroydb demo
</programlisting>
</para>
<para>
To destroy the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
destroydb -p 5000 -h eden demo
</programlisting>
</para>
</refsect1>
</REFENTRY>

382
doc/src/sgml/ref/destroyuser.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Destroy a <productname>Postgres</productname> user and associated databases
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
@@ -22,179 +23,222 @@ destroyuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <repla
[ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-APP-DESTROYUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be removed.
This name must exist in the <productname>Postgres</productname> installation.
You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-DESTROYUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroyuser</application> will remove an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
and will remove all databases for which that user is the administrator
(<acronym>DBA</acronym>).
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroyuser: database access failed.
</term>
<listitem>
<para>
<application>destroyuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroyuser: database access failed.
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
</term>
<listitem>
<para>
You do not have permission to delete users; contact your
<productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
</term>
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
database access failed
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be removed.
This name must exist in the <productname>Postgres</productname> installation.
You will be prompted for a name if none is specified on the command line.
<varlistentry>
<term>
destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. There was possibly a Unix permissions problem with the
specified database.
</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>
delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server.
</para>
</listitem>
</varlistentry>
<REFSECT2 ID="R2-APP-DESTROYUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroyuser</application> will remove an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
and will remove all databases for which that user is the administrator
(<acronym>DBA</acronym>).
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroyuser: database access failed.
<listitem>
<para>
<application>destroyuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroyuser: database access failed.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
<varlistentry>
<term>
destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
<listitem>
<para>
You do not have permission to delete users; contact your
<productname>Postgres</productname> site administrator.
<varlistentry>
<term>
destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
<varlistentry>
<term>
database access failed
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
<varlistentry>
<term>
destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. There was possibly a Unix permissions problem with the
specified database.
<varlistentry>
<term>
delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server.
</variablelist>
<note>
<para>
<application>destroyuser</application> internally runs
DROP USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-DESTROYUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroyuser</application> removes an existing
<productname>Postgres</productname> user
and the databases for which that user
is database administrator.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can destroy
<productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can remove users.
<para>
<application>destroyuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroyuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<para>
Once invoked, <application>destroyuser</application>
will warn you about the databases that will be destroyed in the
process and permit you to abort the removal of the user if desired.
</variablelist>
</para>
<note>
<para>
<application>destroyuser</application> internally runs
DROP USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-DESTROYUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroyuser</application> removes an existing
<productname>Postgres</productname> user
and the databases for which that user
is database administrator.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can destroy
<productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can remove users.
</para>
<para>
<application>destroyuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroyuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
<para>
Once invoked, <application>destroyuser</application>
will warn you about the databases that will be destroyed in the
process and permit you to abort the removal of the user if desired.
</para>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes the definition of an aggregate function
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -84,8 +85,11 @@ DROP AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> <REPLACEABLE CL
<PARA>
This message occurs if the aggregate function specified does not
exist in the database.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Destroys an existing database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -80,8 +81,11 @@ DROP DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
<LISTITEM>
<PARA>
This message occurs if the specified database does not exist.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Removes a user-defined C function
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -82,8 +82,11 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
<PARA>
This message is given if the function specified does not
exist in the current database.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -118,6 +121,7 @@ CREATE FUNCTION
to create aggregate functions.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPFUNCTION-2">
<TITLE>
@@ -130,6 +134,7 @@ CREATE FUNCTION
DROP FUNCTION sqrt(int4);
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-DROPFUNCTION-3">
<TITLE>
Bugs

9
doc/src/sgml/ref/drop_index.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes an index from a database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -70,8 +71,11 @@ DROP INDEX <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
<PARA>
This message occurs if <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
is not an index in the database.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -104,6 +108,7 @@ DROP INDEX <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
information on how to create indexes.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPINDEX-2">
<TITLE>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes a user-defined procedural language
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
@@ -72,8 +73,11 @@ DROP PROCEDURAL LANGUAGE '<REPLACEABLE CLASS="PARAMETER">langname</REPLACEABLE>'
This message occurs if the language
"<replaceable class="parameter">langname</replaceable>" is
not found.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

10
doc/src/sgml/ref/drop_operator.sgml
View File

@@ -12,7 +12,7 @@
<REFPURPOSE>
Removes an operator from the database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
@@ -104,8 +104,11 @@ DROP OPERATOR <REPLACEABLE CLASS="PARAMETER">id</REPLACEABLE> ( <REPLACEABLE CLA
<PARA>
This message occurs if the specified right unary operator
specified does not exist.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -147,6 +150,7 @@ DROP OPERATOR <REPLACEABLE CLASS="PARAMETER">id</REPLACEABLE> ( <REPLACEABLE CLA
operator classes that rely on the deleted operator.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPOPERATOR-2">
<TITLE>

7
doc/src/sgml/ref/drop_rule.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes an existing rule from the database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -69,7 +70,11 @@ DROP RULE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
<LISTITEM>
<PARA>
This message occurs if the specified rule does not exist.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes an existing sequence
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -70,7 +71,11 @@ DROP SEQUENCE <REPLACEABLE CLASS="PARAMETER">seqname</REPLACEABLE> [, ...]
<LISTITEM>
<PARA>
This message occurs if the specified sequence does not exist.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -105,6 +110,7 @@ DROP SEQUENCE <REPLACEABLE CLASS="PARAMETER">seqname</REPLACEABLE> [, ...]
information on how to create a sequence.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPSEQUENCE-2">
<TITLE>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Removes existing tables from a database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -70,7 +70,11 @@ DROP TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [, ...]
<LISTITEM>
<PARA>
If the specified table or view does not exist in the database.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

12
doc/src/sgml/ref/drop_trigger.sgml
View File

@@ -11,7 +11,8 @@
</REFNAME>
<REFPURPOSE>
Removes the definition of a trigger
</REFPURPOSE>
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -80,9 +81,11 @@ DROP TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ON <REPLACEABLE C
<LISTITEM>
<PARA>
This message occurs if the trigger specified does not exist.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -115,6 +118,7 @@ DROP TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ON <REPLACEABLE C
information on how to create triggers.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPTRIGGER-2">
<TITLE>

9
doc/src/sgml/ref/drop_type.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes a user-defined type from the system catalogs
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -69,8 +70,11 @@ DROP TYPE <REPLACEABLE CLASS="PARAMETER">typename</REPLACEABLE>
<LISTITEM>
<PARA>
This message occurs if the specified type is not found.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -123,6 +127,7 @@ DROP TYPE <REPLACEABLE CLASS="PARAMETER">typename</REPLACEABLE>
is unpredictable.
</PARA>
</refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPTYPE-2">
<TITLE>

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

@@ -12,7 +12,7 @@
<REFPURPOSE>
Removes an user account information
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -70,10 +70,11 @@ DROP USER <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
<LISTITEM>
<PARA>
This message occurs if the username is not found.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -111,6 +112,7 @@ DROP USER <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
how to create or modify user accounts.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPUSER-2">
<TITLE>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Removes an existing view from a database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
@@ -60,19 +61,24 @@ DROP VIEW <REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>
<LISTITEM>
<PARA>
The message returned if the command is successful.
<VARLISTENTRY>
<TERM>
<ReturnValue>
ERROR: RewriteGetRuleEventRel: rule "_RET<REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>" not found</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This message occurs if the specified view does not exist in
the database.
</variablelist>
</REFSECT2>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<ReturnValue>
ERROR: RewriteGetRuleEventRel: rule "_RET<REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>" not found</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
This message occurs if the specified view does not exist in
the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-DROPVIEW-1">
@@ -104,6 +110,7 @@ the database.
for information on how to create views.
</PARA>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPVIEW-2">
<TITLE>
@@ -164,11 +171,12 @@ DROP VIEW <replaceable class="parameter">view</replaceable> { RESTRICT | CASCADE
<para>
Any referencing views and integrity constraints
will be dropped as well.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<REFSECT3 ID="R3-SQL-DROPVIEW-2">
<REFSECT3INFO>
@@ -176,15 +184,17 @@ DROP VIEW <replaceable class="parameter">view</replaceable> { RESTRICT | CASCADE
</REFSECT3INFO>
<TITLE>
Notes
</TITLE>
<para>
<tip>
</TITLE>
<para>
At present, to remove a referenced view from a
<productname>Postgres</productname> database,
you must drop it explicitly.
<tip>
<para>
At present, to remove a referenced view from a
<productname>Postgres</productname> database,
you must drop it explicitly.
</para>
</tip>
</para>
</tip>
</refsect3>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@ EXPLAIN
<REFPURPOSE>
Shows statement execution details
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
@@ -38,7 +39,9 @@ VERBOSE
<LISTITEM>
<PARA>
Flag to show detailed query plan.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
@@ -46,9 +49,11 @@ Flag to show detailed query plan.
<LISTITEM>
<PARA>
Any <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-EXPLAIN-2">
@@ -69,7 +74,9 @@ NOTICE: QUERY PLAN:
<LISTITEM>
<PARA>
Explicit query plan from the <productname>Postgres</productname> backend.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
EXPLAIN
@@ -77,9 +84,11 @@ EXPLAIN
<LISTITEM>
<PARA>
Flag sent after query plan is shown.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -95,7 +104,7 @@ Description
The default output is the computed query cost.
VERBOSE displays the full query plan and cost to your screen,
and pretty-prints the plan to the postmaster log file.
</para>
<REFSECT2 ID="R2-SQL-EXPLAIN-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
@@ -111,8 +120,9 @@ can be found in database textbooks.
Refer to the <citetitle>Programmer's Guide</citetitle>
in the chapters on indexes and the genetic query optimizer for
more information.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-EXPLAIN-2">
<TITLE>
@@ -129,7 +139,7 @@ Seq Scan on foo (cost=0.00 size=0 width=4)
EXPLAIN
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-EXPLAIN-3">
@@ -148,6 +158,9 @@ SQL92
</TITLE>
<PARA>
There is no EXPLAIN statement defined in SQL92.
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!--

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

@@ -12,6 +12,7 @@ FETCH
<REFPURPOSE>
Gets rows using a cursor
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
@@ -42,7 +43,10 @@ Inputs
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
defines the fetch direction. It can be one
the following:
</para>
</listitem>
</varlistentry>
</variablelist>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
@@ -52,7 +56,9 @@ FORWARD
<PARA>
fetch next row(s). This is the default
if <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> is omitted.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
BACKWARD
@@ -60,7 +66,9 @@ BACKWARD
<LISTITEM>
<PARA>
fetch previous row(s).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
RELATIVE
@@ -68,8 +76,10 @@ RELATIVE
<LISTITEM>
<PARA>
Noise word for SQL92 compatibility.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
<VARLISTENTRY>
<TERM>
@@ -79,8 +89,11 @@ Noise word for SQL92 compatibility.
<PARA>
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
determines how many rows to fetch. It can be one of the following:
</para>
</listitem>
</varlistentry>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
@@ -90,6 +103,9 @@ determines how many rows to fetch. It can be one of the following:
A signed integer that specify how many rows to fetch.
Note that a negative integer is equivalent to changing the sense of
FORWARD and BACKWARD.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -98,6 +114,9 @@ ALL
<LISTITEM>
<PARA>
Retrieve all remaining rows.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -106,6 +125,9 @@ NEXT
<LISTITEM>
<PARA>
Equivalent to specifying a count of <command>1</command>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -114,8 +136,9 @@ PRIOR
<LISTITEM>
<PARA>
Equivalent to specifying a count of <command>-1</command>.
</VARIABLELIST>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -124,9 +147,11 @@ Equivalent to specifying a count of <command>-1</command>.
<LISTITEM>
<PARA>
An open cursor's name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-FETCH-2">
@@ -139,6 +164,7 @@ Outputs
<PARA>
FETCH returns the results of the query defined by the specified cursor.
The following messages will be returned if the query fails:
</para>
<VARIABLELIST>
<VARLISTENTRY>
@@ -150,6 +176,9 @@ NOTICE: PerformPortalFetch: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPL
If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
is not previously declared.
The cursor must be declared within a transaction block.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -159,6 +188,9 @@ NOTICE: FETCH/ABSOLUTE not supported, using RELATIVE
<PARA>
<productname>Postgres</productname> does not support absolute
positioning of cursors.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
@@ -178,6 +210,9 @@ all rows should be retrieved and is equivalent to specifying the ALL keyword.
If the RELATIVE keyword has been used, the <productname>Postgres</productname>
assumes that the user intended <acronym>SQL92</acronym> behavior
and returns this error message.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -209,18 +244,20 @@ Negative numbers are now allowed to be specified for the
row count. A negative number is equivalent to reversing
the sense of the FORWARD and BACKWARD keywords. For example,
<command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>.
</para>
</tip>
</para>
<para>
Note that the FORWARD and BACKWARD keywords are
<productname>Postgres</productname> extensions.
The <acronym>SQL92</acronym> syntax is also supported, specified
in the second form of the command. See below for details
on compatibility issues.
</para>
<para>
Once all rows are fetched, every other fetch access returns
no rows.
</para>
<para>
Updating data in a cursor is not supported by
@@ -229,10 +266,12 @@ on compatibility issues.
not generally possible, as is also the case with VIEW updates.
Consequently,
users must issue explicit UPDATE commands to replace data.
</para>
<para>
Cursors may only be used inside of transactions because
the data that they store spans multiple user queries.
</para>
<REFSECT2 ID="R2-SQL-FETCH-3">
<REFSECT2INFO>
@@ -246,8 +285,9 @@ Notes
Refer to DECLARE statements to declare a cursor.
Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
for further information about transactions.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-FETCH-2">
<TITLE>
@@ -287,7 +327,7 @@ Usage
CLOSE liahona;
COMMIT WORK;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-FETCH-3">
@@ -327,7 +367,9 @@ ABSOLUTE
The cursor should be positioned to the specified absolute
row number. All row numbers in <productname>Postgres</productname>
are relative numbers so this capability is not supported.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
:<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
@@ -335,9 +377,13 @@ are relative numbers so this capability is not supported.
<LISTITEM>
<PARA>
Target host variable(s).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!--

850
doc/src/sgml/ref/grant.sgml
View File

@@ -1,226 +1,270 @@
<REFENTRY ID="SQL-GRANT">
<REFMETA>
<REFENTRYTITLE>
GRANT
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
GRANT
</REFNAME>
<REFPURPOSE>
Grants access privilege to a user, a group or all users
</REFPURPOSE>
<REFMETA>
<REFENTRYTITLE>
GRANT
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
GRANT
</REFNAME>
<REFPURPOSE>
Grants access privilege to a user, a group or all users
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-23</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [, ...]
TO { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-GRANT-1">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The possible privileges are:
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
SELECT
</TERM>
<LISTITEM>
<PARA>
Access all of the columns of a specific
table/view.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
INSERT
</TERM>
<LISTITEM>
<PARA>
Insert data into all columns of a
specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
UPDATE
</TERM>
<LISTITEM>
<PARA>
Update all columns of a specific
table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
DELETE
</TERM>
<LISTITEM>
<PARA>
Delete rows from a specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
RULE
</TERM>
<LISTITEM>
<PARA>
Define rules on the table/view
(See CREATE RULE statement).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Grant all privileges.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an object to which to grant access.
The possible objects are:
</para>
<para>
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
table
</para>
</listitem>
<listitem>
<para>
view
</para>
</listitem>
<listitem>
<para>
sequence
</para>
</listitem>
<listitem>
<para>
index
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-23</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [, ...]
TO { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS>
<VARLISTENTRY>
<TERM>
PUBLIC
</TERM>
<LISTITEM>
<PARA>
A short form representing all users.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> to whom to grant privileges.
In the current release, the group must be created explicitly as described below.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a user to whom grant privileges. PUBLIC is a short form
representing all users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-GRANT-1">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-GRANT-2">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ERROR: ChangeAcl: class "<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>"
not found
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified object is not available or
if it is impossible
to give privileges to the specified group or users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The possible privileges are:
<REFSECT1 ID="R1-SQL-GRANT-1">
<REFSECT1INFO>
<DATE>1998-09-23</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
GRANT allows the creator of an object to give specific permissions to
all users (PUBLIC) or to a certain user or group.
Users other than the creator don't have any access permission
unless the creator GRANTs permissions, after the object
is created.
</para>
<para>
Once a user has a privilege on an object, he is enabled to exercise
that privilege.
There is no need to GRANT privileges to the creator of
an object, the creator automatically holds ALL privileges, and can
also drop the object.
</para>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
SELECT
</TERM>
<LISTITEM>
<PARA>
Access all of the columns of a specific
table/view.
<VARLISTENTRY>
<TERM>
INSERT
</TERM>
<LISTITEM>
<PARA>
Insert data into all columns of a
specific table.
<VARLISTENTRY>
<TERM>
UPDATE
</TERM>
<LISTITEM>
<PARA>
Update all columns of a specific
table.
<VARLISTENTRY>
<TERM>
DELETE
</TERM>
<LISTITEM>
<PARA>
Delete rows from a specific table.
<VARLISTENTRY>
<TERM>
RULE
</TERM>
<LISTITEM>
<PARA>
Define rules on the table/view
(See CREATE RULE statement).
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Grant all privileges.
</VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an object to which to grant access.
The possible objects are:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
table
<listitem>
<para>
view
<listitem>
<para>
sequence
<listitem>
<para>
index
</itemizedlist>
<VARLISTENTRY>
<TERM>
PUBLIC
</TERM>
<LISTITEM>
<PARA>
A short form representing all users.
<VARLISTENTRY>
<TERM>
GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> to whom to grant privileges.
In the current release, the group must be created explicitly as described below.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a user to whom grant privileges. PUBLIC is a short form
representing all users.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-GRANT-2">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
<VARLISTENTRY>
<TERM>
ERROR: ChangeAcl: class "<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>"
not found
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified object is not available or
if it is impossible
to give privileges to the specified group or users.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-GRANT-1">
<REFSECT1INFO>
<DATE>1998-09-23</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
GRANT allows the creator of an object to give specific permissions to
all users (PUBLIC) or to a certain user or group.
Users other than the creator don't have any access permission
unless the creator GRANTs permissions, after the object
is created.
<para>
Once a user has a privilege on an object, he is enabled to exercise
that privilege.
There is no need to GRANT privileges to the creator of
an object, the creator automatically holds ALL privileges, and can
also drop the object.
<REFSECT2 ID="R2-SQL-GRANT-3">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Use the <command>psql \z</command> command
for further information about permissions
on existing objects:
<programlisting>
Database = lusitania
<REFSECT2 ID="R2-SQL-GRANT-3">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Use the <command>psql \z</command> command
for further information about permissions
on existing objects:
<programlisting>
Database = lusitania
+------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions |
+------------------+---------------------------------------------+
@@ -236,177 +280,211 @@ Use the <command>psql \z</command> command
a -- INSERT
R -- RULE
arwR -- ALL
</programlisting>
</programlisting>
<tip>
<para>
Currently, to create a GROUP you have to insert
data manually into table pg_group as:
<programlisting>
INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos;
</programlisting>
Refer to REVOKE statements to revoke access privileges.
</tip>
<tip>
<para>
Currently, to create a GROUP you have to insert
data manually into table pg_group as:
<programlisting>
INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos;
</programlisting>
Refer to REVOKE statements to revoke access privileges.
</para>
</tip>
</para>
</REFSECT2>
</refsect1>
</REFSECT2>
<REFSECT1 ID="R1-SQL-GRANT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- grant insert privilege to all users on table films:
--
GRANT INSERT ON films TO PUBLIC;
</programlisting>
<programlisting>
-- grant all privileges to user manuel on view kinds:
--
GRANT ALL ON kinds TO manuel;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-GRANT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- grant insert privilege to all users on table films:
--
GRANT INSERT ON films TO PUBLIC;
</programlisting>
<programlisting>
-- grant all privileges to user manuel on view kinds:
--
GRANT ALL ON kinds TO manuel;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-GRANT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-GRANT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The <acronym>SQL92</acronym> syntax for GRANT allows setting privileges
for individual columns
within a table, and allows setting a privilege to grant
the same privileges to others.
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, ...]
TO { PUBLIC | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> [, ...] }
[ WITH GRANT OPTION ]
</SYNOPSIS>
Fields are compatible with the those in the <acronym>Postgres</acronym>
implementation, with the following additions:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
SELECT
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> permits additional privileges to be specified:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
REFERENCES
</TERM>
<LISTITEM>
<PARA>
Allowed to reference some or all of the columns of a specific
table/view in integrity constraints.
<VARLISTENTRY>
<TERM>
USAGE
</TERM>
<LISTITEM>
<PARA>
Allowed to use a domain, character set, collation
or translation.
If an object specifies anything other than a table/view,
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
must specify only USAGE.
</variablelist>
<tip>
<para>
Currently, to grant privileges in <productname>Postgres</productname>
to only few columns, you must
create a view having desired columns and then grant privileges
to that view.
</tip>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> allows an additional non-functional keyword:
<simplelist>
<member>
[ TABLE ] table
</simplelist>
<VARLISTENTRY>
<TERM>
CHARACTER SET
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set.
<VARLISTENTRY>
<TERM>
COLLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified collation sequence.
<VARLISTENTRY>
<TERM>
TRANSLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set translation.
<VARLISTENTRY>
<TERM>
DOMAIN
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified domain.
</variablelist>
<VARLISTENTRY>
<TERM>
WITH GRANT OPTION
</TERM>
<LISTITEM>
<PARA>
Allowed to grant the same privilege to others.
</variablelist>
<REFSECT1 ID="R1-SQL-GRANT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-GRANT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The <acronym>SQL92</acronym> syntax for GRANT allows setting privileges
for individual columns
within a table, and allows setting a privilege to grant
the same privileges to others.
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, ...]
TO { PUBLIC | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> [, ...] }
[ WITH GRANT OPTION ]
</SYNOPSIS>
Fields are compatible with the those in the <acronym>Postgres</acronym>
implementation, with the following additions:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
SELECT
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> permits additional privileges to be specified:
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
REFERENCES
</TERM>
<LISTITEM>
<PARA>
Allowed to reference some or all of the columns of a specific
table/view in integrity constraints.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
USAGE
</TERM>
<LISTITEM>
<PARA>
Allowed to use a domain, character set, collation
or translation.
If an object specifies anything other than a table/view,
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
must specify only USAGE.
</para>
</listitem>
</varlistentry>
</variablelist>
<tip>
<para>
Currently, to grant privileges in <productname>Postgres</productname>
to only few columns, you must
create a view having desired columns and then grant privileges
to that view.
</para>
</tip>
<variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> allows an additional non-functional keyword:
<simplelist>
<member>
[ TABLE ] table
</member>
</simplelist>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
CHARACTER SET
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
COLLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified collation sequence.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
TRANSLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set translation.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
DOMAIN
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified domain.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
WITH GRANT OPTION
</TERM>
<LISTITEM>
<PARA>
Allowed to grant the same privilege to others.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!--

534
doc/src/sgml/ref/initdb.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Create a new <productname>Postgres</productname> database installation
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
@@ -24,256 +25,289 @@ initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <repla
[ --noclean | -n ] [ --debug | -d ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-INITDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
--pglib=<replaceable class="parameter">libdir</replaceable>
</term>
<term>
-l <replaceable class="parameter">libdir</replaceable>
</term>
<term>
<envar>PGLIB</envar>
<listitem>
<para>
Where are the files that make up <productname>Postgres</productname>?
Apart from files that
have to go in particular directories because of their function, the
files that make up the <productname>Postgres</productname> software
were installed in a directory
called the <replaceable class="parameter">libdir</replaceable> directory.
An example of a file that will be found
there that <application>initdb</application>
needs is <filename>global1.bki.source</filename>,
which contains all the information that goes
into the shared catalog tables.
<REFSECT2 ID="R2-APP-INITDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
--pglib=<replaceable class="parameter">libdir</replaceable>
</term>
<term>
-l <replaceable class="parameter">libdir</replaceable>
</term>
<term>
<envar>PGLIB</envar>
</term>
<listitem>
<para>
Where are the files that make up <productname>Postgres</productname>?
Apart from files that
have to go in particular directories because of their function, the
files that make up the <productname>Postgres</productname> software
were installed in a directory
called the <replaceable class="parameter">libdir</replaceable> directory.
An example of a file that will be found
there that <application>initdb</application>
needs is <filename>global1.bki.source</filename>,
which contains all the information that goes
into the shared catalog tables.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--pgdata=<replaceable class="parameter">dbdir</replaceable>
</term>
<term>
-r <replaceable class="parameter">dbdir</replaceable>
</term>
<term>
<envar>PGDATA</envar>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want the database data to go?
The top level directory is called the <envar>PGDATA</envar> directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the <productname>Postgres</productname> superuser
for this database system? The
<productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Or just let it default to you (the Unix user who runs
<application>initdb</application>).
</para>
<note>
<para>
Only the Unix superuser (<literal>root</literal>)
can create a database system with an owner
different from the <productname>Postgres</productname> superuser.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Other, less commonly used, parameters are also available:
<variablelist>
<varlistentry>
<term>
--template=<replaceable class="parameter">template</replaceable>
</term>
<term>
-t <replaceable class="parameter">template</replaceable>
</term>
<listitem>
<para>
Replace the <literal>template1</literal>
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your <literal>template1</literal>
database using <application>initdb</application>
from a newer release of <productname>Postgres</productname>,
or when your <literal>template1</literal>
database has become corrupted by some system problem. Normally the
contents of <literal>template1</literal>
remain constant throughout the life of the database system. You can't
destroy anything by running <application>initdb</application>
with the
<option>--template</option>
option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--noclean
</term>
<term>
-n
</term>
<listitem>
<para>
By default, when <application>initdb</application>
determines that error prevent it from completely creating the database
system, it removes any files it may have created before determining
that it can't finish the job. That includes any core files left by
the programs it invokes. This option inhibits any tidying-up and is
thus useful for debugging.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--debug
</term>
<term>
-d
</term>
<listitem>
<para>
Print debugging output from the bootstrap backend.
The bootstrap backend is the program <application>initdb</application>
uses to create the catalog tables. This option generates a tremendous
amount of output. It also turns off the final vacuuming step.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Files are also input to <application>initdb</application>:
<variablelist>
<varlistentry>
<term>
<application>postconfig</application>
</term>
<listitem>
<para>
If appearing somewhere in the Unix command search path
(defined by the PATH environment variable).
This is a program that specifies defaults for some of the
command options. See below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/global1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the shared catalog tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/local1_template1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the template1 tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<varlistentry>
<term>
--pgdata=<replaceable class="parameter">dbdir</replaceable>
</term>
<term>
-r <replaceable class="parameter">dbdir</replaceable>
</term>
<term>
<envar>PGDATA</envar>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want the database data to go?
The top level directory is called the <envar>PGDATA</envar> directory.
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the <productname>Postgres</productname> superuser
for this database system? The
<productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Or just let it default to you (the Unix user who runs
<application>initdb</application>).
<note>
<para>
Only the Unix superuser (<literal>root</literal>)
can create a database system with an owner
different from the <productname>Postgres</productname> superuser.
</note>
</variablelist>
<para>
Other, less commonly used, parameters are also available:
<variablelist>
<varlistentry>
<term>
--template=<replaceable class="parameter">template</replaceable>
</term>
<term>
-t <replaceable class="parameter">template</replaceable>
</term>
<listitem>
<para>
Replace the <literal>template1</literal>
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your <literal>template1</literal>
database using <application>initdb</application>
from a newer release of <productname>Postgres</productname>,
or when your <literal>template1</literal>
database has become corrupted by some system problem. Normally the
contents of <literal>template1</literal>
remain constant throughout the life of the database system. You can't
destroy anything by running <application>initdb</application>
with the
<option>--template</option>
option.
<varlistentry>
<term>
--noclean
</term>
<term>
-n
</term>
<listitem>
<para>
By default, when <application>initdb</application>
determines that error prevent it from completely creating the database
system, it removes any files it may have created before determining
that it can't finish the job. That includes any core files left by
the programs it invokes. This option inhibits any tidying-up and is
thus useful for debugging.
<varlistentry>
<term>
--debug
</term>
<term>
-d
</term>
<listitem>
<para>
Print debugging output from the bootstrap backend.
The bootstrap backend is the program <application>initdb</application>
uses to create the catalog tables. This option generates a tremendous
amount of output. It also turns off the final vacuuming step.
</variablelist>
<para>
Files are also input to <application>initdb</application>:
<variablelist>
<varlistentry>
<term>
<application>postconfig</application>
</term>
<listitem>
<para>
If appearing somewhere in the Unix command search path
(defined by the PATH environment variable).
This is a program that specifies defaults for some of the
command options. See below.
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/global1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the shared catalog tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/local1_template1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the template1 tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
</variablelist>
<REFSECT2 ID="R2-APP-INITDB-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initdb</application> will create files in the <envar>PGDATA</envar>
data area which are the system tables and framework for a complete
installation.
<REFSECT1 ID="R1-APP-INITDB-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initdb</application> creates a new
<productname>Postgres</productname> database system.
A database system is a
collection of databases that are all administered by the same Unix user
and managed by a single postmaster.
<para>
Creating a database system consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that don't belong to any particular database), and
creating the <literal>template1</literal>
database. What is the <literal>template1</literal>
database? When you create a database, <productname>Postgres</productname>
does it by copying
everything from the <literal>template1</literal>
database. It contains catalog tables filled in for things like the
builtin types.
<para>
After <application>initdb</application>
creates the database, it completes the initialization by running
<application>vacuum</application>, which resets some optimization parameters.
<para>
There are three ways to give parameters to <application>initdb</application>.
First, you can use <application>initdb</application> command options.
Second, you can set environment
variables before invoking <application>initdb</application>.
Third, you can have a program called <application>postconfig</application>
in your Unix command search path.
<application>initdb</application> invokes that program and that program then writes
<application>initdb</application> parameters to its standard output stream.
This third option is not a common thing to do, however.
<para>
Command options always override parameters specified any other way.
The values returned by <application>postconfig</application>
override any environment variables, but your
<application>postconfig</application>
program may base its output on the environment variables if you want
their values to be used.
<para>
The value that <application>postconfig</application>
outputs must have the format
<programlisting>
<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
</programlisting>
It can output nothing if it doesn't want to supply any parameters.
The <replaceable>var</replaceable> values are equal to
the corresponding environment variable
names. For example,
<programlisting>
PGDATA=/tmp/postgres_test
</programlisting>
has the
same effect as invoking <application>initdb</application>
with an environment variable called <envar>PGDATA</envar> whose value is
<filename>/tmp/postgres_test</filename>.
<REFSECT2 ID="R2-APP-INITDB-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initdb</application> will create files in the <envar>PGDATA</envar>
data area which are the system tables and framework for a complete
installation.
</para>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-INITDB-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initdb</application> creates a new
<productname>Postgres</productname> database system.
A database system is a
collection of databases that are all administered by the same Unix user
and managed by a single postmaster.
</para>
<para>
Creating a database system consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that don't belong to any particular database), and
creating the <literal>template1</literal>
database. What is the <literal>template1</literal>
database? When you create a database, <productname>Postgres</productname>
does it by copying
everything from the <literal>template1</literal>
database. It contains catalog tables filled in for things like the
builtin types.
</para>
<para>
After <application>initdb</application>
creates the database, it completes the initialization by running
<application>vacuum</application>, which resets some optimization parameters.
</para>
<para>
There are three ways to give parameters to <application>initdb</application>.
First, you can use <application>initdb</application> command options.
Second, you can set environment
variables before invoking <application>initdb</application>.
Third, you can have a program called <application>postconfig</application>
in your Unix command search path.
<application>initdb</application> invokes that program and that program then writes
<application>initdb</application> parameters to its standard output stream.
This third option is not a common thing to do, however.
</para>
<para>
Command options always override parameters specified any other way.
The values returned by <application>postconfig</application>
override any environment variables, but your
<application>postconfig</application>
program may base its output on the environment variables if you want
their values to be used.
</para>
<para>
The value that <application>postconfig</application>
outputs must have the format
<programlisting>
<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
</programlisting>
It can output nothing if it doesn't want to supply any parameters.
The <replaceable>var</replaceable> values are equal to
the corresponding environment variable
names. For example,
<programlisting>
PGDATA=/tmp/postgres_test
</programlisting>
has the
same effect as invoking <application>initdb</application>
with an environment variable called <envar>PGDATA</envar> whose value is
<filename>/tmp/postgres_test</filename>.
</para>
</refsect1>
</REFENTRY>

373
doc/src/sgml/ref/initlocation.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Create a secondary <productname>Postgres</productname> database storage area
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
@@ -22,180 +23,206 @@ initlocation [ --location=<replaceable class="parameter">altdir</replaceable> |
[ <replaceable class="parameter">altdir</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-INITLOCATION-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-APP-INITLOCATION-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
--location=<replaceable class="parameter">altdir</replaceable>
</term>
<term>
-D <replaceable class="parameter">altdir</replaceable>
</term>
<term>
<replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want alternate databases to go?
The top level directory is called the <envar>PGDATA</envar> directory, so you
might want to point your first alternate location at <envar>PGDATA2</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the Unix filesystem owner of this database storage area?
The
<productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Usually, this is the user who should run <application>initlocation</application>
and who will thus have ownership of the directories and files.
</para>
<note>
<para>
Only the Unix superuser can create a database system with a
different user as the <productname>Postgres</productname> superuser.
Specifying a user other than the <productname>Postgres</productname> superuser
may lead to database security and data integrity problems. Refer to the
<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
for more information.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-INITLOCATION-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initlocation</application> will create directories in
the specified place.
<variablelist>
<varlistentry>
<term>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Successful completion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory /usr/local/src/testlocation
mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
</term>
<listitem>
<para>
You do not have filesystem permission to write to the specified directory area.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Valid username not given. You must specify the username for
the Postgres superuser for the database system you are
initializing, either with the --username option or by default
to the USER environment variable.
</term>
<listitem>
<para>
The username which you have specified is not the
<productname>Postgres</productname> superuser.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Can't tell what username to use. You don't have the USER
environment variable set to your username and didn't specify the
--username option
</term>
<listitem>
<para>
Specify the <option>--username</option> command line option.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<variablelist>
<varlistentry>
<term>
--location=<replaceable class="parameter">altdir</replaceable>
</term>
<term>
-D <replaceable class="parameter">altdir</replaceable>
</term>
<term>
<replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want alternate databases to go?
The top level directory is called the <envar>PGDATA</envar> directory, so you
might want to point your first alternate location at <envar>PGDATA2</envar>.
<REFSECT1 ID="R1-APP-INITLOCATION-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initlocation</application>
creates a new <productname>Postgres</productname> secondary database storage area.
A secondary storage area contains a required tree of directories with
the correct file permissions on those directories.
</para>
<para>
Creating a database storage area consists of creating the directories in which
database data might live.
</para>
<para>
There are two kinds of arguments for <application>initlocation</application>.
First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
This environment variable should be known to the backend for later use in
<command>CREATE DATABASE/WITH LOCATION</command>
or
<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
However, <emphasis>the backend daemon must have this variable in it's
environment</emphasis> for this to succeed.
Second, you may be able to specify an explicit
absolute path to the top directory of the storage area. However,this second
option is possible only if explicitly enabled during the
<productname>Postgres</productname> installation. It is usually disabled
to alleviate security and data integrity concerns.
</para>
<note>
<para>
<productname>Postgres</productname> will add <filename>/base/</filename>
to the specified path to create the storage area.
</para>
<para>
The backend requires that any argument to <option>WITH LOCATION</option> which is
in all uppercase and which has no path delimiters is an environment variable.
</para>
</note>
</refsect1>
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the Unix filesystem owner of this database storage area?
The
<productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Usually, this is the user who should run <application>initlocation</application>
and who will thus have ownership of the directories and files.
<note>
<para>
Only the Unix superuser can create a database system with a
different user as the <productname>Postgres</productname> superuser.
Specifying a user other than the <productname>Postgres</productname> superuser
may lead to database security and data integrity problems. Refer to the
<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
for more information.
</note>
</variablelist>
<REFSECT2 ID="R2-APP-INITLOCATION-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initlocation</application> will create directories in
the specified place.
<variablelist>
<varlistentry>
<term>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Successful completion.
<varlistentry>
<term>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory /usr/local/src/testlocation
mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
</term>
<listitem>
<para>
You do not have filesystem permission to write to the specified directory area.
<varlistentry>
<term>
Valid username not given. You must specify the username for
the Postgres superuser for the database system you are
initializing, either with the --username option or by default
to the USER environment variable.
</term>
<listitem>
<para>
The username which you have specified is not the
<productname>Postgres</productname> superuser.
<varlistentry>
<term>
Can't tell what username to use. You don't have the USER
environment variable set to your username and didn't specify the
--username option
</term>
<listitem>
<para>
Specify the <option>--username</option> command line option.
</variablelist>
<REFSECT1 ID="R1-APP-INITLOCATION-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initlocation</application>
creates a new <productname>Postgres</productname> secondary database storage area.
A secondary storage area contains a required tree of directories with
the correct file permissions on those directories.
<para>
Creating a database storage area consists of creating the directories in which
database data might live.
<para>
There are two kinds of arguments for <application>initlocation</application>.
First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
This environment variable should be known to the backend for later use in
<command>CREATE DATABASE/WITH LOCATION</command>
or
<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
However, <emphasis>the backend daemon must have this variable in it's
environment</emphasis> for this to succeed.
Second, you may be able to specify an explicit
absolute path to the top directory of the storage area. However,this second
option is possible only if explicitly enabled during the
<productname>Postgres</productname> installation. It is usually disabled
to alleviate security and data integrity concerns.
<note>
<para>
<productname>Postgres</productname> will add <filename>/base/</filename>
to the specified path to create the storage area.
<para>
The backend requires that any argument to <option>WITH LOCATION</option> which is
in all uppercase and which has no path delimiters is an environment variable.
</note>
<REFSECT1 ID="R1-APP-INITLOCATION-2">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create a database in an alternate location, using an environment variable:
<programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
<REFSECT1 ID="R1-APP-INITLOCATION-2">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create a database in an alternate location, using an environment variable:
<programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
</para>
</refsect1>
</REFENTRY>

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

@@ -12,188 +12,208 @@ INSERT
<REFPURPOSE>
Inserts new rows into a table
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-23</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
{ VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-INSERT-1">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid query. Refer to the SELECT statement for a further description
of valid arguments.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-INSERT-2">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>INSERT <replaceable>oid</replaceable></ReturnValue> 1
</TERM>
<LISTITEM>
<PARA>
Message returned if only one row was inserted.
<ReturnValue><replaceable>oid</replaceable></ReturnValue>
is the row identifier.
<VARLISTENTRY>
<TERM>
<ReturnValue>INSERT 0 <replaceable>#</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if more than one rows were inserted.
<ReturnValue><replaceable>#</replaceable></ReturnValue>
is the number of rows inserted.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-INSERT-1">
<REFSECT1INFO>
<DATE>1998-09-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
INSERT allows one to insert new rows into a table. One can insert
a single row at time or several rows as a result of a query.
The columns in the target list may be listed in any order.
In every column not present in the target list will be inserted
the default value, if column has not a declared default value
it will be assumed as NULL. If the expression for each column
is not of the correct data type, automatic type coercion will be
attempted.
<para>
You must have insert privilege to a table in order to append
to it, as well as select privilege on any table specified
in a WHERE clause.
<REFSECT1 ID="R1-SQL-INSERT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Insert a single row into table films;
--(in the second example the column date_prod is omitted
--therefore will be stored in it a default value of NULL):
--
INSERT INTO films VALUES
('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute');
INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama');
</ProgramListing>
<ProgramListing>
--Insert a single row into table distributors, note that
--only column "name" is specified, to the non specified
--column "did" will be assigned its default value:
--
INSERT INTO distributors (name) VALUES ('British Lion');
</ProgramListing>
<ProgramListing>
--Insert several rows into table films from table tmp:
--
INSERT INTO films
SELECT * FROM tmp;
</ProgramListing>
<ProgramListing>
--Insert into arrays:
--Create an empty 3x3 gameboard for noughts-and-crosses
--(all of these queries create the same board attribute)
--(Refer to the <citetitle>PostgreSQL User's Guide</citetitle> for further
--information about arrays).
INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3])
VALUES (2,'{}');
INSERT INTO tictactoe (game, board)
VALUES (3,'{{,,},{,,},{,,}}');
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-INSERT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-INSERT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
clause are documented for the SELECT statement.
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-23</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
{ VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-INSERT-1">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid query. Refer to the SELECT statement for a further description
of valid arguments.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-INSERT-2">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>INSERT <replaceable>oid</replaceable></ReturnValue> 1
</TERM>
<LISTITEM>
<PARA>
Message returned if only one row was inserted.
<ReturnValue><replaceable>oid</replaceable></ReturnValue>
is the numeric <acronym>OID</acronym> of the inserted row.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<ReturnValue>INSERT 0 <replaceable>#</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if more than one rows were inserted.
<ReturnValue><replaceable>#</replaceable></ReturnValue>
is the number of rows inserted.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-INSERT-1">
<REFSECT1INFO>
<DATE>1998-09-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
INSERT allows one to insert new rows into a table. One can insert
a single row at time or several rows as a result of a query.
The columns in the target list may be listed in any order.
In every column not present in the target list will be inserted
the default value, if column has not a declared default value
it will be assumed as NULL. If the expression for each column
is not of the correct data type, automatic type coercion will be
attempted.
</para>
<para>
You must have insert privilege to a table in order to append
to it, as well as select privilege on any table specified
in a WHERE clause.
</para>
</refsect1>
<REFSECT1 ID="R1-SQL-INSERT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Insert a single row into table films;
--(in the second example the column date_prod is omitted
--therefore will be stored in it a default value of NULL):
--
INSERT INTO films VALUES
('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute');
INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama');
</ProgramListing>
<ProgramListing>
--Insert a single row into table distributors, note that
--only column "name" is specified, to the non specified
--column "did" will be assigned its default value:
--
INSERT INTO distributors (name) VALUES ('British Lion');
</ProgramListing>
<ProgramListing>
--Insert several rows into table films from table tmp:
--
INSERT INTO films
SELECT * FROM tmp;
</ProgramListing>
<ProgramListing>
--Insert into arrays:
--Create an empty 3x3 gameboard for noughts-and-crosses
--(all of these queries create the same board attribute)
--(Refer to the <citetitle>PostgreSQL User's Guide</citetitle> for further
--information about arrays).
INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3])
VALUES (2,'{}');
INSERT INTO tictactoe (game, board)
VALUES (3,'{{,,},{,,},{,,}}');
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-INSERT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-INSERT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
clause are documented for the SELECT statement.
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!--

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

@@ -12,7 +12,7 @@ LISTEN
<REFPURPOSE>
Listen for notification on a notify condition
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-07</DATE>
@@ -21,156 +21,165 @@ Listen for notification on a notify condition
LISTEN <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LISTEN-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Name of notify condition.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LISTEN-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LISTEN</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned upon successful completion of registration.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue>
</TERM>
<LISTITEM>
<PARA>
If this backend is already registered for that notify condition.
</PARA>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LISTEN-1">
<REFSECT1INFO>
<DATE>1998-10-07</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
LISTEN registers the current <productname>Postgres</productname> backend as a
listener on the notify condition
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
<para>
Whenever the command
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE></command>
is invoked, either by this backend or another one connected to
the same database, all the backends currently listening on that notify
condition are notified, and each will in turn notify its connected
frontend application. See the discussion of <command>NOTIFY</command>
for more information.
<para>
A backend can be deregistered for a given notify condition with the
<command>UNLISTEN</command> command. Also, a backend's listen registrations
are automatically cleared when the backend process exits.
<para>
The method a frontend application must use to detect notify events depends on
which <productname>Postgres</productname> application programming interface it
uses. With the basic libpq library, the application issues
<command>LISTEN</command> as an ordinary SQL command, and then must
periodically call the routine <function>PQnotifies</function> to find out
whether any notify events have been received. Other interfaces such as
libpgtcl provide higher-level methods for handling notify events; indeed,
with libpgtcl the application programmer should not even issue
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
documentation for the library you are using for more details.
<para>
The reference page for <command>NOTIFY</command> contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
<REFSECT2 ID="R2-SQL-LISTEN-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</REFSECT2>
<REFSECT1 ID="R1-SQL-LISTEN-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LISTEN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-LISTEN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LISTEN</command> in <acronym>SQL92</acronym>.
<REFSECT2 ID="R2-SQL-LISTEN-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Name of notify condition.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LISTEN-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LISTEN</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned upon successful completion of registration.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue>
</TERM>
<LISTITEM>
<PARA>
If this backend is already registered for that notify condition.
</PARA>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LISTEN-1">
<REFSECT1INFO>
<DATE>1998-10-07</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
LISTEN registers the current <productname>Postgres</productname> backend as a
listener on the notify condition
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
</para>
<para>
Whenever the command
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE></command>
is invoked, either by this backend or another one connected to
the same database, all the backends currently listening on that notify
condition are notified, and each will in turn notify its connected
frontend application. See the discussion of <command>NOTIFY</command>
for more information.
</para>
<para>
A backend can be deregistered for a given notify condition with the
<command>UNLISTEN</command> command. Also, a backend's listen registrations
are automatically cleared when the backend process exits.
</para>
<para>
The method a frontend application must use to detect notify events depends on
which <productname>Postgres</productname> application programming interface it
uses. With the basic libpq library, the application issues
<command>LISTEN</command> as an ordinary SQL command, and then must
periodically call the routine <function>PQnotifies</function> to find out
whether any notify events have been received. Other interfaces such as
libpgtcl provide higher-level methods for handling notify events; indeed,
with libpgtcl the application programmer should not even issue
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
documentation for the library you are using for more details.
</para>
<para>
The reference page for <command>NOTIFY</command> contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
</para>
<REFSECT2 ID="R2-SQL-LISTEN-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
</para>
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-LISTEN-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LISTEN-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-LISTEN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

337
doc/src/sgml/ref/load.sgml
View File

@@ -1,170 +1,179 @@
<REFENTRY ID="SQL-LOAD">
<REFMETA>
<REFENTRYTITLE>
LOAD
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LOAD
</REFNAME>
<REFPURPOSE>
Dynamically loads an object file
</REFPURPOSE>
<REFMETA>
<REFENTRYTITLE>
LOAD
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LOAD
</REFNAME>
<REFPURPOSE>
Dynamically loads an object file
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
</SYNOPSIS>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LOAD-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
<REFSECT2 ID="R2-SQL-LOAD-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.
</REFSECT2>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LOAD-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LOAD</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned on successful completion.
<VARLISTENTRY>
<TERM>
<returnvalue>ERROR: LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified file is not found. The file must be visible
<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
with the appropriate full path name specified, to avoid this message.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LOAD-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
Loads an object (or ".o") file into the
<productname>Postgres</productname> backend address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of user-defined types and functions.
<para>
If a file is not loaded using
<command>LOAD</command>,
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
can also be used to reload an object file if it has been edited and
recompiled. Only objects created from C language files are supported
at this time.
<REFSECT2 ID="R2-SQL-LOAD-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
command. For example, all functions in file <literal>A</literal> should
call each other, functions in the standard or math libraries, or in
Postgres itself. They should not call functions defined in a different
loaded file <literal>B</literal>.
This is because if <literal>B</literal> is reloaded, the Postgres loader is
not able to relocate the calls from the functions in <literal>A</literal> into
the new address space of <literal>B</literal>.
If <literal>B</literal> is not reloaded, however, there will
not be a problem.
<para>
Object files must be compiled to contain position independent code.
For example,
on DECstations you must use
<application>/bin/cc</application>
with the <literal>-G 0</literal> option when compiling object files to be
loaded.
<para>
Note that if you are porting <productname>Postgres</productname>
to a new platform, <command>LOAD</command>
will have to work in order to support ADTs.
</REFSECT2>
<REFSECT1 ID="R1-SQL-LOAD-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Load the file /usr/postgres/demo/circle.o
--
LOAD '/usr/postgres/demo/circle.o'
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
<REFSECT2 ID="R2-SQL-LOAD-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LOAD</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned on successful completion.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<returnvalue>ERROR: LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified file is not found. The file must be visible
<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
with the appropriate full path name specified, to avoid this message.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LOAD-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
Loads an object (or ".o") file into the
<productname>Postgres</productname> backend address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of user-defined types and functions.
</para>
<para>
If a file is not loaded using
<command>LOAD</command>,
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
can also be used to reload an object file if it has been edited and
recompiled. Only objects created from C language files are supported
at this time.
</para>
<REFSECT2 ID="R2-SQL-LOAD-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
command. For example, all functions in file <literal>A</literal> should
call each other, functions in the standard or math libraries, or in
Postgres itself. They should not call functions defined in a different
loaded file <literal>B</literal>.
This is because if <literal>B</literal> is reloaded, the Postgres loader is
not able to relocate the calls from the functions in <literal>A</literal> into
the new address space of <literal>B</literal>.
If <literal>B</literal> is not reloaded, however, there will
not be a problem.
</para>
<para>
Object files must be compiled to contain position independent code.
For example,
on DECstations you must use
<application>/bin/cc</application>
with the <literal>-G 0</literal> option when compiling object files to be
loaded.
</para>
<para>
Note that if you are porting <productname>Postgres</productname>
to a new platform, <command>LOAD</command>
will have to work in order to support ADTs.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-LOAD-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Load the file /usr/postgres/demo/circle.o
--
LOAD '/usr/postgres/demo/circle.o'
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

314
doc/src/sgml/ref/lock.sgml
View File

@@ -12,7 +12,7 @@ LOCK
<REFPURPOSE>
Explicit lock of a table inside a transaction
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -21,158 +21,170 @@ Explicit lock of a table inside a transaction
LOCK [ TABLE ] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LOCK-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table to lock.
</VARIABLELIST>
<REFSECT2 ID="R2-SQL-LOCK-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table to lock.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</REFSECT2>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LOCK-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
DELETE 0
</TERM>
<LISTITEM>
<PARA>
Message returned on a successful lock.
<command>LOCK</command> is implemented as a
<command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command>
which is guaranteed to not delete any rows.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist.
</TERM>
<LISTITEM>
<PARA>
Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT2 ID="R2-SQL-LOCK-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT1 ID="R1-SQL-LOCK-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>LOCK</command> locks in exclusive mode a table inside
a transaction. The classic use for this is
the case where you want to select some data, then
update it inside a transaction.
If you don't explicit lock a table using LOCK statement, it will be
implicit locked only at the first
<command>UPDATE</command>, <command>INSERT</command>,
or <command>DELETE</command> operation.
If you don't exclusive lock the table before the select, some
other user may also read the selected data, and try and do
their own update, causing a deadlock while you both wait
for the other to release the select-induced shared lock so
you can get an exclusive lock to do the update.
</para>
<para>
Another example of deadlock is where one user locks one
table, and another user locks a second table. While both
keep their existing locks, the first user tries to lock
the second user's table, and the second user tries to lock
the first user's table. Both users deadlock waiting for
the tables to become available. The only solution to this
is for both users to lock tables in the same order, so
user's lock acquisitions and requests to not form a deadlock.
</para>
<note>
<para>
<productname>Postgres</productname> does detect deadlocks and will
rollback transactions to resolve the deadlock. Usually, at least one
of the deadlocked transactions will complete successfully.
</para>
</note>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
DELETE 0
</TERM>
<LISTITEM>
<PARA>
Message returned on a successful lock.
<command>LOCK</command> is implemented as a
<command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command>
which is guaranteed to not delete any rows.
<VARLISTENTRY>
<TERM>
ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist.
</TERM>
<LISTITEM>
<PARA>
Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
does not exist.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LOCK-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>LOCK</command> locks in exclusive mode a table inside
a transaction. The classic use for this is
the case where you want to select some data, then
update it inside a transaction.
If you don't explicit lock a table using LOCK statement, it will be
implicit locked only at the first
<command>UPDATE</command>, <command>INSERT</command>,
or <command>DELETE</command> operation.
If you don't exclusive lock the table before the select, some
other user may also read the selected data, and try and do
their own update, causing a deadlock while you both wait
for the other to release the select-induced shared lock so
you can get an exclusive lock to do the update.
<para>
Another example of deadlock is where one user locks one
table, and another user locks a second table. While both
keep their existing locks, the first user tries to lock
the second user's table, and the second user tries to lock
the first user's table. Both users deadlock waiting for
the tables to become available. The only solution to this
is for both users to lock tables in the same order, so
user's lock acquisitions and requests to not form a deadlock.
<note>
<para>
<productname>Postgres</productname> does detect deadlocks and will
rollback transactions to resolve the deadlock. Usually, at least one
of the deadlocked transactions will complete successfully.
</note>
<REFSECT2 ID="R2-SQL-LOCK-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<command>LOCK</command> is a <productname>Postgres</productname>
language extension.
<para>
<command>LOCK</command> works only inside transactions.
<note>
<title>Bug</title>
<para>
If the locked table is dropped then it will be automatically
unlocked even if a transaction is still in progress.
</note>
</REFSECT2>
<REFSECT1 ID="R1-SQL-LOCK-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
--Explicit locking to prevent deadlock:
--
BEGIN WORK;
LOCK films;
SELECT * FROM films;
UPDATE films SET len = INTERVAL '100 minute'
WHERE len = INTERVAL '117 minute';
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOCK-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-LOCK-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
which instead uses <command>SET TRANSACTION</command> to specify
concurrency level on transactions.
<REFSECT2 ID="R2-SQL-LOCK-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<command>LOCK</command> is a <productname>Postgres</productname>
language extension.
</para>
<para>
<command>LOCK</command> works only inside transactions.
<note>
<title>Bug</title>
<para>
If the locked table is dropped then it will be automatically
unlocked even if a transaction is still in progress.
</para>
</note>
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-LOCK-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
--Explicit locking to prevent deadlock:
--
BEGIN WORK;
LOCK films;
SELECT * FROM films;
UPDATE films SET len = INTERVAL '100 minute'
WHERE len = INTERVAL '117 minute';
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOCK-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-LOCK-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
which instead uses <command>SET TRANSACTION</command> to specify
concurrency level on transactions.
</para>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,7 +12,7 @@ MOVE
<REFPURPOSE>
Moves cursor position
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -21,99 +21,104 @@ Moves cursor position
MOVE [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] [ <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> ]
{ IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
FETCH [ RELATIVE ] [ { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL | NEXT | PRIOR ] } ] FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</SYNOPSIS>
</SYNOPSIS>
</refsynopsisdiv>
<REFSECT1 ID="R1-SQL-MOVE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>MOVE</command> allows a user to move cursor position a specified
number of rows.
<command>MOVE</command> works like the <command>FETCH</command> command,
but only positions the cursor and does
not return rows.
<REFSECT1 ID="R1-SQL-MOVE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>MOVE</command> allows a user to move cursor position a specified
number of rows.
<command>MOVE</command> works like the <command>FETCH</command> command,
but only positions the cursor and does
not return rows.
</para>
<para>
Refer to the <command>FETCH</command> command for details on syntax and usage.
</para>
<para>
Refer to the <command>FETCH</command> command for details on syntax and usage.
<REFSECT2 ID="R2-SQL-MOVE-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<command>MOVE</command> is a <productname>Postgres</productname>
language extension.
</para>
<para>
Refer to <command>FETCH</command> for a description
of valid arguments.
Refer to <command>DECLARE</command> to declare a cursor.
Refer to <command>BEGIN WORK</command>, <command>COMMIT WORK</command>,
<command>ROLLBACK WORK</command> statements
for further information about transactions.
</para>
</REFSECT2>
</refsect1>
<REFSECT2 ID="R2-SQL-MOVE-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<command>MOVE</command> is a <productname>Postgres</productname>
language extension.
<para>
Refer to <command>FETCH</command> for a description
of valid arguments.
Refer to <command>DECLARE</command> to declare a cursor.
Refer to <command>BEGIN WORK</command>, <command>COMMIT WORK</command>,
<command>ROLLBACK WORK</command> statements
for further information about transactions.
</REFSECT2>
<REFSECT1 ID="R1-SQL-MOVE-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--set up and use a cursor:
--
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM films;
--Skip first 5 rows:
--
MOVE FORWARD 5 IN liahona;
<computeroutput>
MOVE
</computeroutput>
--Fetch 6th row in the cursor liahona:
--
FETCH 1 IN liahona;
<computeroutput>
FETCH
code |title |did| date_prod|kind |len
-----+------+---+----------+----------+------
P_303|48 Hrs|103|1982-10-22|Action | 01:37
(1 row)
</computeroutput>
-- close the cursor liahona and commit work:
--
CLOSE liahona;
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-MOVE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-MOVE-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no SQL92 <command>MOVE</command> statement.
Instead, <acronym>SQL92</acronym> allows
one to <command>FETCH</command> rows from an absolute cursor position,
implicitly moving the cursor to the correct place.
<REFSECT1 ID="R1-SQL-MOVE-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--set up and use a cursor:
--
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM films;
--Skip first 5 rows:
--
MOVE FORWARD 5 IN liahona;
<computeroutput>
MOVE
</computeroutput>
--Fetch 6th row in the cursor liahona:
--
FETCH 1 IN liahona;
<computeroutput>
FETCH
code |title |did| date_prod|kind |len
-----+------+---+----------+----------+------
P_303|48 Hrs|103|1982-10-22|Action | 01:37
(1 row)
</computeroutput>
-- close the cursor liahona and commit work:
--
CLOSE liahona;
COMMIT WORK;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-MOVE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-MOVE-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no SQL92 <command>MOVE</command> statement.
Instead, <acronym>SQL92</acronym> allows
one to <command>FETCH</command> rows from an absolute cursor position,
implicitly moving the cursor to the correct place.
</para>
</refsect2>
</refsect1>
</REFENTRY>

409
doc/src/sgml/ref/notify.sgml
View File

@@ -12,7 +12,7 @@ NOTIFY
<REFPURPOSE>
Signals all frontends and backends listening on a notify condition
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-07</DATE>
@@ -23,208 +23,215 @@ Signals all frontends and backends listening on a notify condition
NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-NOTIFY-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-NOTIFY-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Notify condition to be signaled.
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Notify condition to be signaled.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</VARIABLELIST>
<REFSECT2 ID="R2-SQL-NOTIFY-2">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTIFY
</TERM>
<LISTITEM>
<PARA>
Acknowledgement that notify command has executed.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
Notify events
</TERM>
<LISTITEM>
<PARA>
Events are delivered to listening frontends; whether and how each frontend
application reacts depends on its programming.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-NOTIFY-1">
<REFSECT1INFO>
<DATE>1998-10-07</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The <command>NOTIFY</command> command sends a notify event to each
frontend application that has previously executed
<command>LISTEN <replaceable class="parameter">notifyname</replaceable></command>
for the specified notify condition in the current database.
</para>
<para>
The information passed to the frontend for a notify event includes the notify
condition name and the notifying backend process's PID. It is up to the
database designer to define the condition names that will be used in a given
database and what each one means.
</para>
<para>
Commonly, the notify condition name is the same as the name of some table in
the database, and the notify event essentially means "I changed this table,
take a look at it to see what's new". But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different condition names
to signal different sorts of changes to a single table.
</para>
<para>
<command>NOTIFY</command> provides a simple form of signal or
IPC (interprocess communication) mechanism for a collection of processes
accessing the same <productname>Postgres</productname> database.
Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere condition name) from notifier to
listener(s).
</para>
<para>
When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the
<command>NOTIFY</command> in a rule that is triggered by table updates.
In this way, notification happens automatically when the table is changed,
and the application programmer can't accidentally forget to do it.
</para>
<para>
<command>NOTIFY</command> interacts with SQL transactions in some important
ways. Firstly, if a <command>NOTIFY</command> is executed inside a
transaction, the notify events are not delivered until and unless the
transaction is committed. This is appropriate, since if the transaction
is aborted we would like all the commands within it to have had no effect
--- including <command>NOTIFY</command>. But it can be disconcerting if one
is expecting the notify events to be delivered immediately. Secondly, if
a listening backend receives a notify signal while it is within a transaction,
the notify event will not be delivered to its connected frontend until just
after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notify were delivered within a transaction that was
later aborted, one would want the notification to be undone somehow --- but
the backend cannot "take back" a notify once it has sent it to the frontend.
So notify events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling
should try to keep their transactions short.
</para>
<para>
<command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same condition name is signaled multiple times in quick
succession, recipients may get only one notify event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifies received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times
it happened.
</para>
<para>
It is common for a frontend that sends <command>NOTIFY</command> to be
listening on the same notify name itself. In that case it will get back a
notify event, just like all the other listening frontends. Depending on the
application logic, this could result in useless work --- for example,
re-reading a database table to find the same updates that that frontend just
wrote out. In <productname>Postgres</productname> 6.4 and later, it is
possible to avoid such extra work by noticing whether the notifying backend
process's PID (supplied in the notify event message) is the same as one's own
backend's PID (available from libpq). When they are the same, the notify
event is one's own work bouncing back, and can be ignored. (Despite what was
said in the preceding paragraph, this is a safe technique.
<productname>Postgres</productname> keeps self-notifies separate from notifies
arriving from other backends, so you cannot miss an outside notify by ignoring
your own notifies.)
</para>
<REFSECT2 ID="R2-SQL-NOTIFY-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
</para>
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</para>
<para>
In <productname>Postgres</productname> releases prior to 6.4, the backend
PID delivered in a notify message was always the PID of the frontend's own
backend. So it was not possible to distinguish one's own notifies from other
clients' notifies in those earlier releases.
</para>
</REFSECT2>
</refsect1>
</REFSECT2>
<REFSECT2 ID="R2-SQL-NOTIFY-2">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTIFY
</TERM>
<LISTITEM>
<PARA>
Acknowledgement that notify command has executed.
<VARLISTENTRY>
<TERM>
Notify events
</TERM>
<LISTITEM>
<PARA>
Events are delivered to listening frontends; whether and how each frontend
application reacts depends on its programming.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-NOTIFY-1">
<REFSECT1INFO>
<DATE>1998-10-07</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The <command>NOTIFY</command> command sends a notify event to each
frontend application that has previously executed
<command>LISTEN <replaceable class="parameter">notifyname</replaceable></command>
for the specified notify condition in the current database.
<para>
The information passed to the frontend for a notify event includes the notify
condition name and the notifying backend process's PID. It is up to the
database designer to define the condition names that will be used in a given
database and what each one means.
<para>
Commonly, the notify condition name is the same as the name of some table in
the database, and the notify event essentially means "I changed this table,
take a look at it to see what's new". But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different condition names
to signal different sorts of changes to a single table.
<para>
<command>NOTIFY</command> provides a simple form of signal or
IPC (interprocess communication) mechanism for a collection of processes
accessing the same <productname>Postgres</productname> database.
Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere condition name) from notifier to
listener(s).
<para>
When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the
<command>NOTIFY</command> in a rule that is triggered by table updates.
In this way, notification happens automatically when the table is changed,
and the application programmer can't accidentally forget to do it.
<para>
<command>NOTIFY</command> interacts with SQL transactions in some important
ways. Firstly, if a <command>NOTIFY</command> is executed inside a
transaction, the notify events are not delivered until and unless the
transaction is committed. This is appropriate, since if the transaction
is aborted we would like all the commands within it to have had no effect
--- including <command>NOTIFY</command>. But it can be disconcerting if one
is expecting the notify events to be delivered immediately. Secondly, if
a listening backend receives a notify signal while it is within a transaction,
the notify event will not be delivered to its connected frontend until just
after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notify were delivered within a transaction that was
later aborted, one would want the notification to be undone somehow --- but
the backend cannot "take back" a notify once it has sent it to the frontend.
So notify events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling
should try to keep their transactions short.
<para>
<command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same condition name is signaled multiple times in quick
succession, recipients may get only one notify event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifies received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times
it happened.
<para>
It is common for a frontend that sends <command>NOTIFY</command> to be
listening on the same notify name itself. In that case it will get back a
notify event, just like all the other listening frontends. Depending on the
application logic, this could result in useless work --- for example,
re-reading a database table to find the same updates that that frontend just
wrote out. In <productname>Postgres</productname> 6.4 and later, it is
possible to avoid such extra work by noticing whether the notifying backend
process's PID (supplied in the notify event message) is the same as one's own
backend's PID (available from libpq). When they are the same, the notify
event is one's own work bouncing back, and can be ignored. (Despite what was
said in the preceding paragraph, this is a safe technique.
<productname>Postgres</productname> keeps self-notifies separate from notifies
arriving from other backends, so you cannot miss an outside notify by ignoring
your own notifies.)
<REFSECT2 ID="R2-SQL-NOTIFY-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
<para>
In <productname>Postgres</productname> releases prior to 6.4, the backend
PID delivered in a notify message was always the PID of the frontend's own
backend. So it was not possible to distinguish one's own notifies from other
clients' notifies in those earlier releases.
</REFSECT2>
<REFSECT1 ID="R1-SQL-NOTIFY-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-NOTIFY-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-NOTIFY-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>NOTIFY</command> statement in <acronym>SQL92</acronym>.
<REFSECT1 ID="R1-SQL-NOTIFY-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-NOTIFY-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-NOTIFY-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>NOTIFY</command> statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

667
doc/src/sgml/ref/pg_dump.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Extract a <productname>Postgres</productname> database into a script file
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-11-05</DATE>
@@ -25,308 +26,386 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceab
[ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMP-1">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dump</application> accepts the following command line arguments:
<REFSECT2 ID="R2-APP-PG-DUMP-1">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dump</application> accepts the following command line arguments:
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be extracted.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-f <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para>
Specifies the output file. Defaults to <filename>stdout</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
This was the default behavior in pre-v6.4 <application>pg_dump</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-N
</term>
<listitem>
<para>
Include double quotes around identifiers.
This is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-t <replaceable class="parameter">table</replaceable>
</term>
<listitem>
<para>
Dump data for <replaceable class="parameter">table</replaceable> only.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be extracted.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
</para>
<para>
<application>pg_dump</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
</variablelist>
</para>
</refsect2>
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
<REFSECT2 ID="R2-APP-PG-DUMP-2">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dump</application> will create a file or
write to <filename>stdout</filename>.
<varlistentry>
<term>
-f <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para>
Specifies the output file. Defaults to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
</term>
<listitem>
<para>
<application>pg_dump</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
</term>
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
<application>pg_dump</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dump</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-PG-DUMP-1">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dump</application> is a utility for dumping out a
<productname>Postgres</productname> database into a script file
containing query commands. The script
files are in text format and can be used to reconstruct the database,
even on other machines and other architectures.
<application>pg_dump</application>
will produce the queries necessary to re-generate all
user-defined types, functions, tables, indices, aggregates, and
operators. In addition, all the data is copied out in text format so
that it can be readily copied in again, as well as imported into tools
for editing.
</para>
<para>
<application>pg_dump</application>
is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another. After running
<application>pg_dump</application>,
one should examine the output script file for any warnings, especially
in light of the limitations listed below.
</para>
</refsect1>
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
This was the default behavior in pre-v6.4 <application>pg_dump</application>.
<REFSECT1 ID="R1-APP-PG-DUMP-2">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<application>pg_dump</application> has a few limitations.
The limitations mostly stem from
difficulty in extracting certain meta-information from the system
catalogs.
<varlistentry>
<term>
-N
</term>
<listitem>
<para>
Include double quotes around identifiers.
This is the default.
<variablelist>
<varlistentry>
<term>
partial indices
</term>
<listitem>
<para>
<application>pg_dump</application>
does not understand partial indices. The reason is
the same as above; partial index predicates are stored as plans.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
<varlistentry>
<term>
large objects
</term>
<listitem>
<para>
<application>pg_dump</application> does not handle large objects.
Large objects are ignored and must be dealt with manually.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
<varlistentry>
<term>
-t <replaceable class="parameter">table</replaceable>
</term>
<listitem>
<para>
Dump data for <replaceable class="parameter">table</replaceable> only.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</variablelist>
<para>
<application>pg_dump</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</variablelist>
<REFSECT2 ID="R2-APP-PG-DUMP-2">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dump</application> will create a file or
write to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>pg_dump</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</variablelist>
<note>
<para>
<application>pg_dump</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dump</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</note>
<REFSECT1 ID="R1-APP-PG-DUMP-1">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dump</application> is a utility for dumping out a
<productname>Postgres</productname> database into a script file
containing query commands. The script
files are in text format and can be used to reconstruct the database,
even on other machines and other architectures.
<application>pg_dump</application>
will produce the queries necessary to re-generate all
user-defined types, functions, tables, indices, aggregates, and
operators. In addition, all the data is copied out in text format so
that it can be readily copied in again, as well as imported into tools
for editing.
<para>
<application>pg_dump</application>
is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another. After running
<application>pg_dump</application>,
one should examine the output script file for any warnings, especially
in light of the limitations listed below.
<REFSECT1 ID="R1-APP-PG-DUMP-2">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<application>pg_dump</application> has a few limitations.
The limitations mostly stem from
difficulty in extracting certain meta-information from the system
catalogs.
<variablelist>
<varlistentry>
<term>
partial indices
<listitem>
<para>
<application>pg_dump</application>
does not understand partial indices. The reason is
the same as above; partial index predicates are stored as plans.
<varlistentry>
<term>
large objects
<listitem>
<para>
<application>pg_dump</application> does not handle large objects.
Large objects are ignored and must be dealt with manually.
</variablelist>
<REFSECT1 ID="R1-APP-PG-DUMP-3">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump a database of the same name as the user:
<programlisting>
% pg_dump > db.out
</programlisting>
<para>
To reload this database:
<programlisting>
psql -e database < db.out
</programlisting>
<REFSECT1 ID="R1-APP-PG-DUMP-3">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump a database of the same name as the user:
<programlisting>
% pg_dump > db.out
</programlisting>
</para>
<para>
To reload this database:
<programlisting>
psql -e database < db.out
</programlisting>
</para>
</refsect1>
</REFENTRY>

526
doc/src/sgml/ref/pg_dumpall.sgml
View File

@@ -12,6 +12,7 @@
<REFPURPOSE>
Extract all <productname>Postgres</productname> databases into a script file
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
@@ -22,246 +23,301 @@ pg_dumpall [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replac
[ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMPALL-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dumpall</application> accepts the following command line arguments:
<REFSECT2 ID="R2-APP-PG-DUMPALL-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dumpall</application> accepts the following command line arguments:
<variablelist>
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<application>pg_dumpall</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
<REFSECT2 ID="R2-APP-PG-DUMPALL-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dumpall</application> will create a file or
write to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
</term>
<listitem>
<para>
<application>pg_dumpall</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
</term>
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
<note>
<para>
<application>pg_dumpall</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dumpall</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-PG-DUMPALL-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dumpall</application>
is a utility for dumping out all Postgres databases into one file.
It also dumps the pg_shadow table, which is global to all databases.
<application>pg_dumpall</application> includes in this file the proper commands
to automatically create each dumped database before loading.
</para>
<para>
<application>pg_dumpall</application> takes all <application>pg_dump</application>
options, but <option>-f</option>, <option>-t</option> and
<replaceable class="parameter">dbname</replaceable>
should be omitted.
</para>
<para>
Refer to
<xref linkend="app-pg-dump" endterm="pg-dump">
for more information on this capability.
</para
</refsect1>
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
<REFSECT1 ID="R1-APP-PG-DUMPALL-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump all databases:
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</variablelist>
<para>
<application>pg_dumpall</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</variablelist>
<REFSECT2 ID="R2-APP-PG-DUMPALL-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dumpall</application> will create a file or
write to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>pg_dumpall</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</variablelist>
<note>
<para>
<application>pg_dumpall</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dumpall</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</note>
<REFSECT1 ID="R1-APP-PG-DUMPALL-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dumpall</application>
is a utility for dumping out all Postgres databases into one file.
It also dumps the pg_shadow table, which is global to all databases.
<application>pg_dumpall</application> includes in this file the proper commands
to automatically create each dumped database before loading.
<para>
<application>pg_dumpall</application> takes all <application>pg_dump</application>
options, but <option>-f</option>, <option>-t</option> and
<replaceable class="parameter">dbname</replaceable>
should be omitted.
<para>
Refer to
<xref linkend="app-pg-dump" endterm="pg-dump">
for more information on this capability.
<REFSECT1 ID="R1-APP-PG-DUMPALL-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump all databases:
<programlisting>
% pg_dumpall -o > db.out
</programlisting>
<tip>
<para>
You can use most <application>pg_dump</application> options
for <application>pg_dumpall</application>.
</tip>
<para>
To reload this database:
<programlisting>
psql -e template1 < db.out
</programlisting>
<tip>
<para>
You can use most <application>psql</application> options
when reloading.
</tip>
<programlisting>
% pg_dumpall -o > db.out
</programlisting>
<tip>
<para>
You can use most <application>pg_dump</application> options
for <application>pg_dumpall</application>.
</para>
</tip>
</para>
<para>
To reload this database:
<programlisting>
psql -e template1 < db.out
</programlisting>
</para>
<tip>
<para>
You can use most <application>psql</application> options
when reloading.
</para>
</tip>
</refsect1>
</REFENTRY>

1873
doc/src/sgml/ref/psql-ref.sgml
View File

File diff suppressed because it is too large Load Diff

223
doc/src/sgml/ref/reset.sgml
View File

@@ -12,7 +12,7 @@ RESET
<REFPURPOSE>
Restores run-time parameters for session to default values
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -21,115 +21,122 @@ Restores run-time parameters for session to default values
RESET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-RESET-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-RESET-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to the SET statement for more information on available
variables.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to the SET statement for more information on available
variables.
</variablelist>
<REFSECT2 ID="R2-SQL-RESET-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
RESET VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is successfully reset
to its default value..
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-RESET-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>RESET</command> restores variables to the
default values.
Refer to the <command>SET</command> command for details on
allowed values and defaults.
<command>RESET</command> is an alternate form for
<synopsis>
<command>SET <replaceable class="parameter">variable</replaceable> = DEFAULT</command>
</synopsis>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-RESET-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The RESET statement is a <productname>Postgres</productname> language extension.
</para>
<para>
Refer to SET/SHOW statements to set/show variable values.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-RESET-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- reset DateStyle to its default;
RESET DateStyle;
</programlisting>
<programlisting>
-- reset Geqo to its default;
RESET GEQO;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT2 ID="R2-SQL-RESET-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
RESET VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is successfully reset
to its default value..
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-RESET-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>RESET</command> restores variables to the
default values.
Refer to the <command>SET</command> command for details on
allowed values and defaults.
<command>RESET</command> is an alternate form for
<synopsis>
<command>SET <replaceable class="parameter">variable</replaceable> = DEFAULT</command>
</synopsis>
<REFSECT2 ID="R2-SQL-RESET-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The RESET statement is a <productname>Postgres</productname> language extension.
<para>
Refer to SET/SHOW statements to set/show variable values.
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-RESET-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- reset DateStyle to its default;
RESET DateStyle;
</programlisting>
<programlisting>
-- reset Geqo to its default;
RESET GEQO;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-RESET-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-RESET-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>RESET</command> in <acronym>SQL92</acronym>.
<REFSECT1 ID="R1-SQL-RESET-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-RESET-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>RESET</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

652
doc/src/sgml/ref/revoke.sgml
View File

@@ -12,7 +12,7 @@ REVOKE
<REFPURPOSE>
Revokes access privilege from a user, a group or all users.
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -25,312 +25,360 @@ REVOKE <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
FROM { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-REVOKE-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-REVOKE-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The possible privileges are:
</para>
</listitem>
</varlistentry>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The possible privileges are:
<VARLISTENTRY>
<TERM>
SELECT
</TERM>
<LISTITEM>
<PARA>
Privilege to access all of the columns of a specific
table/view.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
INSERT
</TERM>
<LISTITEM>
<PARA>
Privilege to insert data into all columns of a
specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
UPDATE
</TERM>
<LISTITEM>
<PARA>
Privilege to update all columns of a specific
table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
DELETE
</TERM>
<LISTITEM>
<PARA>
Privilege to delete rows from a specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
RULE
</TERM>
<LISTITEM>
<PARA>
Privilege to define rules on table/view.
(See <command>CREATE RULE</command>).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Rescind all privileges.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an object from which to revoke access.
The possible objects are:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
table
</para>
</listitem>
<listitem>
<para>
view
</para>
</listitem>
<listitem>
<para>
sequence
</para>
</listitem>
<listitem>
<para>
index
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a group from whom to revoke privileges.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a user from whom revoke privileges. Use the PUBLIC keyword
to specify all users.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
PUBLIC
</TERM>
<LISTITEM>
<PARA>
Rescind the specified privilege(s) for all users.
</para>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
SELECT
</TERM>
<LISTITEM>
<PARA>
Privilege to access all of the columns of a specific
table/view.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<REFSECT2 ID="R2-SQL-REVOKE-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ERROR
</TERM>
<LISTITEM>
<PARA>
Message returned if object is not available or impossible
to revoke privileges from a group or users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-REVOKE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
REVOKE allows creator of an object to revoke permissions granted
before, from all users (via PUBLIC) or a certain user or group.
</para>
<VARLISTENTRY>
<TERM>
INSERT
</TERM>
<LISTITEM>
<PARA>
Privilege to insert data into all columns of a
specific table.
<VARLISTENTRY>
<TERM>
UPDATE
</TERM>
<LISTITEM>
<PARA>
Privilege to update all columns of a specific
table.
<VARLISTENTRY>
<TERM>
DELETE
</TERM>
<LISTITEM>
<PARA>
Privilege to delete rows from a specific table.
<VARLISTENTRY>
<TERM>
RULE
</TERM>
<LISTITEM>
<PARA>
Privilege to define rules on table/view.
(See <command>CREATE RULE</command>).
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Rescind all privileges.
</VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an object from which to revoke access.
The possible objects are:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
table
<listitem>
<para>
view
<listitem>
<para>
sequence
<listitem>
<para>
index
</itemizedlist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a group from whom to revoke privileges.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a user from whom revoke privileges. Use the PUBLIC keyword
to specify all users.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
PUBLIC
</TERM>
<LISTITEM>
<PARA>
Rescind the specified privilege(s) for all users.
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-REVOKE-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully.
<VARLISTENTRY>
<TERM>
ERROR
</TERM>
<LISTITEM>
<PARA>
Message returned if object is not available or impossible
to revoke privileges from a group or users.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-REVOKE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
REVOKE allows creator of an object to revoke permissions granted
before, from all users (via PUBLIC) or a certain user or group.
<REFSECT2 ID="R2-SQL-REVOKE-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to psql \z command for further information about permissions
on existing objects:
<programlisting>
Database = lusitania
+------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions |
+------------------+---------------------------------------------+
| mytable | {"=rw","miriam=arwR","group todos=rw"} |
+------------------+---------------------------------------------+
Legend:
uname=arwR -- privileges granted to a user
group gname=arwR -- privileges granted to a GROUP
=arwR -- privileges granted to PUBLIC
r -- SELECT
w -- UPDATE/DELETE
a -- INSERT
R -- RULE
arwR -- ALL
</programlisting>
<tip>
<para>
Currently, to create a GROUP you have to insert
<REFSECT2 ID="R2-SQL-REVOKE-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to psql \z command for further information about permissions
on existing objects:
<programlisting>
Database = lusitania
+------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions |
+------------------+---------------------------------------------+
| mytable | {"=rw","miriam=arwR","group todos=rw"} |
+------------------+---------------------------------------------+
Legend:
uname=arwR -- privileges granted to a user
group gname=arwR -- privileges granted to a GROUP
=arwR -- privileges granted to PUBLIC
r -- SELECT
w -- UPDATE/DELETE
a -- INSERT
R -- RULE
arwR -- ALL
</programlisting>
</para>
<tip>
<para>
Currently, to create a GROUP you have to insert
data manually into table pg_group as:
<programlisting>
INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos;
</programlisting>
</tip>
<programlisting>
INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos;
</programlisting>
</para>
</tip>
</REFSECT2>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-REVOKE-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- revoke insert privilege from all users on table films:
--
REVOKE INSERT ON films FROM PUBLIC;
<REFSECT1 ID="R1-SQL-REVOKE-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- revoke insert privilege from all users on table films:
--
REVOKE INSERT ON films FROM PUBLIC;
-- revoke all privileges from user manuel on view kinds:
--
REVOKE ALL ON kinds FROM manuel;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-REVOKE-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-REVOKE-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The SQL92 syntax for <command>REVOKE</command>
has additional capabilities for rescinding
privileges, including those on individual columns in tables:
-- revoke all privileges from user manuel on view kinds:
--
REVOKE ALL ON kinds FROM manuel;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-REVOKE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-REVOKE-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The SQL92 syntax for <command>REVOKE</command>
has additional capabilities for rescinding
privileges, including those on individual columns in tables:
<variablelist>
<varlistentry>
<term>
<synopsis>
REVOKE { SELECT | DELETE | USAGE | ALL PRIVILEGES } [, ...]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
REVOKE { INSERT | UPDATE | REFERENCES } [, ...] [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis>
<listitem>
<para>
Refer to the <command>GRANT</command> command for details on individual fields.
<varlistentry>
<term>
<synopsis>
REVOKE GRANT OPTION FOR <replaceable class="parameter">privilege</replaceable> [, ...]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis>
<listitem>
<para>
Rescinds authority for a user to grant the specified privilege to others.
Refer to the <command>GRANT</command> command for details on individual fields.
</variablelist>
<para>
The possible objects are:
<simplelist>
<member> [ TABLE ] table/view
<member> CHARACTER SET character-set
<member> COLLATION collation
<member> TRANSLATION translation
<member> DOMAIN domain
</simplelist>
<para>
If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then user1 can revoke
this privilege in cascade using the CASCADE keyword.
<para>
If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then if user1 try revoke
this privilege it fails if he/she specify the RESTRICT
keyword.
<variablelist>
<varlistentry>
<term>
<synopsis>
REVOKE { SELECT | DELETE | USAGE | ALL PRIVILEGES } [, ...]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
REVOKE { INSERT | UPDATE | REFERENCES } [, ...] [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis>
</term>
<listitem>
<para>
Refer to the <command>GRANT</command> command for details on individual fields.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<synopsis>
REVOKE GRANT OPTION FOR <replaceable class="parameter">privilege</replaceable> [, ...]
ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis>
</term>
<listitem>
<para>
Rescinds authority for a user to grant the specified privilege to others.
Refer to the <command>GRANT</command> command for details on individual fields.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The possible objects are:
<simplelist>
<member> [ TABLE ] table/view
</member>
<member> CHARACTER SET character-set
</member>
<member> COLLATION collation
</member>
<member> TRANSLATION translation
</member>
<member> DOMAIN domain
</member>
</simplelist>
</para>
<para>
If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then user1 can revoke
this privilege in cascade using the CASCADE keyword.
</para>
<para>
If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then if user1 try revoke
this privilege it fails if he/she specify the RESTRICT
keyword.
</para>
</refsect2>
</refsect1>
</REFENTRY>

205
doc/src/sgml/ref/rollback.sgml
View File

@@ -12,6 +12,7 @@ ROLLBACK
<REFPURPOSE>
Aborts the current transaction
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -20,105 +21,113 @@ Aborts the current transaction
ROLLBACK [ WORK ]
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-ROLLBACK-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
<REFSECT2 ID="R2-SQL-ROLLBACK-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
</para>
</REFSECT2>
</REFSECT2>
<REFSECT2 ID="R2-SQL-ROLLBACK-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
ABORT
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
</para>
</listitem>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state
ABORT
</TERM>
<LISTITEM>
<PARA>
If there is not any transaction currently in progress.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT2 ID="R2-SQL-ROLLBACK-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT1 ID="R1-SQL-ROLLBACK-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>ROLLBACK</command> rolls back the current transaction and causes
all the updates made by the transaction to be discarded.
</para>
<REFSECT2 ID="R2-SQL-ROLLBACK-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The keyword WORK is noise and can be omitted.
</para>
<para>
Use the <command>COMMIT</command> statement to successfully
terminate a transaction.
</para>
</refsect2>
</REFSECT1>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
ABORT
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
<VARLISTENTRY>
<TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state
ABORT
</TERM>
<LISTITEM>
<PARA>
If there is not any transaction currently in progress.
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-ROLLBACK-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>ROLLBACK</command> rolls back the current transaction and causes
all the updates made by the transaction to be discarded.
<REFSECT2 ID="R2-SQL-ROLLBACK-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The keyword WORK is noise and can be omitted.
<para>
Use the <command>COMMIT</command> statement to successfully
terminate a transaction.
</REFSECT1>
<REFSECT1 ID="R1-SQL-ROLLBACK-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--To abort all changes:
--
ROLLBACK WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-ROLLBACK-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-ROLLBACK-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
Full compatibility.
<REFSECT1 ID="R1-SQL-ROLLBACK-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--To abort all changes:
--
ROLLBACK WORK;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-ROLLBACK-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-ROLLBACK-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
Full compatibility.
</para>
</refsect2>
</refsect1>
</REFENTRY>

86
doc/src/sgml/ref/select.sgml
View File

@@ -156,29 +156,32 @@ SELECT [ALL|DISTINCT [ON <replaceable class="PARAMETER">column</replaceable>] ]
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term>
Rows
</term>
<listitem>
<para>
The complete set of rows resulting from the query specification.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<returnvalue><replaceable>count</replaceable></returnvalue>
</term>
<listitem>
<para>
The count of rows returned by the query.
</variablelist>
<para>
<variablelist>
<varlistentry>
<term>
Rows
</term>
<listitem>
<para>
The complete set of rows resulting from the query specification.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<returnvalue><replaceable>count</replaceable></returnvalue>
</term>
<listitem>
<para>
The count of rows returned by the query.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
@@ -513,6 +516,7 @@ SELECT distributors.* WHERE name = 'Westwood';
108|Westward
</programlisting>
</para>
</refsect2>
<refsect2 id="R2-SQL-SELECT-5">
<refsect2info>
@@ -613,6 +617,8 @@ SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable
</title>
<para>
All input fields are described in detail for SELECT.
</para>
</refsect2>
<refsect2 id="R2-SQL-SELECTINTO-2">
<refsect2info>
@@ -623,22 +629,26 @@ All input fields are described in detail for SELECT.
</title>
<para>
All output fields are described in detail for SELECT.
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-SELECTINTO-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
SELECT INTO creates a new table from the results of a query. Typically, this
query draws data from an existing table, but any SQL query is allowed.
<note>
<para>
CREATE TABLE AS is functionally equivalent to the SELECT INTO command.
</note>
<refsect1 id="R1-SQL-SELECTINTO-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
SELECT INTO creates a new table from the results of a query. Typically, this
query draws data from an existing table, but any SQL query is allowed.
<note>
<para>
CREATE TABLE AS is functionally equivalent to the SELECT INTO command.
</para>
</note>
</para>
</refsect1>
</refentry>

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

File diff suppressed because it is too large Load Diff

278
doc/src/sgml/ref/show.sgml
View File

@@ -12,6 +12,7 @@ SHOW
<REFPURPOSE>
Shows run-time parameters for session
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -20,144 +21,151 @@ Shows run-time parameters for session
SHOW <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-SHOW-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-SHOW-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to <command>SET</command> for more information on available
variables.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to <command>SET</command> for more information on available
variables.
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-SHOW-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is <replaceable>value</replaceable></ReturnValue>
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: Unrecognized variable <replaceable>value</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if <ReturnValue>value</ReturnValue> does not exist.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NOTICE: Time zone is unknown
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
If the TZ environment variable is not set.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT2 ID="R2-SQL-SHOW-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT1 ID="R1-SQL-SHOW-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>SHOW</command> will display the current
configuration parameters for
variable during a session.
</para>
<para>
The session can be configured using <command>SET</command> statement,
and values
can be restored to the defaults using <command>RESET</command> statement.
Parameters and values are case-insensitive.
</para>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is <replaceable>value</replaceable></ReturnValue>
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully.
</listitem>
<REFSECT2 ID="R2-SQL-SHOW-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The <command>SHOW</command> is a <productname>Postgres</productname>
language extension.
</para>
<para>
Refer to <command>SET</command>/<command>RESET</command>
to set/reset variable values.
See also <command>SET TIME ZONE</command>.
</para>
</REFSECT2>
</REFSECT1>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: Unrecognized variable <replaceable>value</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if <ReturnValue>value</ReturnValue> does not exist.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<REFSECT1 ID="R1-SQL-SHOW-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- show DateStyle;
SHOW DateStyle;
NOTICE:DateStyle is Postgres with US (NonEuropean) conventions
-- show Geqo;
SHOW GEQO;
NOTICE:GEQO is ON
</ProgramListing>
</para>
</REFSECT1>
<VARLISTENTRY>
<TERM>
NOTICE: Time zone is unknown
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
If the TZ environment variable is not set.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-SHOW-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>SHOW</command> will display the current
configuration parameters for
variable during a session.
<para>
The session can be configured using <command>SET</command> statement,
and values
can be restored to the defaults using <command>RESET</command> statement.
Parameters and values are case-insensitive.
<REFSECT2 ID="R2-SQL-SHOW-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The <command>SHOW</command> is a <productname>Postgres</productname>
language extension.
<para>
Refer to <command>SET</command>/<command>RESET</command>
to set/reset variable values.
See also <command>SET TIME ZONE</command>.
</REFSECT2>
</REFSECT1>
<REFSECT1 ID="R1-SQL-SHOW-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- show DateStyle;
SHOW DateStyle;
NOTICE:DateStyle is Postgres with US (NonEuropean) conventions
-- show Geqo;
SHOW GEQO;
NOTICE:GEQO is ON
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-SHOW-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-SHOW-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>SET</command> defined in <acronym>SQL92</acronym>.
</refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-SHOW-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-SHOW-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>SET</command> defined in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

30
doc/src/sgml/ref/unlisten.sgml
View File

@@ -12,7 +12,7 @@ UNLISTEN
<REFPURPOSE>
Stop listening for notification
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-19</DATE>
@@ -38,7 +38,9 @@ Inputs
<LISTITEM>
<PARA>
Name of previously registered notify condition.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<literal>*</literal>
@@ -46,6 +48,9 @@ Name of previously registered notify condition.
<LISTITEM>
<PARA>
All current listen registrations for this backend are cleared.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
@@ -68,8 +73,12 @@ Outputs
<LISTITEM>
<PARA>
Acknowledgement that statement has executed.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
@@ -88,12 +97,13 @@ UNLISTEN cancels any existing registration of the current
condition <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
The special condition wildcard "*" cancels all listener registrations
for the current session.
</para>
<para>
<xref linkend="sql-notify" endterm="sql-notify-ref">
contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
</para>
<REFSECT2 ID="R2-SQL-UNLISTEN-3">
<REFSECT2INFO>
@@ -106,21 +116,22 @@ Notes
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
needs not to be a valid class name but can be any string valid
as a name up to 32 characters long.
</para>
<para>
The backend does not complain if you UNLISTEN something you were not
listening for.
Each backend will automatically execute <command>UNLISTEN *</command> when
exiting.
</para>
<para>
A restriction in some previous releases of
<productname>Postgres</productname> that a
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
which does not correspond to an actual table must be enclosed in double-quotes
is no longer present.
</para>
</REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-UNLISTEN-2">
<TITLE>
@@ -144,14 +155,13 @@ NOTIFY
-- notice no NOTIFY event is received
postgres=>
</programlisting>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-UNLISTEN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-UNLISTEN-4">
<REFSECT2INFO>
@@ -162,5 +172,7 @@ SQL92
</TITLE>
<PARA>
There is no <command>UNLISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,7 +12,7 @@ UPDATE
<REFPURPOSE>
Replaces values of columns in a table
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
@@ -23,127 +23,134 @@ UPDATE <REPLACEABLE CLASS="PARAMETER">table</replaceable> SET <REPLACEABLE CLASS
[ WHERE <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> ]
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-UPDATE-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-UPDATE-1">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</replaceable>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table.
</para>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</replaceable>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</replaceable>.
</para>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</replaceable>
</TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to column.
</para>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">fromlist</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <productname>Postgres</productname>
non-standard extension to allow columns
from other tables to appear in the WHERE condition.
</para>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to the SELECT statement for a further description
of the WHERE clause.
</para>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-UPDATE-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
UPDATE <replaceable class="parameter">#</replaceable>
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
The <replaceable class="parameter">#</replaceable>
means the number of rows updated.
If <replaceable class="parameter">#</replaceable>
is equal 0 no rows are updated.
</para>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</replaceable>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table.
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</replaceable>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</replaceable>.
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</replaceable>
</TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to column.
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">fromlist</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <productname>Postgres</productname>
non-standard extension to allow columns
from other tables to appear in the WHERE condition.
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refer to the SELECT statement for a further description
of the WHERE clause.
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT1 ID="R1-SQL-UPDATE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
UPDATE changes the values of the columns specified for
all rows which satisfy condition. Only the columns
to be modified need appear as column.
</para>
<PARA>
Array references use the same syntax found in SELECT.
That is, either single array elements, a range of array
elements or the entire array may be replaced with a single
query.
</para>
<PARA>
You must have write access to the table in order to modify
it, as well as read access to any table whose values are
mentioned in the WHERE condition.
</para>
</REFSECT1>
<REFSECT2 ID="R2-SQL-UPDATE-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
UPDATE <replaceable class="parameter">#</replaceable>
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
The <replaceable class="parameter">#</replaceable>
means the number of rows updated.
If <replaceable class="parameter">#</replaceable>
is equal 0 no rows are updated.
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-UPDATE-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
UPDATE changes the values of the columns specified for
all rows which satisfy condition. Only the columns
to be modified need appear as column.
<PARA>
Array references use the same syntax found in SELECT.
That is, either single array elements, a range of array
elements or the entire array may be replaced with a single
query.
<PARA>
You must have write access to the table in order to modify
it, as well as read access to any table whose values are
mentioned in the WHERE condition.
</REFSECT1>
<REFSECT1 ID="R1-SQL-UPDATE-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
<REFSECT1 ID="R1-SQL-UPDATE-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
--Change word "Drama" with "Dramatic" on column kind:
--
UPDATE films
@@ -159,32 +166,35 @@ Usage
M_401|War and Peace|104|1967-02-12|Dramatic | 05:57
T_601|Yojimbo |106|1961-06-16|Dramatic | 01:50
DA101|Das Boot |110|1981-11-11|Dramatic | 02:29
</ProgramListing>
</ProgramListing>
</REFSECT1>
</REFSECT1>
<REFSECT1 ID="R1-SQL-UPDATE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT1 ID="R1-SQL-UPDATE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-UPDATE-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 defines a different syntax for positioned UPDATE statement:
<REFSECT2 ID="R2-SQL-UPDATE-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 defines a different syntax for positioned UPDATE statement:
<programlisting>
<programlisting>
UPDATE table SET column = expression [, ...]
WHERE CURRENT OF <replaceable class="parameter">cursor</replaceable>
</programlisting>
</programlisting>
where <replaceable class="parameter">cursor</replaceable>
identifies an open cursor.
where <replaceable class="parameter">cursor</replaceable>
identifies an open cursor.
</para>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@ VACUUM
<REFPURPOSE>
Clean and analyze a <productname>Postgres</productname> database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
@@ -21,163 +22,191 @@ VACUUM [ VERBOSE ] [ ANALYZE ] [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEAB
VACUUM [ VERBOSE ] ANALYZE [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ (<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] ]
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-VACUUM-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-VACUUM-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
VERBOSE
</term>
<LISTITEM>
<PARA>
Prints a detailed vacuum activity report for each table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
ANALYZE
</term>
<LISTITEM>
<PARA>
Updates column statistics used by the optimizer to
determine the most efficient way to execute a query.
The statistics represent the disbursion of the data in each column.
This information is valuable when several execution paths are possible.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</term>
<LISTITEM>
<PARA>
The name of a specific table to vacuum. Defaults to all tables.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</term>
<LISTITEM>
<PARA>
The name of a specific column to analyze. Defaults to all columns.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
VERBOSE
<LISTITEM>
<PARA>
Prints a detailed vacuum activity report for each table.
<REFSECT2 ID="R2-SQL-VACUUM-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARLISTENTRY>
<TERM>
ANALYZE
<LISTITEM>
<PARA>
Updates column statistics used by the optimizer to
determine the most efficient way to execute a query.
The statistics represent the disbursion of the data in each column.
This information is valuable when several execution paths are possible.
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>VACUUM</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The command has been accepted and the database is being cleaned.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
NOTICE: --Relation <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>--
</term>
<LISTITEM>
<PARA>
The report header for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
<LISTITEM>
<PARA>
The name of a specific table to vacuum. Defaults to all tables.
<VARLISTENTRY>
<TERM>
NOTICE: 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.
</term>
<LISTITEM>
<PARA>
The analysis for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> itself.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
NOTICE: Index <REPLACEABLE CLASS="PARAMETER">index</REPLACEABLE>: Pages 28;
Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
</term>
<LISTITEM>
<PARA>
The analysis for an index on the target table.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
<LISTITEM>
<PARA>
The name of a specific column to analyze. Defaults to all columns.
<REFSECT1 ID="R1-SQL-VACUUM-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>VACUUM</command> serves two purposes in
<productname>Postgres</productname> as both a means to reclaim storage and
also a means to collect information for the optimizer.
</para>
<para>
<command>VACUUM</command> opens every class in the database,
cleans out records from rolled back transactions, and updates statistics in the
system catalogs. The statistics maintained include the number of
tuples and number of pages stored in all classes.
</VARIABLELIST>
Running <command>VACUUM</command>
periodically will increase the speed of the database in processing user queries.
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-VACUUM-3">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The open database is target for <command>VACUUM</command>.
</para>
<para>
We recommend that active production databases be cleaned nightly, in order
to keep statistics relatively current. The <command>VACUUM</command>
query may be executed at any time, however. In particular, after
copying a large class into <productname>Postgres</productname>
or after deleting a large number of
records, it may be a good idea to issue a <command>VACUUM</command>
query. This will update the system catalogs with the results of all
recent changes, and allow the <productname>Postgres</productname>
query optimizer to make better choices in planning user queries.
</para>
<para>
If the server crashes during a <command>VACUUM</command> command,
chances are it will leave a lock file hanging around.
Attempts to re-run the <command>VACUUM</command> command
result in an error message about the creation of a lock file. If you
are sure <command>VACUUM</command> is not running,
remove the <filename>pg_vlock</filename> file in your
database directory
(i.e. <filename><envar>PGDATA</envar>/base/dbname/pg_vlock</filename>).
</PARA>
</REFSECT2>
</refsect1>
<REFSECT2 ID="R2-SQL-VACUUM-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>VACUUM</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The command has been accepted and the database is being cleaned.
<VARLISTENTRY>
<TERM>
NOTICE: --Relation <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>--
<LISTITEM>
<PARA>
The report header for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
NOTICE: 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.
<LISTITEM>
<PARA>
The analysis for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> itself.
<VARLISTENTRY>
<TERM>
NOTICE: Index <REPLACEABLE CLASS="PARAMETER">index</REPLACEABLE>: Pages 28;
Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
<LISTITEM>
<PARA>
The analysis for an index on the target table.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-VACUUM-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>VACUUM</command> serves two purposes in
<productname>Postgres</productname> as both a means to reclaim storage and
also a means to collect information for the optimizer.
<para>
<command>VACUUM</command> opens every class in the database,
cleans out records from rolled back transactions, and updates statistics in the
system catalogs. The statistics maintained include the number of
tuples and number of pages stored in all classes.
Running <command>VACUUM</command>
periodically will increase the speed of the database in processing user queries.
<REFSECT2 ID="R2-SQL-VACUUM-3">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The open database is target for <command>VACUUM</command>.
<para>
We recommend that active production databases be cleaned nightly, in order
to keep statistics relatively current. The <command>VACUUM</command>
query may be executed at any time, however. In particular, after
copying a large class into <productname>Postgres</productname>
or after deleting a large number of
records, it may be a good idea to issue a <command>VACUUM</command>
query. This will update the system catalogs with the results of all
recent changes, and allow the <productname>Postgres</productname>
query optimizer to make better choices in planning user queries.
<para>
If the server crashes during a <command>VACUUM</command> command,
chances are it will leave a lock file hanging around.
Attempts to re-run the <command>VACUUM</command> command
result in an error message about the creation of a lock file. If you
are sure <command>VACUUM</command> is not running,
remove the <filename>pg_vlock</filename> file in your
database directory
(i.e. <filename><envar>PGDATA</envar>/base/dbname/pg_vlock</filename>).
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-VACUUM-2">
<TITLE>
Usage
</TITLE>
<PARA>
The following is an example from running <command>VACUUM</command> on a table
in the regression database:
<ProgramListing>
<REFSECT1 ID="R1-SQL-VACUUM-2">
<TITLE>
Usage
</TITLE>
<PARA>
The following is an example from running <command>VACUUM</command> on a table
in the regression database:
<ProgramListing>
regression=> vacuum verbose analyze onek;
NOTICE: --Relation onek--
NOTICE: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
@@ -194,24 +223,24 @@ NOTICE: Index onek_hundred: Pages 12; Tuples 1000: Deleted 1000. Elapsed 0/0 se
NOTICE: Index onek_unique2: Pages 19; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
NOTICE: Index onek_unique1: Pages 17; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
VACUUM
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-VACUUM-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-VACUUM-4">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <COMMAND>VACUUM</COMMAND> statement in SQL92.
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-VACUUM-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT2 ID="R2-SQL-VACUUM-4">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <COMMAND>VACUUM</COMMAND> statement in SQL92.
</para>
</refsect2>
</refsect1>
</REFENTRY>

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

@@ -12,6 +12,7 @@
<REFPURPOSE>
Clean and analyze a <productname>Postgres</productname> database
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
@@ -23,218 +24,262 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
[ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-VACUUMDB-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>vacuumdb</application> accepts the following command line arguments:
<REFSECT2 ID="R2-APP-VACUUMDB-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>vacuumdb</application> accepts the following command line arguments:
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be cleaned or analyzed.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--analyze
</term>
<term>
-z
</term>
<listitem>
<para>
Calculate statistics on the database for use by the optimizer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--verbose
</term>
<term>
-v
</term>
<listitem>
<para>
Print detailed information during processing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
</term>
<term>
-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
</term>
<listitem>
<para>
Clean or analyze <replaceable class="parameter">table</replaceable> only.
Column names may be specified only in conjunction with
the <option>--analyze</option> option.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<application>vacuumdb</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be cleaned or analyzed.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
</para>
</refsect2>
<varlistentry>
<term>
--analyze
</term>
<term>
-z
</term>
<listitem>
<para>
Calculate statistics on the database for use by the optimizer.
<REFSECT2 ID="R2-APP-VACUUMDB-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>vacuumdb</application> executes a <command>VACUUM</command> command
on the specified database, so has not explicit external output.
<varlistentry>
<term>
--verbose
</term>
<term>
-v
</term>
<listitem>
<para>
Print detailed information during processing.
<variablelist>
<varlistentry>
<term>
ERROR: Can't vacuum columns, only tables. You can 'vacuum analyze' columns.
vacuumdb: database vacuum failed on <replaceable class="parameter">dbname</replaceable>.
</term>
<listitem>
<para>
The non-analyze mode requires cleaning full tables or databases.
Individual columns may be specified only when analyzing a specific table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
</term>
<term>
-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
</term>
<listitem>
<para>
Clean or analyze <replaceable class="parameter">table</replaceable> only.
Column names may be specified only in conjunction with
the <option>--analyze</option> option.
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
</term>
<listitem>
<para>
<application>vacuumdb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
</term>
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<application>vacuumdb</application> also accepts
the following command line arguments for connection parameters:
<note>
<para>
<application>vacuumdb</application> internally executes a
<command>VACUUM</command> <acronym>SQL</acronym> statement.
If you have problems running <application>vacuumdb</application>,
make sure you are able to run <command>VACUUM</command> on the database using, for
example, <application>psql</application>.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-VACUUMDB-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>vacuumdb</application> is a utility for cleaning a
<productname>Postgres</productname> database.
<application>vacuumdb</application> will also generate internal statistics
used by the <productname>Postgres</productname> query optimizer.
</para>
</refsect1>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</variablelist>
<REFSECT2 ID="R2-APP-VACUUMDB-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>vacuumdb</application> executes a <command>VACUUM</command> command
on the specified database, so has not explicit external output.
<variablelist>
<varlistentry>
<term>
ERROR: Can't vacuum columns, only tables. You can 'vacuum analyze' columns.
vacuumdb: database vacuum failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The non-analyze mode requires cleaning full tables or databases.
Individual columns may be specified only when analyzing a specific table.
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>vacuumdb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</variablelist>
<note>
<para>
<application>vacuumdb</application> internally executes a
<command>VACUUM</command> <acronym>SQL</acronym> statement.
If you have problems running <application>vacuumdb</application>,
make sure you are able to run <command>VACUUM</command> on the database using, for
example, <application>psql</application>.
</note>
<REFSECT1 ID="R1-APP-VACUUMDB-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>vacuumdb</application> is a utility for cleaning a
<productname>Postgres</productname> database.
<application>vacuumdb</application> will also generate internal statistics
used by the <productname>Postgres</productname> query optimizer.
<REFSECT1 ID="R1-APP-VACUUMDB-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<para>
See <xref linkend="vacuum" endterm="vacuum"> for more details.
<REFSECT1 ID="R1-APP-VACUUMDB-3">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To clean a database of the same name as the user:
<programlisting>
% vacuumdb
</programlisting>
<para>
To analyze a database named <literal>bigdb</literal> for the optimizer:
<programlisting>
% vacuumdb --analyze bigdb
</programlisting>
<para>
To analyze a single column <literal>bar</literal> in table <literal>foo</literal>
in a database named <literal>xyzzy</literal> for the optimizer:
<programlisting>
% vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy
</programlisting>
<REFSECT1 ID="R1-APP-VACUUMDB-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<para>
See <xref linkend="vacuum" endterm="vacuum"> for more details.
</para>
</refsect1>
<REFSECT1 ID="R1-APP-VACUUMDB-3">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To clean a database of the same name as the user:
<programlisting>
% vacuumdb
</programlisting>
</para>
<para>
To analyze a database named <literal>bigdb</literal> for the optimizer:
<programlisting>
% vacuumdb --analyze bigdb
</programlisting>
</para>
<para>
To analyze a single column <literal>bar</literal> in table <literal>foo</literal>
in a database named <literal>xyzzy</literal> for the optimizer:
<programlisting>
% vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy
</programlisting>
</para>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file