diff options
Diffstat (limited to 'doc/src/sgml/ref')
64 files changed, 8155 insertions, 6823 deletions
diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index 586b471ff35..d849c7ccff0 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -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> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index c2fb66e6a9a..c08245923be 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -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> diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml index 95a72ce2e46..52372d8ecfa 100644 --- a/doc/src/sgml/ref/alter_user.sgml +++ b/doc/src/sgml/ref/alter_user.sgml @@ -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> diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml index ab8a0fea2df..cd9842a87de 100644 --- a/doc/src/sgml/ref/begin.sgml +++ b/doc/src/sgml/ref/begin.sgml @@ -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> diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml index fb9a9598847..58e4694e730 100644 --- a/doc/src/sgml/ref/close.sgml +++ b/doc/src/sgml/ref/close.sgml @@ -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> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 050fee754eb..c49354478b6 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -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> diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index 689220993a7..55c6212dd5c 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -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> diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 77e652849ee..7fd7fb92d17 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index 273d6087a92..e225db11efe 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -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 diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 77a1a8d2e02..537db5f2ffa 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index e639845a7c5..f5a27adb308 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index b5523611566..1629a600547 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -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 diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 7554f7dcae2..4a27a9fd30a 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -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"> diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index 5cb21cda5cc..02961e38a1c 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -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> - + - * / < > = ~ ! @ # % ^ & | ` ? $ : -</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> + + - * / < > = ~ ! @ # % ^ & | ` ? $ : + </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 "<>" 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, <<<, - would have a commutator - operator, area-greater-than, >>>. - Hence, the query optimizer could freely convert: + For example, the operator area-less-than, <<<, + would have a commutator + operator, area-greater-than, >>>. + Hence, the query optimizer could freely convert: <programlisting> -"0,0,1,1"::box >>> MYBOXES.description + "0,0,1,1"::box >>> MYBOXES.description </programlisting> to <programlisting> -MYBOXES.description <<< "0,0,1,1"::box</programlisting> + MYBOXES.description <<< "0,0,1,1"::box</programlisting> </para> <para> This allows the execution code to always use the latter @@ -233,21 +236,21 @@ MYBOXES.description <<< "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 <<< MYBOXES2.description. + MYBOXES.description <<< 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 <<< MYBOXES2.description. sort both relations using the operator, <<<. On the other hand, merge-sort is not usable with the clause: <programlisting> -MYBOXES.description <<< MYBOXES2.description + MYBOXES.description <<< 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 <<< MYBOXES2.description the query optimizer can estimate result sizes. If a clause of the form: <programlisting> -MYBOXES.description <<< "0,0,1,1"::box + MYBOXES.description <<< "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 <<< "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"> diff --git a/doc/src/sgml/ref/create_rule.sgml b/doc/src/sgml/ref/create_rule.sgml index 132eddf1513..05845f0752c 100644 --- a/doc/src/sgml/ref/create_rule.sgml +++ b/doc/src/sgml/ref/create_rule.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index e8fb57f3b4f..f6d6ae0b8d4 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -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"> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index b0525ff6ed3..998c370a3b8 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -12,7 +12,7 @@ <REFPURPOSE> Creates a new table </REFPURPOSE> - + </refnamediv> <REFSYNOPSISDIV> <REFSYNOPSISDIVINFO> <DATE>1998-09-11</DATE> @@ -20,8 +20,7 @@ <SYNOPSIS> CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE> - [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>] - [, NOT NULL ] [ ,UNIQUE ] + [ NULL | NOT NULL ] [ UNIQUE ] [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> ] [<REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ] [, ... ] [, PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] @@ -126,33 +125,32 @@ requires the <REPLACEABLE CLASS="PARAMETER">column_constraint_clause</REPLACEABL </LISTITEM> </VARLISTENTRY> - <VARLISTENTRY> - <TERM> - INHERITS <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE> - </TERM> - <LISTITEM> - <PARA> - The optional INHERITS clause specifies a collection of table - names from which this table automatically inherits all fields. - If any inherited field name appears more than once, -<productname>Postgres</productname> - reports an error. - <productname>Postgres</productname> automatically allows the created - table to inherit functions on tables above it in the inheritance - hierarchy. -<note> -<title>Aside</title> -<para> - Inheritance of functions is done according - to the conventions of the Common Lisp Object System (CLOS). -</note> - </PARA> - </LISTITEM> - </VARLISTENTRY> - - </VARIABLELIST> - - + <VARLISTENTRY> + <TERM> + INHERITS <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE> + </TERM> + <LISTITEM> + <PARA> + The optional INHERITS clause specifies a collection of table + names from which this table automatically inherits all fields. + If any inherited field name appears more than once, + <productname>Postgres</productname> + reports an error. + <productname>Postgres</productname> automatically allows the created + table to inherit functions on tables above it in the inheritance + hierarchy. + <note> + <title>Aside</title> + <para> + Inheritance of functions is done according + to the conventions of the Common Lisp Object System (CLOS). + </para> + </note> + </PARA> + </LISTITEM> + </VARLISTENTRY> + </VARIABLELIST> + </para> </REFSECT2> <REFSECT2 ID="R2-SQL-CREATETABLE-2"> @@ -201,8 +199,11 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already <PARA> if data type of default value doesn't match the column definition's data type. - - </VARIABLELIST> + </para> + </listitem> + </varlistentry> + </VARIABLELIST> + </para> </REFSECT2> </REFSYNOPSISDIV> @@ -217,7 +218,7 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already <command>CREATE TABLE</command> will enter a new table into the current data base. The table will be "owned" by the user issuing the command. - + </para> <PARA> The new table is created as a heap with no initial data. A table can have no more than 1600 columns (realistically, @@ -226,9 +227,9 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already lower at some sites. A table cannot have the same name as a system catalog table. </PARA> - + </refsect1> - <REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1"> + <REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1"> <REFSECT1INFO> <DATE>1998-09-11</DATE> </REFSECT1INFO> @@ -239,7 +240,7 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already <SYNOPSIS> DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> </SYNOPSIS> - + </para> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-1"> <REFSECT2INFO> <DATE>1998-09-11</DATE> @@ -270,23 +271,27 @@ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> <listitem> <simpara> a niladic function - </simpara> - </listitem> - </itemizedlist> - </para> + </simpara> </listitem> - </VARLISTENTRY> - - </variablelist> + </itemizedlist> + </para> + </listitem> + </VARLISTENTRY> + </variablelist> + </para> + </refsect2> + <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-2"> <REFSECT2INFO> <DATE>1998-09-11</DATE> </REFSECT2INFO> <TITLE> - Outputs - </TITLE> - <PARA> - + Outputs + </TITLE> + <para> + </para> + </refsect2> + <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-3"> <REFSECT2INFO> <DATE>1998-09-11</DATE> @@ -365,6 +370,7 @@ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> </listitem> </varlistentry> </variablelist> + </para> <para> In the current release (v6.4), <productname>Postgres</productname> @@ -386,7 +392,8 @@ DEFAULT CURRENT_TIMESTAMP </quote>. This forces <productname>Postgres</productname> to consider the constant a string type and then to convert the value to <type>timestamp</type> at runtime. - + </para> + </refsect2> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-4"> <REFSECT2INFO> <DATE>1998-09-11</DATE> @@ -406,7 +413,7 @@ CREATE TABLE video_sales ( total CASH DEFAULT '$0.0' ); </ProgramListing> - + </para> <PARA> To assign an existing sequence as the default for the column <literal>did</literal>, @@ -418,7 +425,8 @@ CREATE TABLE distributors ( name VARCHAR(40) DEFAULT 'luso films' ); </ProgramListing> - + </para> + </refsect2> </REFSECT1> <REFSECT1 ID="R1-SQL-COLUMNCONSTRAINT-1"> @@ -430,8 +438,9 @@ CREATE TABLE distributors ( </TITLE> <para> <SYNOPSIS> -[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] { NOT NULL | UNIQUE | PRIMARY KEY | CHECK <replaceable class="parameter">constraint</replaceable> } [, ...] +[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] { [ NULL | NOT NULL ] | UNIQUE | PRIMARY KEY | CHECK <replaceable class="parameter">constraint</replaceable> } [, ...] </SYNOPSIS> + </para> <REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-1"> <REFSECT2INFO> @@ -459,6 +468,17 @@ which should ensure uniqueness for <VARLISTENTRY> <TERM> + NULL + </TERM> + <LISTITEM> + <PARA> +The column is allowed to contain NULL values. This is the default. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> NOT NULL </TERM> <LISTITEM> @@ -507,6 +527,8 @@ as a unique identifier for rows. </LISTITEM> </VARLISTENTRY> </VARIABLELIST> + </para> + </refsect2> <REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-2"> <REFSECT2INFO> @@ -544,6 +566,7 @@ as a unique identifier for rows. accepts the REFERENCES syntax but ignores the clause. </para> </note> + </refsect2> <REFSECT2 ID="R2-SQL-NOTNULL-1"> <REFSECT2INFO> @@ -564,69 +587,76 @@ accepts the REFERENCES syntax but ignores the clause. as a table constraint. </PARA> - <REFSECT3 ID="R3-SQL-NOTNULL-1"> - <REFSECT3INFO> - <DATE>1998-09-11</DATE> - </REFSECT3INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - </PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> -<replaceable>status</replaceable> - </TERM> - <LISTITEM> - <PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <ReturnValue>ERROR: ExecAppend: Fail to add null value in not - null attribute "<replaceable class="parameter">column</replaceable>".</ReturnValue> - </TERM> - <LISTITEM> - <PARA> - This error occurs at runtime if one tries to insert a null value - into a column which has a NOT NULL constraint. - </PARA> - </LISTITEM> - </VARLISTENTRY> - </variablelist> - </LISTITEM> - </VARLISTENTRY> - </VARIABLELIST> - - <REFSECT3 ID="R3-SQL-NOTNULL-2"> - <REFSECT3INFO> - <DATE>1998-09-11</DATE> - </REFSECT3INFO> - <TITLE> -Description -</title> -<para> - - <REFSECT3 ID="R3-SQL-NOTNULL-3"> - <REFSECT3INFO> - <DATE>1998-09-11</DATE> - </REFSECT3INFO> - <TITLE> -Usage -</title> - - <PARA> - Define two NOT NULL column constraints on the table - <classname>distributors</classname>, -one of which being a named constraint: - </PARA> - <ProgramListing> -CREATE TABLE distributors ( - did DECIMAL(3) CONSTRAINT no_null NOT NULL, - name VARCHAR(40) NOT NULL -); - </ProgramListing> + <REFSECT3 ID="R3-SQL-NOTNULL-1"> + <REFSECT3INFO> + <DATE>1998-09-11</DATE> + </REFSECT3INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + </PARA> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <replaceable>status</replaceable> + </TERM> + <LISTITEM> + <PARA> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <ReturnValue>ERROR: ExecAppend: Fail to add null value in not + null attribute "<replaceable class="parameter">column</replaceable>".</ReturnValue> + </TERM> + <LISTITEM> + <PARA> + This error occurs at runtime if one tries to insert a null value + into a column which has a NOT NULL constraint. + </PARA> + </LISTITEM> + </VARLISTENTRY> + </variablelist> + </para> + </LISTITEM> + </VARLISTENTRY> + </VARIABLELIST> + </refsect3> + <REFSECT3 ID="R3-SQL-NOTNULL-2"> + <REFSECT3INFO> + <DATE>1998-09-11</DATE> + </REFSECT3INFO> + <TITLE> + Description + </title> + <para> + </para> + </refsect3> + + <REFSECT3 ID="R3-SQL-NOTNULL-3"> + <REFSECT3INFO> + <DATE>1998-09-11</DATE> + </REFSECT3INFO> + <TITLE> + Usage + </title> + + <PARA> + Define two NOT NULL column constraints on the table + <classname>distributors</classname>, + one of which being a named constraint: + + <ProgramListing> + CREATE TABLE distributors ( + did DECIMAL(3) CONSTRAINT no_null NOT NULL, + name VARCHAR(40) NOT NULL + ); + </ProgramListing> + </para> + </refsect3> + </refsect2> + <REFSECT2 ID="R2-SQL-UNIQUECLAUSE-1"> <REFSECT2INFO> <DATE>1998-09-11</DATE> @@ -640,21 +670,22 @@ CREATE TABLE distributors ( <refsect3> <title>Inputs</title> -<para> - <variablelist> - <varlistentry> - <term> - CONSTRAINT <replaceable class="parameter">name</replaceable> - </term> - <listitem> - <para> - An arbitrary label given to a constraint. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + <variablelist> + <varlistentry> + <term> + CONSTRAINT <replaceable class="parameter">name</replaceable> + </term> + <listitem> + <para> + An arbitrary label given to a constraint. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> </refsect3> - + <refsect3> <title>Outputs</title> <PARA> @@ -674,15 +705,17 @@ CREATE TABLE distributors ( <para> This error occurs at runtime if one tries to insert a duplicate value into a column. - </para> - </listitem> - </varlistentry> - </variablelist></para> - </listitem> - </varlistentry> - </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> </refsect3> - + <refsect3> <title> Description @@ -713,6 +746,7 @@ for more details.). data integrity. See CREATE INDEX for more information. </Para> </Note> + </refsect3> <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-3"> <TITLE> @@ -737,6 +771,9 @@ CREATE TABLE distributors ( UNIQUE(name) ); </ProgramListing> + </para> + </refsect3> + </refsect2> <REFSECT2 ID="R2-SQL-CHECK-1"> <REFSECT2INFO> @@ -759,70 +796,73 @@ The CHECK Constraint <LISTITEM> <PARA> An arbitrary name given to a constraint. - </PARA> - </LISTITEM> - </VARLISTENTRY> - <VARLISTENTRY> - <TERM> - <replaceable>condition</replaceable> - </TERM> - <LISTITEM> - <PARA> - Any valid conditional expression evaluating to a boolean result. - </PARA> - </LISTITEM> - </VARLISTENTRY> - </variablelist> - </REFSECT3> - - <REFSECT3 ID="R3-SQL-CHECK-2"> - <REFSECT3INFO> - <DATE>1998-09-11</DATE> - </REFSECT3INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - <VARIABLELIST> + </PARA> + </LISTITEM> + </VARLISTENTRY> <VARLISTENTRY> <TERM> -<replaceable>status</replaceable> + <replaceable>condition</replaceable> </TERM> <LISTITEM> <PARA> - + Any valid conditional expression evaluating to a boolean result. + </PARA> + </LISTITEM> + </VARLISTENTRY> + </variablelist> + </para> + </REFSECT3> + + <REFSECT3 ID="R3-SQL-CHECK-2"> + <REFSECT3INFO> + <DATE>1998-09-11</DATE> + </REFSECT3INFO> + <TITLE> + Outputs + </TITLE> + <PARA> <VARIABLELIST> <VARLISTENTRY> <TERM> - <ReturnValue> - ERROR: ExecAppend: rejected due to CHECK constraint - "<replaceable class="parameter">table_column</replaceable>". - </ReturnValue> + <replaceable>status</replaceable> </TERM> <LISTITEM> <PARA> - This error occurs at runtime if one tries to insert an illegal - value into a column subject to a CHECK constraint. - </PARA> - </LISTITEM> - </VARLISTENTRY> - </variablelist> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <ReturnValue> + ERROR: ExecAppend: rejected due to CHECK constraint + "<replaceable class="parameter">table_column</replaceable>". + </ReturnValue> + </TERM> + <LISTITEM> + <PARA> + This error occurs at runtime if one tries to insert an illegal + value into a column subject to a CHECK constraint. + </PARA> + </LISTITEM> + </VARLISTENTRY> + </variablelist> + </para> </LISTITEM> </VARLISTENTRY> </variablelist> + </para> </REFSECT3> - + <refsect3> <title>Description</title> <para> The CHECK constraint specifies a restriction on allowed values -within a column. + within a column. The CHECK constraint is also allowed as a table constraint. </PARA> <PARA> The SQL92 CHECK column constraints can only be defined on, and refer to, one column of the table. <productname>Postgres</productname> - does not have + does not have this restriction. </PARA> </refsect3> @@ -868,7 +908,7 @@ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> <para> This occurs at run-time if one tries to insert a duplicate value into a column subject to a PRIMARY KEY constraint. - </PARA> + </PARA> </listitem> </varlistentry> </variablelist> @@ -909,83 +949,89 @@ However, <productname>Postgres</productname> does not specifically disallow this. </PARA> </refsect3> - - <REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1"> - <REFSECT1INFO> - <DATE>1998-09-11</DATE> - </REFSECT1INFO> - <TITLE> + </refsect2> + </refsect1> + + <REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1"> + <REFSECT1INFO> + <DATE>1998-09-11</DATE> + </REFSECT1INFO> + <TITLE> Table CONSTRAINT Clause - </TITLE> - <para> + </TITLE> + <para> <SYNOPSIS> -[ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] ) -[ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> ) + [ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] ) + [ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> ) </SYNOPSIS> - <PARA> - + </para> <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-1"> <REFSECT2INFO> <DATE>1998-09-11</DATE> </REFSECT2INFO> -<title> -Inputs -</title> - -<para> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - CONSTRAINT <replaceable class="parameter">name</replaceable> - </TERM> - <LISTITEM> - <PARA> - An arbitrary name given to an integrity constraint. - </PARA> - </LISTITEM> - </VARLISTENTRY> - <VARLISTENTRY> - <TERM> - <replaceable class="parameter">column</replaceable> [, ...] - </TERM> - <LISTITEM> - <PARA> - The column name(s) for which to define a unique index -and, for PRIMARY KEY, a NOT NULL constraint. - </PARA> - </LISTITEM> - <VARLISTENTRY> - <TERM> - CHECK ( <replaceable class="parameter">constraint</replaceable> ) - </TERM> - <LISTITEM> - <PARA> - A boolean expression to be evaluated as the constraint. - </PARA> - </LISTITEM> - </VARLISTENTRY> - </VARIABLELIST> - + <title> + Inputs + </title> + + <para> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + CONSTRAINT <replaceable class="parameter">name</replaceable> + </TERM> + <LISTITEM> + <PARA> + An arbitrary name given to an integrity constraint. + </PARA> + </LISTITEM> + </VARLISTENTRY> + <VARLISTENTRY> + <TERM> + <replaceable class="parameter">column</replaceable> [, ...] + </TERM> + <LISTITEM> + <PARA> + The column name(s) for which to define a unique index + and, for PRIMARY KEY, a NOT NULL constraint. + </PARA> + </LISTITEM> + </varlistentry> + <VARLISTENTRY> + <TERM> + CHECK ( <replaceable class="parameter">constraint</replaceable> ) + </TERM> + <LISTITEM> + <PARA> + A boolean expression to be evaluated as the constraint. + </PARA> + </LISTITEM> + </VARLISTENTRY> + </VARIABLELIST> + </para> + </refsect2> + <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-2"> <REFSECT2INFO> <DATE>1998-09-11</DATE> </REFSECT2INFO> -<title> -Outputs -</title> - -<para> -The possible outputs for the table constraint clause are the same -as for the corresponding portions of the column constraint clause. - + <title> + Outputs + </title> + + <para> + The possible outputs for the table constraint clause are the same + as for the corresponding portions of the column constraint clause. + </para> + </refsect2> + <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-3"> <REFSECT2INFO> <DATE>1998-09-11</DATE> </REFSECT2INFO> -<title> -Description -</title> - + <title> + Description + </title> + <para> A table constraint is an integrity constraint defined on one or more columns of a base table. The four variations of "Table @@ -1000,14 +1046,15 @@ Description <note> <para> <productname>Postgres</productname> does not yet -(as of version 6.4) support FOREIGN KEY -integrity constraints. The parser understands the FOREIGN KEY syntax, -but only prints a notice and otherwise ignores the clause. + (as of version 6.4) support FOREIGN KEY + integrity constraints. The parser understands the FOREIGN KEY syntax, + but only prints a notice and otherwise ignores the clause. Foreign keys may be partially emulated by triggers (See the CREATE TRIGGER statement). </para> </note> - + </refsect2> + <REFSECT2 ID="R2-SQL-UNIQUECLAUSE-4"> <REFSECT2INFO> <DATE>1998-09-11</DATE> @@ -1016,15 +1063,16 @@ but only prints a notice and otherwise ignores the clause. UNIQUE Constraint </TITLE> <para> - <synopsis> -[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] ) - </SYNOPSIS> + <synopsis> + [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] ) + </SYNOPSIS> + </para> <refsect3> <title>Inputs</title> <variablelist> <varlistentry> <term> - CONSTRAINT <replaceable class="parameter">name</replaceable> + CONSTRAINT <replaceable class="parameter">name</replaceable> </term> <listitem> <para> @@ -1044,64 +1092,69 @@ but only prints a notice and otherwise ignores the clause. </varlistentry> </variablelist> </refsect3> + <refsect3> <title>Outputs</title> <PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> -<replaceable>status</replaceable> - </TERM> - <LISTITEM> - <PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - ERROR: Cannot insert a duplicate key into a unique index. - </term> - <listitem> - <para> - This error occurs at runtime if one tries to insert a - duplicate value into a column. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <replaceable>status</replaceable> + </TERM> + <LISTITEM> + <PARA> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + ERROR: Cannot insert a duplicate key into a unique index. + </term> + <listitem> + <para> + This error occurs at runtime if one tries to insert a + duplicate value into a column. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> </refsect3> - + <refsect3> <title> -Description + Description </title> - + <PARA> The UNIQUE constraint specifies a rule that a group of one or more distinct columns of a table may contain only unique values. -The behavior of the UNIQUE table constraint is the same as that for column -constraints, with the additional capability to span multiple columns. + The behavior of the UNIQUE table constraint is the same as that for column + constraints, with the additional capability to span multiple columns. </para> <para> -See the section on the UNIQUE column constraint for more details. - - <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4"> - <TITLE> -Usage -</title> - - <PARA> - Define a UNIQUE table constraint for the table distributors: - <ProgramListing> -CREATE TABLE distributors ( - did DECIMAL(03), - name VARCHAR(40), - UNIQUE(name) -); - </ProgramListing> - + See the section on the UNIQUE column constraint for more details. + </para> + </refsect3> + <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4"> + <TITLE> + Usage + </title> + + <PARA> + Define a UNIQUE table constraint for the table distributors: + <ProgramListing> + CREATE TABLE distributors ( + did DECIMAL(03), + name VARCHAR(40), + UNIQUE(name) + ); + </ProgramListing> + </para> + </refsect3> </REFSECT2> <REFSECT2 ID="R2-SQL-PRIMARYKEY-4"> @@ -1111,18 +1164,18 @@ CREATE TABLE distributors ( <TITLE> PRIMARY KEY Constraint </TITLE> -<para> - <SYNOPSIS> - [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) - </SYNOPSIS> - + <para> + <SYNOPSIS> + [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) + </SYNOPSIS> + </para> <refsect3> <title>Inputs</title> <PARA> <VARIABLELIST> <VARLISTENTRY> <TERM> -CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue> + CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue> </TERM> <LISTITEM> <PARA> @@ -1132,7 +1185,7 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur </VARLISTENTRY> <VARLISTENTRY> <TERM> -<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] + <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] </TERM> <LISTITEM> <PARA> @@ -1143,32 +1196,33 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur </VARIABLELIST> </para> </refsect3> - + <refsect3> <title>Outputs</title> <variablelist> <varlistentry> <term> -<replaceable>status</replaceable> -</term> -<listitem> -<para> - <variablelist> - <varlistentry> - <term>ERROR: Cannot insert a duplicate key into a unique index.</term> + <replaceable>status</replaceable> + </term> <listitem> <para> - This occurs at run-time if one tries to insert a duplicate value into - a column subject to a PRIMARY KEY constraint. - </PARA> - </listitem> - </varlistentry> - </variablelist> + <variablelist> + <varlistentry> + <term>ERROR: Cannot insert a duplicate key into a unique index.</term> + <listitem> + <para> + This occurs at run-time if one tries to insert a duplicate value into + a column subject to a PRIMARY KEY constraint. + </PARA> + </listitem> + </varlistentry> + </variablelist> + </para> </listitem> </varlistentry> </variablelist> </refsect3> - + <refsect3> <title>Description</title> <PARA> @@ -1177,17 +1231,18 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur (non duplicate), non-null values. The column definitions of the specified columns do not have to include a NOT NULL constraint to be included in a PRIMARY KEY constraint. - -The PRIMARY KEY table constraint is similar to that for column constraints, -with the additional capability of encompassing multiple columns. + + The PRIMARY KEY table constraint is similar to that for column constraints, + with the additional capability of encompassing multiple columns. </PARA> <PARA> -Refer to the section on the PRIMARY KEY column constraint for more -information. + Refer to the section on the PRIMARY KEY column constraint for more + information. + </para> </REFSECT3> </REFSECT2> - + </refsect1> <REFSECT1 ID="R1-SQL-CREATETABLE-2"> @@ -1306,7 +1361,7 @@ information. </TITLE> <PARA> CREATE TABLE/INHERITS is a <productname>Postgres</productname> - language extension. + language extension. </PARA> </refsect2> @@ -1316,7 +1371,6 @@ information. <TITLE> Compatibility </TITLE> - <PARA> <REFSECT2 ID="R2-SQL-CREATETABLE-4"> <REFSECT2INFO> @@ -1357,15 +1411,17 @@ information. ) ON COMMIT DELETE ROWS </programlisting> <para> -Temporary tables are not currently available - in <productname>Postgres</productname>. -<tip> - <para> - In the current release of <productname>Postgres</productname> - (v6.4), to create a temporary - table you must create and drop the table by explicit commands. -</tip> - + Temporary tables are not currently available + in <productname>Postgres</productname>. + <tip> + <para> + In the current release of <productname>Postgres</productname> + (v6.4), to create a temporary + table you must create and drop the table by explicit commands. + </para> + </tip> + </para> + <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-1"> <REFSECT3INFO> <DATE>1998-09-11</DATE> @@ -1375,6 +1431,7 @@ Temporary tables are not currently available </TITLE> <PARA> SQL92 specifies some additional capabilities for UNIQUE: + </para> <para> Table Constraint definition </PARA> @@ -1395,6 +1452,23 @@ Temporary tables are not currently available </synopsis> </refsect3> + <REFSECT3 ID="R3-SQL-NULL-1"> + <REFSECT3INFO> + <DATE>1998-12-24</DATE> + </REFSECT3INFO> + <TITLE> + NULL clause + </TITLE> + <PARA> + The NULL "constraint" (actually a non-constraint) + is a <productname>Postgres</productname> extension to SQL92 + is included for symmetry with the NOT NULL clause. Since it is the default + for any column, its presence is simply noise. + <synopsis> + [ CONSTRAINT name ] NULL + </synopsis> + </REFSECT3> + <REFSECT3 ID="R3-SQL-NOTNULL-4"> <REFSECT3INFO> <DATE>1998-09-11</DATE> @@ -1407,9 +1481,9 @@ Temporary tables are not currently available SQL92 specifies some additional capabilities for NOT NULL: </PARA> <synopsis> - [ CONSTRAINT name ] NOT NULL - [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] - [ [ NOT ] DEFERRABLE ] + [ CONSTRAINT name ] NOT NULL + [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] + [ [ NOT ] DEFERRABLE ] </synopsis> </REFSECT3> @@ -1450,13 +1524,13 @@ the column. Not our problem... <PARA> SQL92 specifies some additional capabilities for constraints, and also defines assertions and domain constraints. - <note> - <para> - <productname>Postgres</productname> does not yet support -either domains or assertions. + <note> + <para> + <productname>Postgres</productname> does not yet support + either domains or assertions. + </para> + </note> </para> - </note> - <PARA> An assertion is a special type of integrity constraint and share the same namespace as other constraints. @@ -1672,7 +1746,7 @@ affect a column or a table. <REFPURPOSE> Creates a new table </REFPURPOSE> - + </refnamediv> <REFSYNOPSISDIV> <REFSYNOPSISDIVINFO> <DATE>1998-09-22</DATE> @@ -1722,10 +1796,12 @@ a comma-delimited list of column names. <PARA> A valid query statement. Refer to SELECT for a description of the allowed syntax. - </PARA> - </LISTITEM> - </VARLISTENTRY> - </VARIABLELIST> + </PARA> + </LISTITEM> + </VARLISTENTRY> + </VARIABLELIST> + </para> + </refsect2> <REFSECT2 ID="R2-SQL-CREATETABLEAS-2"> <REFSECT2INFO> @@ -1735,22 +1811,25 @@ allowed syntax. Outputs </TITLE> <PARA> - Refer to CREATE TABLE and SELECT for a summary of possible output -messages. - - <REFSECT1 ID="R1-SQL-CREATETABLEAS-1"> - <REFSECT1INFO> - <DATE>1998-09-22</DATE> - </REFSECT1INFO> - <TITLE> - Description - </TITLE> + Refer to CREATE TABLE and SELECT for a summary of possible output + messages. + </para> + </refsect2> + </refsynopsisdiv> + + <REFSECT1 ID="R1-SQL-CREATETABLEAS-1"> + <REFSECT1INFO> + <DATE>1998-09-22</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> <PARA> CREATE TABLE AS enables a table to be created from the contents of an existing table. It has functionality equivalent to SELECT TABLE INTO, but with perhaps a more obvious syntax. - -</refsect1> + </para> + </refsect1> </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index a871a59cce8..c9e241b6f9b 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -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 diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 1fd0066c52f..9455d8fd455 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index 2f041e83d94..3ab3e2958d5 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -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> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 575e7df1531..9f870794421 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -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 diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 9f0ce35fd25..54e27a5e673 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -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> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index ad51ae5c666..09b3209a135 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -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> diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 954b3b4af03..a65ef65495a 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -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 diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 4a77e02210a..341c97370fb 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -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 <> 'Musical'; +DETETE FROM films WHERE kind <> '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> diff --git a/doc/src/sgml/ref/destroydb.sgml b/doc/src/sgml/ref/destroydb.sgml index 547cfee8809..a31265e76e2 100644 --- a/doc/src/sgml/ref/destroydb.sgml +++ b/doc/src/sgml/ref/destroydb.sgml @@ -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> - -<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> --i -</term> -<listitem> -<para> -Run in interactive mode. -Prompts for confirmation before destroying a database. - -<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. + <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> -<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. + <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> -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> + 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> -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> + <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> -<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> diff --git a/doc/src/sgml/ref/destroyuser.sgml b/doc/src/sgml/ref/destroyuser.sgml index 03bce6e14e7..44440029d6f 100644 --- a/doc/src/sgml/ref/destroyuser.sgml +++ b/doc/src/sgml/ref/destroyuser.sgml @@ -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> - -<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> -<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. - -</variablelist> - -<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. - + <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> + 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> + 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> + 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> + + <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> + + </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> diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index 068d69e4924..2cd03ae2ff2 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index d9f42906a25..a2465550d89 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 9a63ac71e10..d2b4eb87c6e 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -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 diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 8e91465a7b9..3c4f7673e45 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 4eb3545736f..1fc9f298934 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index df488aa5f59..619f8887e73 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_rule.sgml b/doc/src/sgml/ref/drop_rule.sgml index f53bd77994e..41f0b03970c 100644 --- a/doc/src/sgml/ref/drop_rule.sgml +++ b/doc/src/sgml/ref/drop_rule.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index ace32b0850c..eff237f7673 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index 80527cf01a3..11dfaf8cfb0 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml index d2729bda824..f4b8d733e5d 100644 --- a/doc/src/sgml/ref/drop_trigger.sgml +++ b/doc/src/sgml/ref/drop_trigger.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index baad378c0db..ca9793b70fd 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml index 3de3deaa193..fa29c9f5e89 100644 --- a/doc/src/sgml/ref/drop_user.sgml +++ b/doc/src/sgml/ref/drop_user.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index e49701815ed..98449d0eefd 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -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> diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 6ae69d7abc8..5f4a8063f43 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -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> <!-- diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index 10d5df0c6d7..839732c669d 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -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> <!-- diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index aefb6251b89..5dd043e7959 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -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> - -<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: - -<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 + <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> + + <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-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> + + <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> + + <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> - -<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> - -</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> - -</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> + </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. + </para> + </tip> + </para> + </REFSECT2> + </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> + </para> + </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: + </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> <!-- diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index ccfcd4bb81c..19ee8d88dc8 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -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. - -<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> + <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> -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> diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml index 7302118e866..687f5e81efe 100644 --- a/doc/src/sgml/ref/initlocation.sgml +++ b/doc/src/sgml/ref/initlocation.sgml @@ -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> - -<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>. - -<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> - + <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> + + <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> + + <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> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 2d90cc65fe0..b5e2c0241ea 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -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> <!-- diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index c9ef49ab980..1a110074f8b 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -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> diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index 66fafdc887a..fc2f04ed516 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -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> - -<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. - -</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>. - + <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> + + <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> + + <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> diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index ca973654104..0d2c5047523 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -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> - -<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. - -<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-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 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> + + <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> + + <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> diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 7a17639827f..50dd279062d 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -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. - -<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> - 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-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> -<REFSECT1 ID="R1-SQL-MOVE-3"> -<TITLE> -Compatibility -</TITLE> -<PARA> -</PARA> + <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-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> diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index 73eb7754268..f603258ebef 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -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> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Notify condition to be signaled. - -</VARIABLELIST> - -</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>. - + <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. + </para> + </listitem> + </varlistentry> + </VARIABLELIST> + </para> + </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. + </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> + + <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> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 5cda9ae3631..1f55f58754e 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -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: - -<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. - -<varlistentry> -<term> --a -</term> -<listitem> -<para> -Dump out only the data, no schema (definitions). - -<varlistentry> -<term> --d -</term> -<listitem> -<para> -Dump data as proper insert strings. - -<varlistentry> -<term> --D -</term> -<listitem> -<para> -Dump data as inserts with attribute names - -<varlistentry> -<term> --f <replaceable class="parameter">filename</replaceable> -</term> -<listitem> -<para> -Specifies the output file. Defaults to <filename>stdout</filename>. - -<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>. - -<varlistentry> -<term> --N -</term> -<listitem> -<para> -Include double quotes around identifiers. -This is the default. - -<varlistentry> -<term> --o -</term> -<listitem> -<para> -Dump object identifiers (<acronym>OID</acronym>s) for every table. - -<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> - + <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> + </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> + -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> + + <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>'? + </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> + + <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 + </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> + 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> + + <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> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 08932933427..3be7440720c 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -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: - -<variablelist> -<varlistentry> -<term> --a -</term> -<listitem> -<para> -Dump out only the data, no schema (definitions). - -<varlistentry> -<term> --d -</term> -<listitem> -<para> -Dump data as proper insert strings. - -<varlistentry> -<term> --D -</term> -<listitem> -<para> -Dump data as inserts with attribute names - -<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. - -<varlistentry> -<term> --o -</term> -<listitem> -<para> -Dump object identifiers (<acronym>OID</acronym>s) for every table. - -<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> - + <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> + + <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> + + <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> + 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_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> + + <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>. + </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> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 2a71416abed..a8fd9473c2f 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -12,6 +12,7 @@ <REFPURPOSE> <productname>Postgres</productname> interactive client </REFPURPOSE> + </refnamediv> <REFSYNOPSISDIV> <REFSYNOPSISDIVINFO> <DATE>1998-09-26</DATE> @@ -23,851 +24,1029 @@ psql -A [ -c <replaceable class="parameter">query</replaceable> ] [ -d <replacea [ -o <replaceable class="parameter">filename</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] -qsSt ] [ -T <replaceable class="parameter">table_options</replaceable> ] -ux [ <replaceable class="parameter">dbname</replaceable> ] </SYNOPSIS> -<REFSECT2 ID="R2-APP-PSQL-1"> -<REFSECT2INFO> -<DATE>1998-09-26</DATE> -</REFSECT2INFO> -<TITLE> -Inputs -</TITLE> -<PARA> -<application>psql</application> accepts many command-line arguments, -a rich set of meta-commands, and the full <acronym>SQL</acronym> language -supported by <productname>Postgres</productname>. The most common -command-line arguments are: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -The name of an existing database to access. -<replaceable class="parameter">dbname</replaceable> -defaults to the value of the -<envar>USER</envar> -environment variable or, if that's not set, to the Unix account name of the -current user. - -</PARA> -</LISTITEM> -</VARLISTENTRY> - -<VARLISTENTRY> -<TERM> --c <replaceable class="parameter">query</replaceable> -</TERM> -<LISTITEM> -<PARA> -A single query to run. <application>psql</application> will exit on completion. -</PARA> -</LISTITEM> -</VARLISTENTRY> - -</variablelist> - -<para> -The full set of command-line arguments and meta-commands are described in a subsequent -section. - -<para> -There are some environment variables which can be used in liu of -command line arguments. -Additionally, the <productname>Postgres</productname> frontend library used by -the <application>psql</application> application -looks for other optional environment variables to configure, for example, -the style of date/time representation and the local time zone. Refer -to the chapter on <filename>libpq</filename> in the -<citetitle>Programmer's Guide</citetitle> for more details. - -<para> -You may set any of the following environment variables to avoid -specifying command-line options: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<envar>PGHOST</envar> -</TERM> -<LISTITEM> -<PARA> -The <acronym>DNS</acronym> host name of the database server. -Setting <envar>PGHOST</envar> to a non-zero-length string causes -<acronym>TCP/IP</acronym> communication -to be used, rather than the default local Unix domain sockets. -</PARA> -</LISTITEM> -</VARLISTENTRY> - -<VARLISTENTRY> -<TERM> -<envar>PGPORT</envar> -</TERM> -<LISTITEM> -<PARA> -The port number on which a <productname>Postgres</productname> server is listening. -Defaults to <literal>5432</literal>. -</PARA> -</LISTITEM> -</VARLISTENTRY> - -<VARLISTENTRY> -<TERM> -<envar>PGTTY</envar> -</TERM> -<LISTITEM> -<PARA> -The target for display of messages from the client support library. -Not required. -</PARA> -</LISTITEM> -</VARLISTENTRY> - -<VARLISTENTRY> -<TERM> -<envar>PGOPTION</envar> -</TERM> -<LISTITEM> -<PARA> -If <envar>PGOPTION</envar> -is specified, then the options it contains are parsed -<emphasis>before</emphasis> -any command-line options. -</PARA> -</LISTITEM> -</VARLISTENTRY> - -<VARLISTENTRY> -<TERM> -<envar>PGREALM</envar> -</TERM> -<LISTITEM> -<PARA> -<envar>PGREALM</envar> -only applies if -<productname>Kerberos</productname> -authentication is in use. -If this environment variable is set, <productname>Postgres</productname> -will attempt authentication with servers for this realm and will use -separate ticket files to avoid conflicts with local ticket files. -See the <citetitle>PostgreSQL Administrator's Guide</citetitle> -for additional information on -<productname>Kerberos</productname>. - -</variablelist> - -<REFSECT2 ID="R2-APP-PSQL-2"> -<REFSECT2INFO> -<DATE>1998-09-26</DATE> -</REFSECT2INFO> -<TITLE> -Outputs -</TITLE> -<PARA> - -<application>psql</application> -returns 0 to the shell on successful completion of all queries, -1 for errors, 2 for abrupt disconnection from the backend. -The default TAB delimiter is used. -<application>psql</application> -will also return 1 if the connection to a database could not be made for -any reason. - -<REFSECT1 ID="R1-APP-PSQL-1"> -<REFSECT1INFO> -<DATE>1998-09-26</DATE> -</REFSECT1INFO> -<TITLE> -Description -</TITLE> -<PARA> -<application>psql</application> is a character-based front-end to -<productname>Postgres</productname>. -It enables you to -type in queries interactively, issue them to <productname>Postgres</productname>, -and see the query -results. - -<para> -<application>psql</application> -is a <productname>Postgres</productname> client application. Hence, a -<application>postmaster</application> process - must be running on the database server host before -<application>psql</application> -is executed. In addition, the correct parameters to identify -the database server, such as the -<application>postmaster</application> host name, - may need to be specified -as described below. - -<para> -When -<application>psql</application> -starts, it reads SQL commands from -<filename>/etc/psqlrc</filename> -and then from -<filename>$(<envar>HOME</envar>)/.psqlrc</filename> -This allows SQL commands like -<command>SET</command> -which can be used to set the date style to be run at the start of -every session. - -<REFSECT2 ID="R2-APP-PSQL-3"> -<REFSECT2INFO> -<DATE>1998-09-26</DATE> -</REFSECT2INFO> -<TITLE> -Connecting To A Database -</TITLE> -<para> -<application>psql</application> -attempts to make a connection to the database at the hostname and -port number specified on the command line. If the connection could not -be made for any reason (e.g. insufficient privileges, postmaster is not -running on the server, etc) -.IR <application>psql</application> -will return an error that says -<programlisting> -Connection to database failed. -</programlisting> -The reason for the connection failure is not provided. - -<REFSECT2 ID="R2-APP-PSQL-4"> -<REFSECT2INFO> -<DATE>1998-09-26</DATE> -</REFSECT2INFO> -<TITLE> -Entering Queries -</TITLE> -<para> -In normal operation, -<application>psql</application> provides a prompt with the name of the -database that <application>psql</application> is current connected to -followed by the string "=>". -For example, -<programlisting> -$ <userinput>psql testdb</userinput> -Welcome to the POSTGRESQL interactive sql monitor: - Please read the file COPYRIGHT for copyright terms of POSTGRESQL - - type \e? for help on slash commands - type \eq to quit - type \eg or terminate with semicolon to execute query - You are currently connected to the database: testdb - -testdb=> -</programlisting> - -<para> -At the prompt, the user may type in <acronym>SQL</acronym> queries. -Unless the -S option -is set, input lines are sent to the backend when a query-terminating -semicolon is reached. - -<para> -Whenever a query is executed, -<application>psql</application> also polls for asynchronous notification -events generated by <command>LISTEN</command> and <command>NOTIFY</command>. - -<para> -<application>psql</application> -can be used in a pipe sequence, and automatically detects when it -is not listening or talking to a real tty. - -<REFSECT1 ID="R1-APP-PSQL-2"> -<REFSECT1INFO> -<DATE>1998-09-26</DATE> -</REFSECT1INFO> -<TITLE> -Command-line Options -</TITLE> -<para> -<application>psql</application> -understands the following command-line options: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> --A -</TERM> -<LISTITEM> -<PARA> -Turn off fill justification when printing out table elements. - -<VARLISTENTRY> -<TERM> --c <replaceable class="parameter">query</replaceable> -</TERM> -<LISTITEM> -<PARA> -Specifies that -<application>psql</application> -is to execute one query string, -<replaceable class="parameter">query</replaceable>, -and then exit. This is useful for shell scripts, typically in -conjunction with the <option>-q</option> option in shell scripts. - -<VARLISTENTRY> -<TERM> --d <replaceable class="parameter">dbname</replaceable> -</TERM> -<LISTITEM> -<PARA> -Specifies the name of the database to connect to. This is equivalent to specifying -<replaceable class="parameter">dbname</replaceable> as the last field in the -command line. - -<VARLISTENTRY> -<TERM> --e -</TERM> -<LISTITEM> -<PARA> -Echo the query sent to the backend - -<VARLISTENTRY> -<TERM> --f <replaceable class="parameter">filename</replaceable> -</TERM> -<LISTITEM> -<PARA> -Use the file <replaceable class="parameter">filename</replaceable> -as the source of queries instead of reading queries interactively. -This file must be specified for and visible to the client frontend. - -<VARLISTENTRY> -<TERM> --F <replaceable class="parameter">separator</replaceable> -</TERM> -<LISTITEM> -<PARA> -Use <replaceable class="parameter">separator</replaceable> -as the field separator. -The default is an ASCII vertical bar ("|"). - -<VARLISTENTRY> -<TERM> --h <replaceable class="parameter">hostname</replaceable> -</TERM> -<LISTITEM> -<PARA> -Specifies the host name of the machine on which the -<application>postmaster</application> -is running. -Without this option, communication is performed using -local Unix domain sockets. - -<VARLISTENTRY> -<TERM> --H -</TERM> -<LISTITEM> -<PARA> -Turns on -<acronym>HTML 3.0</acronym> -tabular output. - -<VARLISTENTRY> -<TERM> --l -</TERM> -<LISTITEM> -<PARA> -Lists all available databases, then exit. Other non-connection options are ignored. - -<VARLISTENTRY> -<TERM> --n -</TERM> -<LISTITEM> -<PARA> -Do not use the readline library for input line editing and command history. - -<VARLISTENTRY> -<TERM> --o <replaceable class="parameter">filename</replaceable> -</TERM> -<LISTITEM> -<PARA> -Put all output into file <replaceable class="parameter">filename</replaceable>. -The path must be writable by the client. - -<VARLISTENTRY> -<TERM> --p <replaceable class="parameter">port</replaceable> -</TERM> -<LISTITEM> -<PARA> -Specifies the TCP/IP port or, by omission, the local Unix domain socket file -extension on which the -<application>postmaster</application> -is listening for connections. Defaults to the value of the -<envar>PGPORT</envar> -environment variable, if set, or to 5432. - -<VARLISTENTRY> -<TERM> --q -</TERM> -<LISTITEM> -<PARA> -Specifies that -<application>psql</application> -should do its work quietly. By default, it -prints welcome and exit messages and prompts for each query, and prints -out the number of rows returned from a query. -If this option is used, none of this happens. This is useful with the -<option>-c</option> option. - -<VARLISTENTRY> -<TERM> --s -</TERM> -<LISTITEM> -<PARA> -Run in single-step mode where the user is prompted for each query before -it is sent to the backend. - -<VARLISTENTRY> -<TERM> --S -</TERM> -<LISTITEM> -<PARA> -Runs in single-line mode where each query is terminated by a newline, -instead of a semicolon. - -<VARLISTENTRY> -<TERM> --t -</TERM> -<LISTITEM> -<PARA> -Turn off printing of column names. -This is useful with the -<option>-c</option> -option in shell scripts. - -<VARLISTENTRY> -<TERM> --T <replaceable class="parameter">table_options</replaceable> -</TERM> -<LISTITEM> -<PARA> -Allows you to specify options to be placed within the - <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym> -tabular output.For example, <literal>border</literal> -will give you tables with borders. -This must be used in conjunction with the <option>-H</option> option. - -<VARLISTENTRY> -<TERM> --u -</TERM> -<LISTITEM> -<PARA> -Asks the user for the user name and password before connecting to the database. -If the database does not require password authentication then these are -ignored. If the option is not used (and the PGPASSWORD environment variable -is not set) and the database requires password authentication, then the -connection will fail. The user name is ignored anyway. - -<VARLISTENTRY> -<TERM> --x -</TERM> -<LISTITEM> -<PARA> -Turns on extended row format mode. When enabled each row will have its column -names printed on the left with the column values printed on the right. -This is useful for rows which are otherwise too long to fit into -one screen line. HTML row output supports this mode also. -</variablelist> - -<para> -You may set environment variables to avoid typing some of the above -options. See the section on environment variables below. - - -<REFSECT1 ID="R1-APP-PSQL-3"> -<REFSECT1INFO> -<DATE>1998-09-26</DATE> -</REFSECT1INFO> -<TITLE> -<application>psql</application> Meta-Commands -</TITLE> -<para> -Anything you enter in <application>psql</application> -that begins with an unquoted backslash is a <application>psql</application> -meta-command. Anything else is <acronym>SQL</acronym> - and simply goes into the current query buffer -(and once you have at least one complete query, it gets automatically -submitted to the backend). -<Application>psql</Application> meta-commands are also called slash commands. - -<para> -The format of a <application>psql</application> command is the backslash, -followed immediately by -a command verb, then any arguments. The arguments are separated from the -command verb and each other by any number of white space characters. - -<para> -With single character command verbs, you don't actually need to separate the -command verb from the argument with white space, for historical reasons. -You should anyway. - -<para> -The following meta-commands are defined: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<literal>\a</literal> -</TERM> -<LISTITEM> -<PARA> -Toggle field alignment when printing out table elements. - -<VARLISTENTRY> -<TERM> -<literal>\C</literal> <replaceable class="parameter">caption</replaceable> -</TERM> -<LISTITEM> -<PARA> -Set the HTML3.0 table caption to -<quote><replaceable class="parameter">caption</replaceable></quote>. - -<VARLISTENTRY> -<TERM> -<literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Establish a connection to a new database, using the default -<replaceable class="parameter">username</replaceable> if none is specified. -The previous connection is closed. - -<VARLISTENTRY> -<TERM> -<literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable> -</TERM> -<LISTITEM> -<PARA> -Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, -but instead of the backend reading or writing the specified file, and -consequently requiring backend access and special user privilege, -<application>psql</application> reads or writes the -file and routes the data to or from the backend. The default <literal>tab</literal> -delimiter is used. -<tip> -<para> -This operation is not as efficient as the <acronym>SQL</acronym> -<command>COPY</command> command because all data must pass through the -client/server IP or socket connection. For large amounts of data this other -technique may be preferable. -</tip> - -<VARLISTENTRY> -<TERM> -<literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -List tables in the database, or if <replaceable class="parameter">table</replaceable> -is specified, list the columns in that table. -If table name is specified as an asterisk (<quote>*</quote>), -list all tables and column information for each tables. - -<VARLISTENTRY> -<TERM> -<literal>\da</literal> -</TERM> -<LISTITEM> -<PARA> -List all available aggregates. - -<VARLISTENTRY> -<TERM> -<literal>\dd</literal> <replaceable class="parameter">object</replaceable> -</TERM> -<LISTITEM> -<PARA> -List the description from <literal>pg_description</literal> -of the specified object, which can be a -table, table.column, type, operator, or aggregate. -<tip> -<para> -Not all objects have a description in <literal>pg_description</literal>. -This meta-command can be useful to get a quick description of a native -<productname>Postgres</productname> feature. -</tip> - -<VARLISTENTRY> -<TERM> -<literal>\df</literal> -</TERM> -<LISTITEM> -<PARA> -List functions. - -<VARLISTENTRY> -<TERM> -<literal>\di</literal> -</TERM> -<LISTITEM> -<PARA> -List only indexes. - -<VARLISTENTRY> -<TERM> -<literal>\do</literal> -</TERM> -<LISTITEM> -<PARA> -List only operators. - -<VARLISTENTRY> -<TERM> -<literal>\ds</literal> -</TERM> -<LISTITEM> -<PARA> -List only sequences. - -<VARLISTENTRY> -<TERM> -<literal>\dS</literal> -</TERM> -<LISTITEM> -<PARA> -List system tables and indexes. - -<VARLISTENTRY> -<TERM> -<literal>\dt</literal> -</TERM> -<LISTITEM> -<PARA> -List only non-system tables. - -<VARLISTENTRY> -<TERM> -<literal>\dT</literal> -</TERM> -<LISTITEM> -<PARA> -List types. - -<VARLISTENTRY> -<TERM> -<literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Edit the current query buffer or the contents of the file -<replaceable class="parameter">filename</replaceable>. - -<VARLISTENTRY> -<TERM> -<literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Edit the current query buffer or the contents of the file -<replaceable class="parameter">filename</replaceable> -and execute it upon editor exit. - -<VARLISTENTRY> -<TERM> -<literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Set the field separator. Default is a single blank space. - -<VARLISTENTRY> -<TERM> -<literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] -</TERM> -<LISTITEM> -<PARA> -Send the current query input buffer to the backend and optionally -save the output in <replaceable class="parameter">filename</replaceable> -or pipe the output into a separate Unix shell to execute -<replaceable class="parameter">command</replaceable>. - -<VARLISTENTRY> -<TERM> -<literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Give syntax help on the specified SQL command. -If <replaceable class="parameter">command</replaceable> is not a defined SQL command -(or is not documented in <application>psql</application>), or if -<replaceable class="parameter">command</replaceable> is not specified, -then <application>psql</application> will -list all the commands for which syntax help is -available. If <replaceable class="parameter">command</replaceable> -is an asterisk (<quote>*</quote>), then -give syntax help on all SQL commands. - -<VARLISTENTRY> -<TERM> -<literal>\H</literal> -</TERM> -<LISTITEM> -<PARA> -Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option> -command-line option. - -<VARLISTENTRY> -<TERM> -<literal>\i</literal> <replaceable class="parameter">filename</replaceable> -</TERM> -<LISTITEM> -<PARA> -Read queries from the file <replaceable class="parameter">filename</replaceable> -into the query input buffer. - -<VARLISTENTRY> -<TERM> -<literal>\l</literal> -</TERM> -<LISTITEM> -<PARA> -List all the databases in the server. - -<VARLISTENTRY> -<TERM> -<literal>\m</literal> -</TERM> -<LISTITEM> -<PARA> -Toggle the old monitor-like table display, which includes border characters -surrounding the table. -This is standard SQL output. -By default, <application>psql</application> includes only field separators -between columns. - -<VARLISTENTRY> -<TERM> -<literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] -</TERM> -<LISTITEM> -<PARA> -Save future query results to the file -<replaceable class="parameter">filename</replaceable> or pipe future -results into a separate Unix shell to execute -<replaceable class="parameter">command</replaceable>. -If no arguments are specified, send query results to -<filename>stdout</filename>. - -<VARLISTENTRY> -<TERM> -<literal>\p</literal> -</TERM> -<LISTITEM> -<PARA> -Print the current query buffer. - -<VARLISTENTRY> -<TERM> -<literal>\q</literal> -</TERM> -<LISTITEM> -<PARA> -Quit the <application>psql</application> program. - -<VARLISTENTRY> -<TERM> -<literal>\r</literal> -</TERM> -<LISTITEM> -<PARA> -Reset(clear) the query buffer. - -<VARLISTENTRY> -<TERM> -<literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Print or save the command line history to -<replaceable class="parameter">filename</replaceable>. -If <replaceable class="parameter">filename</replaceable> is omitted, -do not save subsequent commands to a history file. -This option is only available if <application>psql</application> is -configured to use readline. - -<VARLISTENTRY> -<TERM> -<literal>\t</literal> -</TERM> -<LISTITEM> -<PARA> -Toggle display of output column name headings and row count footer (defaults to on). - -<VARLISTENTRY> -<TERM> -<literal>\T</literal> <replaceable class="parameter">table_options</replaceable> -</TERM> -<LISTITEM> -<PARA> -Allows you to specify options to be placed within the - <sgmltag>table ...</sgmltag> tag -for <acronym>HTML 3.0</acronym> -tabular output.For example, <literal>border</literal> -will give you tables with borders. -This must be used in conjunction with the <command>\H</command> meta-command. - -<VARLISTENTRY> -<TERM> -<literal>\x</literal> -</TERM> -<LISTITEM> -<PARA> -Toggles extended row format mode. When enabled each row will have its column -names printed on the left with the column values printed on the right. -This is useful for rows which are otherwise too long to fit into -one screen line. <acronym>HTML</acronym> row output mode supports this flag too. - -<VARLISTENTRY> -<TERM> -<literal>\w</literal> <replaceable class="parameter">filename</replaceable> -</TERM> -<LISTITEM> -<PARA> -Outputs the current query buffer to the file -<replaceable class="parameter">filename</replaceable>. - -<VARLISTENTRY> -<TERM> -<literal>\z</literal> -</TERM> -<LISTITEM> -<PARA> -Produces a list of all tables in the database with their appropriate ACLs -(grant/revoke permissions) listed. - -<VARLISTENTRY> -<TERM> -<literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ] -</TERM> -<LISTITEM> -<PARA> -Escape to a separate Unix shell or execute the Unix command -<replaceable class="parameter">command</replaceable>. - -<VARLISTENTRY> -<TERM> -<literal>\?</literal> -</TERM> -<LISTITEM> -<PARA> -Get help information about the slash (<quote>\</quote>) commands. - -</variablelist> - + <REFSECT2 ID="R2-APP-PSQL-1"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + <application>psql</application> accepts many command-line arguments, + a rich set of meta-commands, and the full <acronym>SQL</acronym> language + supported by <productname>Postgres</productname>. The most common + command-line arguments are: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE> + </TERM> + <LISTITEM> + <PARA> + The name of an existing database to access. + <replaceable class="parameter">dbname</replaceable> + defaults to the value of the + <envar>USER</envar> + environment variable or, if that's not set, to the Unix account name of the + current user. + + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + -c <replaceable class="parameter">query</replaceable> + </TERM> + <LISTITEM> + <PARA> + A single query to run. <application>psql</application> will exit on completion. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + </variablelist> + </para> + <para> + The full set of command-line arguments and meta-commands are described in a subsequent + section. + </para> + <para> + There are some environment variables which can be used in liu of + command line arguments. + Additionally, the <productname>Postgres</productname> frontend library used by + the <application>psql</application> application + looks for other optional environment variables to configure, for example, + the style of date/time representation and the local time zone. Refer + to the chapter on <filename>libpq</filename> in the + <citetitle>Programmer's Guide</citetitle> for more details. + </para> + <para> + You may set any of the following environment variables to avoid + specifying command-line options: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <envar>PGHOST</envar> + </TERM> + <LISTITEM> + <PARA> + The <acronym>DNS</acronym> host name of the database server. + Setting <envar>PGHOST</envar> to a non-zero-length string causes + <acronym>TCP/IP</acronym> communication + to be used, rather than the default local Unix domain sockets. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGPORT</envar> + </TERM> + <LISTITEM> + <PARA> + The port number on which a <productname>Postgres</productname> server is listening. + Defaults to <literal>5432</literal>. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGTTY</envar> + </TERM> + <LISTITEM> + <PARA> + The target for display of messages from the client support library. + Not required. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGOPTION</envar> + </TERM> + <LISTITEM> + <PARA> + If <envar>PGOPTION</envar> + is specified, then the options it contains are parsed + <emphasis>before</emphasis> + any command-line options. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGREALM</envar> + </TERM> + <LISTITEM> + <PARA> + <envar>PGREALM</envar> + only applies if + <productname>Kerberos</productname> + authentication is in use. + If this environment variable is set, <productname>Postgres</productname> + will attempt authentication with servers for this realm and will use + separate ticket files to avoid conflicts with local ticket files. + See the <citetitle>PostgreSQL Administrator's Guide</citetitle> + for additional information on + <productname>Kerberos</productname>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PSQL-2"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + + <application>psql</application> + returns 0 to the shell on successful completion of all queries, + 1 for errors, 2 for abrupt disconnection from the backend. + The default TAB delimiter is used. + <application>psql</application> + will also return 1 if the connection to a database could not be made for + any reason. + </para> + </refsect2> + </refsynopsisdiv> + + <REFSECT1 ID="R1-APP-PSQL-1"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + <application>psql</application> is a character-based front-end to + <productname>Postgres</productname>. + It enables you to + type in queries interactively, issue them to <productname>Postgres</productname>, + and see the query + results. + </para> + <para> + <application>psql</application> + is a <productname>Postgres</productname> client application. Hence, a + <application>postmaster</application> process + must be running on the database server host before + <application>psql</application> + is executed. In addition, the correct parameters to identify + the database server, such as the + <application>postmaster</application> host name, + may need to be specified + as described below. + </para> + <para> + When + <application>psql</application> + starts, it reads SQL commands from + <filename>/etc/psqlrc</filename> + and then from + <filename>$(<envar>HOME</envar>)/.psqlrc</filename> + This allows SQL commands like + <command>SET</command> + which can be used to set the date style to be run at the start of + every session. + </para> + + <REFSECT2 ID="R2-APP-PSQL-3"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Connecting To A Database + </TITLE> + <para> + <application>psql</application> + attempts to make a connection to the database at the hostname and + port number specified on the command line. If the connection could not + be made for any reason (e.g. insufficient privileges, postmaster is not + running on the server, etc) + .IR <application>psql</application> + will return an error that says + <programlisting> + Connection to database failed. + </programlisting> + The reason for the connection failure is not provided. + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PSQL-4"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Entering Queries + </TITLE> + <para> + In normal operation, + <application>psql</application> provides a prompt with the name of the + database that <application>psql</application> is current connected to + followed by the string "=>". + For example, + <programlisting> + $ <userinput>psql testdb</userinput> + Welcome to the POSTGRESQL interactive sql monitor: + Please read the file COPYRIGHT for copyright terms of POSTGRESQL + + type \e? for help on slash commands + type \eq to quit + type \eg or terminate with semicolon to execute query + You are currently connected to the database: testdb + + testdb=> + </programlisting> + </para> + <para> + At the prompt, the user may type in <acronym>SQL</acronym> queries. + Unless the -S option + is set, input lines are sent to the backend when a query-terminating + semicolon is reached. + </para> + <para> + Whenever a query is executed, + <application>psql</application> also polls for asynchronous notification + events generated by <command>LISTEN</command> and <command>NOTIFY</command>. + </para> + <para> + <application>psql</application> + can be used in a pipe sequence, and automatically detects when it + is not listening or talking to a real tty. + </para> + </refsect2> + </refsect1> + + <REFSECT1 ID="R1-APP-PSQL-2"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + Command-line Options + </TITLE> + <para> + <application>psql</application> + understands the following command-line options: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + -A + </TERM> + <LISTITEM> + <PARA> + Turn off fill justification when printing out table elements. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -c <replaceable class="parameter">query</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies that + <application>psql</application> + is to execute one query string, + <replaceable class="parameter">query</replaceable>, + and then exit. This is useful for shell scripts, typically in + conjunction with the <option>-q</option> option in shell scripts. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -d <replaceable class="parameter">dbname</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the name of the database to connect to. This is equivalent to specifying + <replaceable class="parameter">dbname</replaceable> as the last field in the + command line. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -e + </TERM> + <LISTITEM> + <PARA> + Echo the query sent to the backend + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -f <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Use the file <replaceable class="parameter">filename</replaceable> + as the source of queries instead of reading queries interactively. + This file must be specified for and visible to the client frontend. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -F <replaceable class="parameter">separator</replaceable> + </TERM> + <LISTITEM> + <PARA> + Use <replaceable class="parameter">separator</replaceable> + as the field separator. + The default is an ASCII vertical bar ("|"). + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -h <replaceable class="parameter">hostname</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the host name of the machine on which the + <application>postmaster</application> + is running. + Without this option, communication is performed using + local Unix domain sockets. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -H + </TERM> + <LISTITEM> + <PARA> + Turns on + <acronym>HTML 3.0</acronym> + tabular output. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -l + </TERM> + <LISTITEM> + <PARA> + Lists all available databases, then exit. Other non-connection options are ignored. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -n + </TERM> + <LISTITEM> + <PARA> + Do not use the readline library for input line editing and command history. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -o <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Put all output into file <replaceable class="parameter">filename</replaceable>. + The path must be writable by the client. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -p <replaceable class="parameter">port</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the TCP/IP port or, by omission, the local Unix domain socket file + extension on which the + <application>postmaster</application> + is listening for connections. Defaults to the value of the + <envar>PGPORT</envar> + environment variable, if set, or to 5432. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -q + </TERM> + <LISTITEM> + <PARA> + Specifies that + <application>psql</application> + should do its work quietly. By default, it + prints welcome and exit messages and prompts for each query, and prints + out the number of rows returned from a query. + If this option is used, none of this happens. This is useful with the + <option>-c</option> option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -s + </TERM> + <LISTITEM> + <PARA> + Run in single-step mode where the user is prompted for each query before + it is sent to the backend. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -S + </TERM> + <LISTITEM> + <PARA> + Runs in single-line mode where each query is terminated by a newline, + instead of a semicolon. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -t + </TERM> + <LISTITEM> + <PARA> + Turn off printing of column names. + This is useful with the + <option>-c</option> + option in shell scripts. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -T <replaceable class="parameter">table_options</replaceable> + </TERM> + <LISTITEM> + <PARA> + Allows you to specify options to be placed within the + <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym> + tabular output.For example, <literal>border</literal> + will give you tables with borders. + This must be used in conjunction with the <option>-H</option> option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -u + </TERM> + <LISTITEM> + <PARA> + Asks the user for the user name and password before connecting to the database. + If the database does not require password authentication then these are + ignored. If the option is not used (and the PGPASSWORD environment variable + is not set) and the database requires password authentication, then the + connection will fail. The user name is ignored anyway. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -x + </TERM> + <LISTITEM> + <PARA> + Turns on extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. HTML row output supports this mode also. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + You may set environment variables to avoid typing some of the above + options. See the section on environment variables below. + </para> + </refsect1> + + <REFSECT1 ID="R1-APP-PSQL-3"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + <application>psql</application> Meta-Commands + </TITLE> + <para> + Anything you enter in <application>psql</application> + that begins with an unquoted backslash is a <application>psql</application> + meta-command. Anything else is <acronym>SQL</acronym> + and simply goes into the current query buffer + (and once you have at least one complete query, it gets automatically + submitted to the backend). + <Application>psql</Application> meta-commands are also called slash commands. + </para> + <para> + The format of a <application>psql</application> command is the backslash, + followed immediately by + a command verb, then any arguments. The arguments are separated from the + command verb and each other by any number of white space characters. + </para> + <para> + With single character command verbs, you don't actually need to separate the + command verb from the argument with white space, for historical reasons. + You should anyway. + </para> + <para> + The following meta-commands are defined: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <literal>\a</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle field alignment when printing out table elements. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\C</literal> <replaceable class="parameter">caption</replaceable> + </TERM> + <LISTITEM> + <PARA> + Set the HTML3.0 table caption to + <quote><replaceable class="parameter">caption</replaceable></quote>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Establish a connection to a new database, using the default + <replaceable class="parameter">username</replaceable> if none is specified. + The previous connection is closed. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, + but instead of the backend reading or writing the specified file, and + consequently requiring backend access and special user privilege, + <application>psql</application> reads or writes the + file and routes the data to or from the backend. The default <literal>tab</literal> + delimiter is used. + </para> + <tip> + <para> + This operation is not as efficient as the <acronym>SQL</acronym> + <command>COPY</command> command because all data must pass through the + client/server IP or socket connection. For large amounts of data this other + technique may be preferable. + </para> + </tip> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + List tables in the database, or if <replaceable class="parameter">table</replaceable> + is specified, list the columns in that table. + If table name is specified as an asterisk (<quote>*</quote>), + list all tables and column information for each tables. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\da</literal> + </TERM> + <LISTITEM> + <PARA> + List all available aggregates. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dd</literal> <replaceable class="parameter">object</replaceable> + </TERM> + <LISTITEM> + <PARA> + List the description from <literal>pg_description</literal> + of the specified object, which can be a + table, table.column, type, operator, or aggregate. + </para> + <tip> + <para> + Not all objects have a description in <literal>pg_description</literal>. + This meta-command can be useful to get a quick description of a native + <productname>Postgres</productname> feature. + </para> + </tip> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\df</literal> + </TERM> + <LISTITEM> + <PARA> + List functions. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\di</literal> + </TERM> + <LISTITEM> + <PARA> + List only indexes. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\do</literal> + </TERM> + <LISTITEM> + <PARA> + List only operators. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\ds</literal> + </TERM> + <LISTITEM> + <PARA> + List only sequences. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dS</literal> + </TERM> + <LISTITEM> + <PARA> + List system tables and indexes. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dt</literal> + </TERM> + <LISTITEM> + <PARA> + List only non-system tables. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dT</literal> + </TERM> + <LISTITEM> + <PARA> + List types. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Edit the current query buffer or the contents of the file + <replaceable class="parameter">filename</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Edit the current query buffer or the contents of the file + <replaceable class="parameter">filename</replaceable> + and execute it upon editor exit. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Set the field separator. Default is a single blank space. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] + </TERM> + <LISTITEM> + <PARA> + Send the current query input buffer to the backend and optionally + save the output in <replaceable class="parameter">filename</replaceable> + or pipe the output into a separate Unix shell to execute + <replaceable class="parameter">command</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Give syntax help on the specified SQL command. + If <replaceable class="parameter">command</replaceable> is not a defined SQL command + (or is not documented in <application>psql</application>), or if + <replaceable class="parameter">command</replaceable> is not specified, + then <application>psql</application> will + list all the commands for which syntax help is + available. If <replaceable class="parameter">command</replaceable> + is an asterisk (<quote>*</quote>), then + give syntax help on all SQL commands. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\H</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option> + command-line option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\i</literal> <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Read queries from the file <replaceable class="parameter">filename</replaceable> + into the query input buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\l</literal> + </TERM> + <LISTITEM> + <PARA> + List all the databases in the server. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\m</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle the old monitor-like table display, which includes border characters + surrounding the table. + This is standard SQL output. + By default, <application>psql</application> includes only field separators + between columns. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] + </TERM> + <LISTITEM> + <PARA> + Save future query results to the file + <replaceable class="parameter">filename</replaceable> or pipe future + results into a separate Unix shell to execute + <replaceable class="parameter">command</replaceable>. + If no arguments are specified, send query results to + <filename>stdout</filename>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\p</literal> + </TERM> + <LISTITEM> + <PARA> + Print the current query buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\q</literal> + </TERM> + <LISTITEM> + <PARA> + Quit the <application>psql</application> program. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\r</literal> + </TERM> + <LISTITEM> + <PARA> + Reset(clear) the query buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Print or save the command line history to + <replaceable class="parameter">filename</replaceable>. + If <replaceable class="parameter">filename</replaceable> is omitted, + do not save subsequent commands to a history file. + This option is only available if <application>psql</application> is + configured to use readline. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\t</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle display of output column name headings and row count footer (defaults to on). + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\T</literal> <replaceable class="parameter">table_options</replaceable> + </TERM> + <LISTITEM> + <PARA> + Allows you to specify options to be placed within the + <sgmltag>table ...</sgmltag> tag + for <acronym>HTML 3.0</acronym> + tabular output.For example, <literal>border</literal> + will give you tables with borders. + This must be used in conjunction with the <command>\H</command> meta-command. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\x</literal> + </TERM> + <LISTITEM> + <PARA> + Toggles extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. <acronym>HTML</acronym> row output mode supports this flag too. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\w</literal> <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Outputs the current query buffer to the file + <replaceable class="parameter">filename</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\z</literal> + </TERM> + <LISTITEM> + <PARA> + Produces a list of all tables in the database with their appropriate ACLs + (grant/revoke permissions) listed. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Escape to a separate Unix shell or execute the Unix command + <replaceable class="parameter">command</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\?</literal> + </TERM> + <LISTITEM> + <PARA> + Get help information about the slash (<quote>\</quote>) commands. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index a1292d3f64a..79b3b7d73c3 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -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> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> - Refer to the SET statement for more information on available - variables. -</variablelist> - -</REFSECT2> - -<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>. - + <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> + + <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 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> + + <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> diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index abbd2439d8e..5fc793ea1da 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -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> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> - The possible privileges are: - -<VARIABLELIST> -<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. - -<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-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> + + <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> + + <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> + + <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> - -</REFSECT2> - -<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> - -</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. + <programlisting> + INSERT INTO pg_group VALUES ('todos'); + CREATE USER miriam IN GROUP todos; + </programlisting> + </para> + </tip> + + </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; + + -- 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: + + <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> diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index 846a53837a9..d0fa6ec3d02 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -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> - -<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. - -<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> + <REFSECT2 ID="R2-SQL-ROLLBACK-1"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + None. + </para> + </REFSECT2> -<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. + <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> -</REFSECT1> + <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> -<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> diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 315447a0bea..f5be4b9aa1b 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -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> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 3328d73341e..4edea532c4a 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -12,6 +12,7 @@ SET <REFPURPOSE> Set run-time parameters for session </REFPURPOSE> + </refnamediv> <REFSYNOPSISDIV> <REFSYNOPSISDIVINFO> <DATE>1998-09-24</DATE> @@ -23,587 +24,718 @@ SET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> { TO | = } { '<REPLACE SET TIME ZONE { '<REPLACEABLE CLASS="PARAMETER">timezone</REPLACEABLE>' | LOCAL }; </SYNOPSIS> -<REFSECT2 ID="R2-SQL-SET-1"> -<REFSECT2INFO> -<DATE>1998-09-24</DATE> -</REFSECT2INFO> -<TITLE> -Inputs -</TITLE> -<PARA> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> -</TERM> -<LISTITEM> -<para> -Settable global parameter. - -<varlistentry> -<term> -<REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> -</term> -<listitem> -<PARA> -New value of parameter. -</variablelist> - -<para> -The possible variables and allowed values are: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -DateStyle -</TERM> -<LISTITEM> -<PARA> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -ISO -</TERM> -<LISTITEM> -<PARA> -use ISO 8601-style dates and times -<VARLISTENTRY> -<TERM> -SQL -</TERM> -<LISTITEM> -<PARA> -use Oracle/Ingres-style dates and times -<VARLISTENTRY> -<TERM> -Postgres -</TERM> -<LISTITEM> -<PARA> -use traditional <productname>Postgres</productname> format -<VARLISTENTRY> -<TERM> -European -</TERM> -<LISTITEM> -<PARA> -use dd/mm/yyyy for numeric date representations. -<VARLISTENTRY> -<TERM> -NonEuropean -</TERM> -<LISTITEM> -<PARA> -use mm/dd/yyyy for numeric date representations. -<VARLISTENTRY> -<TERM> -German -</TERM> -<LISTITEM> -<PARA> -use dd.mm.yyyy for numeric date representations. -<VARLISTENTRY> -<TERM> -US -</TERM> -<LISTITEM> -<PARA> -same as 'NonEuropean' -<VARLISTENTRY> -<TERM> -default -</TERM> -<LISTITEM> -<PARA> -restores the default values ('US,Postgres') -</varlistentry> -</variablelist> - -<para> - Date format initialization my be done by: -<simplelist> -<member> -Setting PGDATESTYLE environment variable. - -<member> -Running postmaster using -oe parameter to set - dates to the 'European' convention. -Note that this affects only the some combinations of date styles; for example -the ISO style is not affected by this parameter. -<member> -Changing variables in -<filename>src/backend/utils/init/globals.c</filename>. -</simplelist> - -<para> -The variables in <filename>globals.c</filename> which can be changed are: -<programlisting> -bool EuroDates = false - true -int DateStyle = USE_ISO_DATES - USE_POSTGRES_DATES - USE_ISO_DATES - USE_SQL_DATES - USE_GERMAN_DATES -</programlisting> - -</varlistentry> - -<varlistentry> -<term> -TIMEZONE -</term> -<listitem> -<para> - The possible values for timezone depends on your operating - system. For example on Linux /usr/lib/zoneinfo contains the - database of timezones. -<para> - Here are some valid values for timezone: - -<variablelist> -<varlistentry> -<term> -'PST8PDT' -</term> -<listitem> -<para> -set the timezone for California -<varlistentry> -<term> -'Portugal' -</term> -<listitem> -<para> -set time zone for Portugal. -<varlistentry> -<term> -'Europe/Rome' -</term> -<listitem> -<para> -set time zone for Italy. -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -set time zone to your local timezone -(value of the TZ environment variable). -</variablelist> - -<para> -If an invalid time zone is specified, the time zone -becomes GMT (on most systems anyway). - -<para> -A frontend which uses libpq may be initialized by setting the PGTZ -environment variable. - -<para> -The second syntax shown above, allows one to set the timezone -with a syntax similar to SQL92 <command>SET TIME ZONE</command>. -The LOCAL keyword is just an alternate form -of DEFAULT for SQL92 compatibility. - -</varlistentry> -</variablelist> - -There are also several internal or optimization - parameters which can be specified -by the <command>SET</command> command: - -<variablelist> -<varlistentry> -<term> -COST_HEAP -</term> -<listitem> -<para> -Sets the default cost of a heap scan for use by the optimizer. - -<variablelist> -<varlistentry> -<term> -<replaceable class="parameter">float4</replaceable> -</term> -<listitem> -<para> -Set the cost of a heap scan to the specified floating point value. - -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Sets the cost of a heap scan to the default value. -</variablelist> - -<para> - The frontend may be initialized by setting the PGCOSTHEAP - environment variable. - -<varlistentry> -<term> -COST_INDEX -</term> -<listitem> -<para> -Sets the default cost of an index scan for use by the optimizer. - -<variablelist> -<varlistentry> -<term> -<replaceable class="parameter">float4</replaceable> -</term> -<listitem> -<para> -Set the cost of an index scan to the specified floating point value. - -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Sets the cost of an index scan to the default value. -</variablelist> - -<para> - The frontend may be initialized by setting the PGCOSTINDEX - environment variable. - -<varlistentry> -<term> -GEQO -</term> -<listitem> -<para> -Sets the threshold for using the genetic optimizer algorithm. - -<variablelist> -<varlistentry> -<term> -On -</term> -<listitem> -<para> -enables the genetic optimizer algorithm - for statements with 8 or more tables. -<varlistentry> -<term> -On=<replaceable class="parameter">#</replaceable> -</term> -<listitem> -<para> -Takes an integer argument to enable the genetic optimizer algorithm - for statements with <replaceable class="parameter">#</replaceable> - or more tables in the query. -<varlistentry> -<term> -Off -</term> -<listitem> -<para> -disables the genetic optimizer algorithm. -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Equivalent to specifying <command>SET GEQO='on'</command> -</varlistentry> -</variablelist> - -<para> - This algorithm is on by default, which used GEQO for - statements of eight or more tables. - (See the chapter on GEQO in the Programmer's Guide -for more information). - -<para> - The frontend may be initialized by setting PGGEQO - environment variable. -</varlistentry> - -<varlistentry> -<term> -R_PLANS -</term> -<listitem> -<para> -Determines whether right-hand plan evaluation is allowed: - -<variablelist> -<varlistentry> -<term> -On -</term> -<listitem> -<para> -enables right-hand evaluation of plans. - -<varlistentry> -<term> -Off -</term> -<listitem> -<para> -disables right-hand evaluation of plans. - -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Equivalent to specifying <command>SET R_PLANS='off'</command>. -</variablelist> - -<para> - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. -<para> - The frontend may be initialized by setting the PGRPLANS - environment variable. -</varlistentry> - -<varlistentry> -<term> -KSQO -</term> -<listitem> -<para> -<firstterm>Key Set Query Optimizer</firstterm> forces the query optimizer -to optimize repetative OR clauses such as generated by -<productname>MicroSoft Access</productname>: - -<variablelist> -<varlistentry> -<term> -On -</term> -<listitem> -<para> -enables this optimization. - -<varlistentry> -<term> -Off -</term> -<listitem> -<para> -disables this optimization. - -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Equivalent to specifying <command>SET KSQO='off'</command>. -</variablelist> - -<para> - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. -<para> - The frontend may be initialized by setting the PGRPLANS - environment variable. - -<varlistentry> -<term> -QUERY_LIMIT -</term> -<listitem> -<para> -Sets the number of rows returned by a query. - -<variablelist> -<varlistentry> -<term> -Value -</term> -<listitem> -<para> -Maximum number of rows to return for a query. The default is to allow -an unlimited number of rows. -<varlistentry> -<term> -<replaceable class="parameter">#</replaceable> -</term> -<listitem> -<para> -Sets the maximum number of rows returned by a -query to <replaceable class="parameter">#</replaceable>. -<varlistentry> -<term> -DEFAULT -</term> -<listitem> -<para> -Sets the maximum number of rows returned by a query to be unlimited. -<para> -By default, there is no limit to the number of rows -returned by a query. -</varlistentry> - -</variablelist> - -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-SQL-SET-2"> -<REFSECT2INFO> -<DATE>1998-09-24</DATE> -</REFSECT2INFO> -<TITLE> -Outputs -</TITLE> -<PARA> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<returnvalue>SET VARIABLE</returnvalue> -</TERM> -<LISTITEM> -<PARA> - Message returned if successfully. - -<VARLISTENTRY> -<TERM> -<returnvalue>WARN: Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)</returnvalue> -</TERM> -<LISTITEM> -<PARA> - If the command fails to set variable. - -</VARIABLELIST> - -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-SQL-SET-1"> -<REFSECT1INFO> -<DATE>1998-09-24</DATE> -</REFSECT1INFO> -<TITLE> -Description -</TITLE> -<PARA> -<command>SET</command> will modify configuration parameters for variable during + <REFSECT2 ID="R2-SQL-SET-1"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> + </TERM> + <LISTITEM> + <para> + Settable global parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> + </term> + <listitem> + <PARA> + New value of parameter. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The possible variables and allowed values are: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + DateStyle + </TERM> + <LISTITEM> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + ISO + </TERM> + <LISTITEM> + <PARA> + use ISO 8601-style dates and times + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + SQL + </TERM> + <LISTITEM> + <PARA> + use Oracle/Ingres-style dates and times + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + Postgres + </TERM> + <LISTITEM> + <PARA> + use traditional <productname>Postgres</productname> format + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + European + </TERM> + <LISTITEM> + <PARA> + use dd/mm/yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + NonEuropean + </TERM> + <LISTITEM> + <PARA> + use mm/dd/yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + German + </TERM> + <LISTITEM> + <PARA> + use dd.mm.yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + US + </TERM> + <LISTITEM> + <PARA> + same as 'NonEuropean' + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + default + </TERM> + <LISTITEM> + <PARA> + restores the default values ('US,Postgres') + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Date format initialization my be done by: + <simplelist> + <member> + Setting PGDATESTYLE environment variable. + </member> + <member> + Running postmaster using -oe parameter to set + dates to the 'European' convention. + Note that this affects only the some combinations of date styles; for example + the ISO style is not affected by this parameter. + </member> + <member> + Changing variables in + <filename>src/backend/utils/init/globals.c</filename>. + </member> + </simplelist> + </para> + <para> + The variables in <filename>globals.c</filename> which can be changed are: + <programlisting> + bool EuroDates = false + true + int DateStyle = USE_ISO_DATES + USE_POSTGRES_DATES + USE_ISO_DATES + USE_SQL_DATES + USE_GERMAN_DATES + </programlisting> + </para> + <para> + <variablelist> + <varlistentry> + <term> + TIMEZONE + </term> + <listitem> + <para> + The possible values for timezone depends on your operating + system. For example on Linux /usr/lib/zoneinfo contains the + database of timezones. + </para> + <para> + Here are some valid values for timezone: + + <variablelist> + <varlistentry> + <term> + 'PST8PDT' + </term> + <listitem> + <para> + set the timezone for California + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + 'Portugal' + </term> + <listitem> + <para> + set time zone for Portugal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + 'Europe/Rome' + </term> + <listitem> + <para> + set time zone for Italy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + set time zone to your local timezone + (value of the TZ environment variable). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + If an invalid time zone is specified, the time zone + becomes GMT (on most systems anyway). + </para> + <para> + A frontend which uses libpq may be initialized by setting the PGTZ + environment variable. + </para> + <para> + The second syntax shown above, allows one to set the timezone + with a syntax similar to SQL92 <command>SET TIME ZONE</command>. + The LOCAL keyword is just an alternate form + of DEFAULT for SQL92 compatibility. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + There are also several internal or optimization + parameters which can be specified + by the <command>SET</command> command: + + <variablelist> + <varlistentry> + <term> + COST_HEAP + </term> + <listitem> + <para> + Sets the default cost of a heap scan for use by the optimizer. + + <variablelist> + <varlistentry> + <term> + <replaceable class="parameter">float4</replaceable> + </term> + <listitem> + <para> + Set the cost of a heap scan to the specified floating point value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Sets the cost of a heap scan to the default value. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The frontend may be initialized by setting the PGCOSTHEAP + environment variable. + </para> + <variablelist> + <varlistentry> + <term> + COST_INDEX + </term> + <listitem> + <para> + Sets the default cost of an index scan for use by the optimizer. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <replaceable class="parameter">float4</replaceable> + </term> + <listitem> + <para> + Set the cost of an index scan to the specified floating point value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Sets the cost of an index scan to the default value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The frontend may be initialized by setting the PGCOSTINDEX + environment variable. + + <variablelist> + <varlistentry> + <term> + GEQO + </term> + <listitem> + <para> + Sets the threshold for using the genetic optimizer algorithm. + </para> + + <variablelist> + <varlistentry> + <term> + On + </term> + <listitem> + <para> + enables the genetic optimizer algorithm + for statements with 8 or more tables. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + On=<replaceable class="parameter">#</replaceable> + </term> + <listitem> + <para> + Takes an integer argument to enable the genetic optimizer algorithm + for statements with <replaceable class="parameter">#</replaceable> + or more tables in the query. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Off + </term> + <listitem> + <para> + disables the genetic optimizer algorithm. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Equivalent to specifying <command>SET GEQO='on'</command> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + This algorithm is on by default, which used GEQO for + statements of eight or more tables. + (See the chapter on GEQO in the Programmer's Guide + for more information). + </para> + <para> + The frontend may be initialized by setting PGGEQO + environment variable. + + <variablelist> + + <varlistentry> + <term> + R_PLANS + </term> + <listitem> + <para> + Determines whether right-hand plan evaluation is allowed: + </para> + + <variablelist> + <varlistentry> + <term> + On + </term> + <listitem> + <para> + enables right-hand evaluation of plans. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Off + </term> + <listitem> + <para> + disables right-hand evaluation of plans. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Equivalent to specifying <command>SET R_PLANS='off'</command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + </para> + <para> + The frontend may be initialized by setting the PGRPLANS + environment variable. + <variablelist> + <varlistentry> + <term> + KSQO + </term> + <listitem> + <para> + <firstterm>Key Set Query Optimizer</firstterm> forces the query optimizer + to optimize repetative OR clauses such as generated by + <productname>MicroSoft Access</productname>: + </para> + + <variablelist> + <varlistentry> + <term> + On + </term> + <listitem> + <para> + enables this optimization. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Off + </term> + <listitem> + <para> + disables this optimization. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Equivalent to specifying <command>SET KSQO='off'</command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + </para> + <para> + The frontend may be initialized by setting the PGRPLANS + environment variable. + <variablelist> + <varlistentry> + <term> + QUERY_LIMIT + </term> + <listitem> + <para> + Sets the number of rows returned by a query. + </para> + + <variablelist> + <varlistentry> + <term> + Value + </term> + <listitem> + <para> + Maximum number of rows to return for a query. The default is to allow + an unlimited number of rows. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable class="parameter">#</replaceable> + </term> + <listitem> + <para> + Sets the maximum number of rows returned by a + query to <replaceable class="parameter">#</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Sets the maximum number of rows returned by a query to be unlimited. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + By default, there is no limit to the number of rows + returned by a query. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </REFSECT2> + + <REFSECT2 ID="R2-SQL-SET-2"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <returnvalue>SET VARIABLE</returnvalue> + </TERM> + <LISTITEM> + <PARA> + Message returned if successfully. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <returnvalue>WARN: Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)</returnvalue> + </TERM> + <LISTITEM> + <PARA> + If the command fails to set variable. + </para> + </listitem> + </varlistentry> + + </VARIABLELIST> + </para> + </REFSECT2> + </REFSYNOPSISDIV> + + <REFSECT1 ID="R1-SQL-SET-1"> + <REFSECT1INFO> + <DATE>1998-09-24</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + <command>SET</command> will modify configuration parameters for variable during a session. - -<para> - Current values can be obtained using <command>SHOW</command>, and values - can be restored to the defaults using <command>RESET</command>. - Parameters and values are case-insensitive. Note that the value - field is always specified as a string, so is enclosed in - single-quotes. -<para> - <command>SET TIME ZONE</command> changes the session's - default time zone offset. - A SQL-session always begins with an initial default time zone - offset. - The <command>SET TIME ZONE</command> statement is used to change the default - time zone offset for the current SQL session. - -<REFSECT2 ID="R2-SQL-SET-3"> -<REFSECT2INFO> -<DATE>1998-09-24</DATE> -</REFSECT2INFO> -<TITLE> -Notes -</TITLE> -<PARA> -The <command>SET <replaceable class="parameter">variable</replaceable></command> - statement is a <productname>Postgres</productname> language extension. - -<para> - Refer to <command>SHOW</command> and <command>RESET</command> to -display or reset the current values. - -</REFSECT2> -</REFSECT1> - -<REFSECT1 ID="R1-SQL-SET-2"> -<TITLE> -Usage -</TITLE> -<PARA> -</PARA> -<ProgramListing> ---Set the style of date to ISO: --- -SET DATESTYLE TO 'ISO'; -</programlisting> -<programlisting> ---Set GEQO to default: --- -SET GEQO = DEFAULT; -</programlisting> -<programlisting> ---Turn on right-hand evaluation of plans: --- -SET R_PLANS TO 'on'; -</programlisting> -<programlisting> ---set the timezone for Berkeley, California: -SET TIME ZONE 'PST8PDT'; - -SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 07:41:21-08 -</programlisting> -<programlisting> ---set the timezone for Italy: -SET TIME ZONE 'Europe/Rome'; - -SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 17:41:31+02 -</ProgramListing> - -</REFSECT1> - -<REFSECT1 ID="R1-SQL-SET-3"> -<TITLE> -Compatibility -</TITLE> -<PARA> -</PARA> - -<REFSECT2 ID="R2-SQL-SET-4"> -<REFSECT2INFO> -<DATE>1998-09-24</DATE> -</REFSECT2INFO> -<TITLE> -SQL92 -</TITLE> -<PARA> - There is no -<command>SET <replaceable class="parameter">variable</replaceable></command> - in <acronym>SQL92</acronym>. - - The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command> - is slightly different, - allowing only a single integer value for time zone specification: - -<programlisting> -SET TIME ZONE { interval_value_expression | LOCAL } -</programlisting> - + </para> + <para> + Current values can be obtained using <command>SHOW</command>, and values + can be restored to the defaults using <command>RESET</command>. + Parameters and values are case-insensitive. Note that the value + field is always specified as a string, so is enclosed in + single-quotes. + </para> + <para> + <command>SET TIME ZONE</command> changes the session's + default time zone offset. + A SQL-session always begins with an initial default time zone + offset. + The <command>SET TIME ZONE</command> statement is used to change the default + time zone offset for the current SQL session. + </para> + + <REFSECT2 ID="R2-SQL-SET-3"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Notes + </TITLE> + <PARA> + The <command>SET <replaceable class="parameter">variable</replaceable></command> + statement is a <productname>Postgres</productname> language extension. + </para> + <para> + Refer to <command>SHOW</command> and <command>RESET</command> to + display or reset the current values. + </para> + </REFSECT2> + </REFSECT1> + + <REFSECT1 ID="R1-SQL-SET-2"> + <TITLE> + Usage + </TITLE> + <PARA> + </PARA> + <ProgramListing> + --Set the style of date to ISO: + -- + SET DATESTYLE TO 'ISO'; + </programlisting> + <programlisting> + --Set GEQO to default: + -- + SET GEQO = DEFAULT; + </programlisting> + <programlisting> + --Turn on right-hand evaluation of plans: + -- + SET R_PLANS TO 'on'; + </programlisting> + <programlisting> + --set the timezone for Berkeley, California: + SET TIME ZONE 'PST8PDT'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 07:41:21-08 + </programlisting> + <programlisting> + --set the timezone for Italy: + SET TIME ZONE 'Europe/Rome'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 17:41:31+02 + </ProgramListing> + + </REFSECT1> + + <REFSECT1 ID="R1-SQL-SET-3"> + <TITLE> + Compatibility + </TITLE> + <PARA> + </PARA> + + <REFSECT2 ID="R2-SQL-SET-4"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + SQL92 + </TITLE> + <PARA> + There is no + <command>SET <replaceable class="parameter">variable</replaceable></command> + in <acronym>SQL92</acronym>. + + The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command> + is slightly different, + allowing only a single integer value for time zone specification: + + <programlisting> + SET TIME ZONE { interval_value_expression | LOCAL } + </programlisting> + </para> + </refsect2> + </refsect1> </REFENTRY> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 36d605eacc9..4db7531fbdf 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -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> - -<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. -</listitem> - -<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. - -</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> + <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> + + <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> + + <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> + + <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> + + <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> + + <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> diff --git a/doc/src/sgml/ref/unlisten.sgml b/doc/src/sgml/ref/unlisten.sgml index 46ed06c9033..5f37388d66c 100644 --- a/doc/src/sgml/ref/unlisten.sgml +++ b/doc/src/sgml/ref/unlisten.sgml @@ -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> diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index a02e022329f..6861c983f7d 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -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> - -<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> - -<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> + <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> + + <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> + + <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> - -</REFSECT1> - -<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: - -<programlisting> + </ProgramListing> + + </REFSECT1> + + <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: + + <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> diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 726acae47d0..98758c773ee 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -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> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -VERBOSE -<LISTITEM> -<PARA> -Prints a detailed vacuum activity report for each table. - -<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. - -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> -<LISTITEM> -<PARA> -The name of a specific table to vacuum. Defaults to all tables. - -<VARLISTENTRY> -<TERM> -<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> -<LISTITEM> -<PARA> -The name of a specific column to analyze. Defaults to all columns. - -</VARIABLELIST> - -</REFSECT2> - -<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> + <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> + + <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. + </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> + 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> + + <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. + + Running <command>VACUUM</command> + periodically will increase the speed of the database in processing user queries. + </para> + + <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> + + <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> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 21bdd13671b..b1714c16cfe 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -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: - -<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. - -<varlistentry> -<term> ---analyze -</term> -<term> --z -</term> -<listitem> -<para> -Calculate statistics on the database for use by the optimizer. - -<varlistentry> -<term> ---verbose -</term> -<term> --v -</term> -<listitem> -<para> -Print detailed information during processing. - -<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. - -</variablelist> - -<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.. - -<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> + <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> -<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. + </variablelist> + </para> + </refsect2> -<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: + <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. -<programlisting> -% vacuumdb -</programlisting> + <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> -<para> -To analyze a database named <literal>bigdb</literal> for the optimizer: + <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> -<programlisting> -% vacuumdb --analyze bigdb -</programlisting> + <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> -To analyze a single column <literal>bar</literal> in table <literal>foo</literal> - in a database named <literal>xyzzy</literal> for the optimizer: + <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> -<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 |