diff options
Diffstat (limited to 'doc/src')
81 files changed, 2286 insertions, 766 deletions
diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index 32fc9a27fd0..e97654a0778 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/abort.sgml,v 1.4 1999/07/22 15:09:05 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-ABORT"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-abort-title"> ABORT </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,10 +20,10 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-27</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -ABORT [ TRANSACTION | WORK ] +ABORT [ WORK | TRANSACTION ] </synopsis> <refsect2 id="R2-SQL-ABORT-1"> diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 07ea4d2ef6b..a0558440d72 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,8 +1,8 @@ -<!-- allfiles.sgml -- -- Complete list of usable sgml source files in this directory. -- -- --> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.10 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +Complete list of usable sgml source files in this directory. +--> <!entity intro-ref system "intro-ref.sgml"> <!entity commands system "commands.sgml"> @@ -38,22 +38,6 @@ <!entity trim system "trim.sgml"> <!entity upper system "upper.sgml"> -<!-- these are folded into create_table.sgml -<!entity check system "check.sgml"> -<!entity constraints system "constraint.sgml"> -<!entity default system "default.sgml"> -<!entity notNull system "not_null.sgml"> -<!entity primaryKey system "primary_key.sgml"> -<!entity unique system "unique.sgml"> ---> - -<!-- these are folded into select.sgml -<!entity groupBy system "group_by.sgml"> -<!entity having system "having.sgml"> -<!entity orderBy system "order_by.sgml"> -<!entity union system "union.sgml"> ---> - <!-- these are in the "commands" reference chapter --> <!entity abort system "abort.sgml"> <!entity alterTable system "alter_table.sgml"> @@ -92,6 +76,7 @@ <!entity dropType system "drop_type.sgml"> <!entity dropUser system "drop_user.sgml"> <!entity dropView system "drop_view.sgml"> +<!entity end system "end.sgml"> <!entity explain system "explain.sgml"> <!entity fetch system "fetch.sgml"> <!entity grant system "grant.sgml"> @@ -117,12 +102,15 @@ <!entity createuser system "createuser.sgml"> <!entity destroydb system "destroydb.sgml"> <!entity destroyuser system "destroyuser.sgml"> +<!entity ecpgRef system "ecpg-ref.sgml"> <!entity initdb system "initdb.sgml"> <!entity initlocation system "initlocation.sgml"> +<!entity ipcclean system "ipcclean.sgml"> <!entity pgAccess system "pgaccess-ref.sgml"> <!entity pgAdmin system "pgadmin-ref.sgml"> <!entity pgDump system "pg_dump.sgml"> <!entity pgDumpall system "pg_dumpall.sgml"> +<!entity pgPasswd system "pg_passwd.sgml"> <!entity pgUpgrade system "pg_upgrade.sgml"> <!entity postgres system "postgres-ref.sgml"> <!entity postmaster system "postmaster.sgml"> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 25a2b948e49..715836f9acd 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.8 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-ALTERTABLE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-altertable-title"> ALTER TABLE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> ALTER TABLE <replaceable class="PARAMETER">table</replaceable> @@ -166,9 +171,37 @@ ERROR </para> <para> - <quote>[*]</quote> following a name of a table indicates that statement + <quote>*</quote> following a name of a table indicates that the statement should be run over that table and all tables below it in the - inheritance hierarchy. + inheritance hierarchy; + by default, the attribute will not be added to or renamed in any of the subclasses. + + This should always be done when adding or modifying an attribute in a + superclass. If it is not, queries on the inheritance hierarchy + such as + + <programlisting> +SELECT <replaceable>NewColumn</replaceable> FROM <replaceable>SuperClass</replaceable>* + </programlisting> + + will not work because the subclasses will be missing an attribute + found in the superclass. + </para> + + <para> + For efficiency reasons, default values for added attributes are + not placed in existing instances of a class. + That is, existing instances will have NULL values in the new + attributes. If non-NULL values are desired, a subsequent + <command>UPDATE</command> query + (<xref linkend="sql-update-title" endterm="sql-update-title">) + should be run. + </para> + + <para> + You must own the class in order to change its schema. + Renaming any part of the schema of a system + catalog is not permitted. The <citetitle>PostgreSQL User's Guide</citetitle> has further information on inheritance. </para> diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml index b7dc46e4b18..686684632a5 100644 --- a/doc/src/sgml/ref/alter_user.sgml +++ b/doc/src/sgml/ref/alter_user.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.8 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-ALTERUSER"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-alteruser-title"> ALTER USER </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-08</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> ALTER USER <replaceable class="PARAMETER">username</replaceable> [ WITH PASSWORD <replaceable class="PARAMETER">password</replaceable> ] @@ -126,7 +131,7 @@ ERROR: alterUser: user "username" does not exist <command>ALTER USER</command> is used to change the attributes of a user's <productname>Postgres</productname> account. Please note that it is not possible - to alter a user's "usesysid" via the alter user + to alter a user's "<literal>usesysid</literal>" via the alter user statement. Also, it is only possible for the <productname>Postgres</productname> user or any user with read and modify permissions on @@ -135,7 +140,7 @@ ERROR: alterUser: user "username" does not exist <para> If any of the clauses of the alter user statement are - omitted, the corresponding value in the "pg_shadow" table + omitted, the corresponding value in the <literal>pg_shadow</literal> table is left unchanged. </para> @@ -205,8 +210,6 @@ ALTER USER miriam IN GROUP sales, payroll; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-ALTERUSER-4"> <refsect2info> diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml index 09d5fe57deb..a6e45aaadb1 100644 --- a/doc/src/sgml/ref/begin.sgml +++ b/doc/src/sgml/ref/begin.sgml @@ -1,6 +1,11 @@ -<refentry id="SQL-BEGINWORK"> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.9 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + +<refentry id="SQL-BEGIN"> <refmeta> - <refentrytitle id="SQL-BEGINWORK-TITLE"> + <refentrytitle id="SQL-BEGIN-TITLE"> BEGIN </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -16,13 +21,13 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1999-06-11</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> BEGIN [ WORK | TRANSACTION ] </synopsis> - <refsect2 id="R2-SQL-BEGINWORK-1"> + <refsect2 id="R2-SQL-BEGIN-1"> <refsect2info> <date>1999-06-11</date> </refsect2info> @@ -30,11 +35,22 @@ BEGIN [ WORK | TRANSACTION ] Inputs </title> <para> - None. + + <variablelist> + <varlistentry> + <term>WORK</term> + <term>TRANSACTION</term> + <listitem> + <para> + Optional keywords. They have no effect. + </para> + </listitem> + </varlistentry> + </variablelist> </para> </refsect2> - <refsect2 id="R2-SQL-BEGINWORK-2"> + <refsect2 id="R2-SQL-BEGIN-2"> <refsect2info> <date>1999-06-11</date> </refsect2info> @@ -70,7 +86,7 @@ NOTICE: BeginTransactionBlock and not in default state </refsect2> </refsynopsisdiv> - <refsect1 id="R1-SQL-BEGINWORK-1"> + <refsect1 id="R1-SQL-BEGIN-1"> <refsect1info> <date>1999-06-11</date> </refsect1info> @@ -88,7 +104,9 @@ NOTICE: BeginTransactionBlock and not in default state (if execution was successful, otherwise a rollback is done). <command>BEGIN</command> initiates a user transaction in chained mode, i.e. all user statements after <command>BEGIN</command> command will - be executed in a single transaction until an explicit COMMIT, ROLLBACK + be executed in a single transaction until an explicit + <xref linkend="sql-commit-title" endterm="sql-commit-title">, + <xref linkend="sql-rollback-title" endterm="sql-rollback-title">, or execution abort. Statements in chained mode are executed much faster, because transaction start/commit requires significant CPU and disk activity. Execution of multiple statements inside a transaction @@ -102,7 +120,7 @@ NOTICE: BeginTransactionBlock and not in default state is READ COMMITTED, where queries inside the transaction see only changes committed before query execution. So, you have to use <command>SET TRANSACTION ISOLATION LEVEL SERIALIZABLE</command> - just after BEGIN if you need more rigorous transaction isolation. + just after <command>BEGIN</command> if you need more rigorous transaction isolation. In SERIALIZABLE mode queries will see only changes committed before the entire transaction began (actually, before execution of the first DML statement @@ -116,7 +134,7 @@ NOTICE: BeginTransactionBlock and not in default state (atomic, consistent, isolatable, and durable) property. </para> - <refsect2 id="R2-SQL-BEGINWORK-3"> + <refsect2 id="R2-SQL-BEGIN-3"> <refsect2info> <date>1999-06-11</date> </refsect2info> @@ -129,7 +147,8 @@ NOTICE: BeginTransactionBlock and not in default state </para> <para> - Refer to the <command>LOCK</command> statement for further information + Refer to <xref linkend="sql-lock-title" endterm="sql-lock-title"> + for further information about locking tables inside a transaction. </para> @@ -142,7 +161,7 @@ NOTICE: BeginTransactionBlock and not in default state </refsect2> </refsect1> - <refsect1 id="R1-SQL-BEGINWORK-2"> + <refsect1 id="R1-SQL-BEGIN-2"> <title> Usage </title> @@ -156,25 +175,26 @@ BEGIN WORK; </para> </refsect1> - <refsect1 id="R1-SQL-BEGINWORK-3"> + <refsect1 id="R1-SQL-BEGIN-3"> <title> Compatibility </title> - <para> - <command>BEGIN</command> - is a <productname>Postgres</productname> language extension. - </para> - <refsect2 id="R2-SQL-BEGINWORK-4"> + + <refsect2 id="R2-SQL-BEGIN-4"> <refsect2info> <date>1999-06-11</date> </refsect2info> <title> SQL92 </title> - <para> - There is no explicit BEGIN WORK command in <acronym>SQL92</acronym>; + + <para> + <command>BEGIN</command> + is a <productname>Postgres</productname> language extension. + There is no explicit <command>BEGIN</command> + command in <acronym>SQL92</acronym>; transaction initiation is always implicit and it terminates either - with a COMMIT or with a ROLLBACK statement. + with a <command>COMMIT</command> or <command>ROLLBACK</command> statement. <note> <para> diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml index 6925849d60b..1a470c00b89 100644 --- a/doc/src/sgml/ref/close.sgml +++ b/doc/src/sgml/ref/close.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/close.sgml,v 1.7 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CLOSE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-CLOSE-TITLE"> CLOSE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-08</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CLOSE <replaceable class="PARAMETER">cursor</replaceable> @@ -131,8 +136,6 @@ CLOSE liahona; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CLOSE-4"> <refsect2info> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index bfae55585e5..2b66cf86907 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.7 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CLUSTER"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-cluster-title"> CLUSTER </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -10,12 +15,12 @@ CLUSTER </refname> <refpurpose> - Gives storage clustering advice to the backend + Gives storage clustering advice to the server </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-08</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">table</replaceable> @@ -72,7 +77,7 @@ CLUSTER </varlistentry> <varlistentry> <term><computeroutput> -ERROR: relation <<replaceable class="PARAMETER">tablerelation_number</replaceable>> inherits "invoice" +ERROR: relation <<replaceable class="PARAMETER">tablerelation_number</replaceable>> inherits "<replaceable class="PARAMETER">table</replaceable>" </computeroutput></term> <listitem> <para> @@ -85,12 +90,12 @@ ERROR: relation <<replaceable class="PARAMETER">tablerelation_number</replace </varlistentry> <varlistentry> <term><computeroutput> -ERROR: Relation x does not exist! +ERROR: Relation <replaceable class="PARAMETER">table</replaceable> does not exist! </computeroutput></term> <listitem> <para> <comment> - The relation complained of was not shown in the error message, + The specified relation was not shown in the error message, which contained a random string instead of the relation name. </comment> </para> @@ -111,12 +116,13 @@ ERROR: Relation x does not exist! <para> <command>CLUSTER</command> instructs <productname>Postgres</productname> to cluster the class specified - by <replaceable class="parameter">classname</replaceable> approximately + by <replaceable class="parameter">table</replaceable> approximately based on the index specified by <replaceable class="parameter">indexname</replaceable>. The index must already have been defined on <replaceable class="parameter">classname</replaceable>. </para> + <para> When a class is clustered, it is physically reordered based on the index information. The clustering is static. @@ -150,7 +156,8 @@ ERROR: Relation x does not exist! </para> <para> - Another place <command>CLUSTER</command> is helpful is in cases where you use an + Another place where <command>CLUSTER</command> is helpful is in + cases where you use an index to pull out several rows from a table. If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, @@ -173,11 +180,14 @@ ERROR: Relation x does not exist! <para> Another way to cluster data is to use + <programlisting> -SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ... ORDER BY ... +SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <replaceable class="parameter">newtable</replaceable> + FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable> </programlisting> - This uses the <productname>Postgres</productname> sorting code in - ORDER BY to match the index, and is much faster for + + which uses the <productname>Postgres</productname> sorting code in + the ORDER BY clause to match the index, and which is much faster for unordered data. You then drop the old table, use <command>ALTER TABLE/RENAME</command> to rename <replaceable class="parameter">temp</replaceable> to the old name, and @@ -205,8 +215,6 @@ CLUSTER emp_ind ON emp; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CLUSTER-4"> <refsect2info> diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index dced732e171..6ed2873c387 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/commands.sgml,v 1.17 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <chapter id="sql-commands"> <Title>SQL Commands</Title> @@ -45,6 +50,7 @@ &dropType &dropUser; &dropView; + &end; &explain; &fetch; &grant; @@ -88,7 +94,7 @@ functions supported by <productname>Postgres</productname>. --> - <chapter Id="utilities"> + <chapter Id="applications"> <title>Applications</title> <abstract> @@ -103,19 +109,37 @@ functions supported by <productname>Postgres</productname>. &createuser; &destroydb; &destroyuser; - &initdb; - &initlocation; + &ecpgRef; &pgAccess; &pgAdmin; &pgDump; &pgDumpall; - &postgres; - &postmaster; &psqlRef; &vacuumdb; </chapter> + <chapter Id="utilities"> + <title>System Applications</title> + + <abstract> + <para> + This is reference information for + <productname>Postgres</productname> + servers and support utilities. + </para> + </abstract> + + &initdb; + &initlocation; + &ipcclean; + &pgPasswd; + &pgUpgrade; + &postgres; + &postmaster; + + </chapter> + <!-- Keep this comment at the end of the file Local variables: mode: sgml diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index 5347534e29d..03dfea23f5f 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.8 1999/07/22 15:09:06 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-COMMIT"> <refmeta> <refentrytitle id="SQL-COMMIT-TITLE"> @@ -16,7 +21,7 @@ <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-08</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> COMMIT [ WORK | TRANSACTION ] @@ -30,7 +35,18 @@ COMMIT [ WORK | TRANSACTION ] Inputs </title> <para> - None. + + <variablelist> + <varlistentry> + <term>WORK</term> + <term>TRANSACTION</term> + <listitem> + <para> + Optional keywords. They have no effect. + </para> + </listitem> + </varlistentry> + </variablelist> </para> </refsect2> @@ -116,8 +132,6 @@ COMMIT WORK; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-COMMIT-4"> <refsect2info> diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 20081eb2e65..cc67e878c2a 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-COPY"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-copy-title"> COPY </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,16 +20,14 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-08</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] - FROM { '<replaceable class="parameter">filename</replaceable>' | - <filename>stdin</filename> } + FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> } [ USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] - TO { '<replaceable class="parameter">filename</replaceable>' | - <filename>stdout</filename> } + TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> } [ USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] </synopsis> @@ -47,6 +50,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">table</replaceable></term> <listitem> @@ -55,6 +59,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term>WITH OIDS</term> <listitem> @@ -63,6 +68,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">filename</replaceable></term> <listitem> @@ -71,6 +77,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term><filename>stdin</filename></term> <listitem> @@ -79,6 +86,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term><filename>stdout</filename></term> <listitem> @@ -87,6 +95,7 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">delimiter</replaceable></term> <listitem> @@ -121,7 +130,7 @@ COPY </varlistentry> <varlistentry> <term><computeroutput> -ERROR: <replaceable>error message</replaceable> +ERROR: <replaceable>reason</replaceable> </computeroutput></term> <listitem> <para> @@ -144,7 +153,7 @@ ERROR: <replaceable>error message</replaceable> <para> <command>COPY</command> moves data between <productname>Postgres</productname> tables and - standard Unix files. + standard file-system files. <command>COPY</command> instructs the <productname>Postgres</productname> backend @@ -175,8 +184,10 @@ ERROR: <replaceable>error message</replaceable> </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 + You must have <firstterm>select access</firstterm> on any table + whose values are read by + <command>COPY</command>, and either + <firstterm>insert or update access</firstterm> 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>. @@ -195,6 +206,44 @@ ERROR: <replaceable>error message</replaceable> </para> </tip> </para> + + <para> + <command>COPY</command> neither invokes rules nor acts on column defaults. + It does invoke triggers, however. + </para> + <para> + <command>COPY</command> stops operation at the first error. This + should not lead to problems in the event of + a <command>COPY FROM</command>, but the + target relation will, of course, be partially modified in a + <command>COPY TO</command>. + <command>VACUUM</command> should be used to clean up + after a failed copy. + </para> + <para> + Because the Postgres backend's current working directory + is not usually the same as the user's + working directory, the result of copying to a file + "<filename>foo</filename>" (without + additional path information) may yield unexpected results for the + naive user. In this case, <filename>foo</filename> + will wind up in <filename>$PGDATA/foo</filename>. In + general, the full pathname as it would appear to the backend server machine + should be used when specifying files to + be copied. + </para> + <para> + Files used as arguments to <command>COPY</command> + must reside on or be + accessible to the database server machine by being either on + local disks or on a networked file system. + </para> + <para> + When a TCP/IP connection from one machine to another is used, and a + target file is specified, the target file will be written on the + machine where the backend is running rather than the user's + machine. + </para> </refsect2> </refsect1> @@ -249,6 +298,7 @@ ERROR: <replaceable>error message</replaceable> properly. </para> </refsect2> + <refsect2> <refsect2info> <date>1998-05-04</date> @@ -385,53 +435,10 @@ has the termination sequence on the last line): </programlisting> </refsect1> - <refsect1 id="R1-SQL-COPY-5"> - <title>Bugs and features</title> - <para> - <command>COPY</command> neither invokes rules nor acts on column defaults. - It does invoke triggers, however. - </para> - <para> - <command>COPY</command> stops operation at the first error. This - should not lead to problems in the event of - a <command>COPY FROM</command>, but the - target relation will, of course, be partially modified in a -<command>COPY TO</command>. - The <command>VACUUM</command> query should be used to clean up - after a failed copy. - </para> - <para> - Because the Postgres backend's current working directory - is not usually the same as the user's - working directory, the result of copying to a file - "<filename>foo</filename>" (without - additional path information) may yield unexpected results for the - naive user. In this case, <filename>foo</filename> - will wind up in <filename>$PGDATA/foo</filename>. In - general, the full pathname as it would appear to the backend server machine -should be used when specifying files to - be copied. - </para> - <para> - Files used as arguments to <command>COPY</command> -must reside on or be - accessible to the database server machine by being either on - local disks or on a networked file system. - </para> - <para> - When a TCP/IP connection from one machine to another is used, and a - target file is specified, the target file will be written on the - machine where the backend is running rather than the user's - machine. - </para> - </refsect1> - <refsect1 id="R1-SQL-COPY-6"> <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-COPY-4"> <refsect2info> diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index 07cb8f15a2e..936ee2b43bc 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.7 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEAGGREGATE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createaggregate-title"> CREATE AGGREGATE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -16,19 +21,15 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-09</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> [ AS ] - ( BASETYPE = <replaceable class="PARAMETER">data_type</replaceable> - [ , SFUNC1 = <replaceable class="PARAMETER">sfunc1</replaceable> - , STYPE1 = <replaceable class="PARAMETER">sfunc1_return_type</replaceable> ] - [ , SFUNC2 = <replaceable class="PARAMETER">sfunc2</replaceable> - , STYPE2 = <replaceable class="PARAMETER">sfunc2_return_type</replaceable> ] +CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> [ AS ] ( BASETYPE = <replaceable class="PARAMETER">data_type</replaceable> + [ , SFUNC1 = <replaceable class="PARAMETER">sfunc1</replaceable>, STYPE1 = <replaceable class="PARAMETER">sfunc1_return_type</replaceable> ] + [ , SFUNC2 = <replaceable class="PARAMETER">sfunc2</replaceable>, STYPE2 = <replaceable class="PARAMETER">sfunc2_return_type</replaceable> ] [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ] [ , INITCOND1 = <replaceable class="PARAMETER">initial_condition1</replaceable> ] - [ , INITCOND2 = <replaceable class="PARAMETER">initial_condition2</replaceable> ] - ) + [ , INITCOND2 = <replaceable class="PARAMETER">initial_condition2</replaceable> ] ) </synopsis> <refsect2 id="R2-SQL-CREATEAGGREGATE-1"> @@ -296,10 +297,9 @@ CREATE </title> <para> Refer to the chapter on aggregate functions - in the <citetitle>PostgreSQL Programmer's Guide</citetitle> - on aggregate functions for + in the <citetitle>PostgreSQL Programmer's Guide</citetitle> for complete examples of usage. - </para> + </para> </refsect1> <refsect1 id="R1-SQL-CREATEAGGREGATE-3"> diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index cb0f18a589e..0be80b994c9 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEDATABASE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createdatabase-title"> CREATE DATABASE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> [ WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ] @@ -43,12 +48,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> [ WITH LOCATIO <term><replaceable class="parameter">dbpath</replaceable></term> <listitem> <para> - An alternate location can be specified as either an - environment variable known to the backend server - (e.g. '<envar>PGDATA2</envar>') or as an absolute path name - (e.g. '<filename>/usr/local/pgsql/data</filename>'). - In either case, the location must be pre-configured - by <command>initlocation</command>. + An alternate location for the new database. See below for caveats. </para> </listitem> </varlistentry> @@ -114,6 +114,16 @@ ERROR: Unable to create database directory <replaceable class="parameter">direc The creator becomes the administrator of the new database. </para> + <para> + An alternate location can be specified as either an + environment variable known to the backend server + (e.g. '<envar>PGDATA2</envar>') or, if the server is built to + allow it, as an absolute path name + (e.g. '<filename>/usr/local/pgsql/data</filename>'). + In either case, the location must be pre-configured + by <command>initlocation</command>. + </para> + <refsect2 id="R2-SQL-CREATEDATABASE-3"> <refsect2info> <date>1998-04-15</date> @@ -128,6 +138,28 @@ ERROR: Unable to create database directory <replaceable class="parameter">direc <para> Use <command>DROP DATABASE</command> to remove a database. </para> + + <para> + There are security and data integrity issues + involved with using alternate database locations + specified with absolute path names, and by default + only an environment variable known to the backend may be + specified for an alternate location. + See the Administrator's Guide for more information. + </para> + +<!-- +comment from Olly; response from Thomas... + <comment> + initlocation does not create a PG_VERSION file in the specified location. + How will Postgres handle the situation if it is upgraded to an + incompatible database version? + </comment> + Hmm. This isn't an issue since the upgrade would do + a dump/reload from the main database area also. + Not sure if the dump/reload would guarantee that + the alternate data area gets refreshed though... +--> </refsect2> </refsect1> @@ -166,31 +198,6 @@ ERROR: Unable to create database directory <replaceable class="parameter">direc </para> </refsect1> - <refsect1 id="R1-SQL-CREATEDATABASE-3"> - <title> - Bugs - </title> - <para> - There are security and data integrity issues - involved with using alternate database locations - specified with absolute path names, and by default - only an environment variable known to the backend may be - specified for an alternate location. - See the Administrator's Guide for more information. - </para> - </refsect1> - -<!-- -comment from Olly; response from Thomas... - <comment> - initlocation does not create a PG_VERSION file in the specified location. - How will Postgres handle the situation if it is upgraded to an - incompatible database version? - </comment> -Hmm. This isn't an issue since the upgrade would do a dump/reload from the main database area also. -Not sure if the dump/reload would guarantee that the alternate data area gets refreshed though... ---> - <refsect1 id="R1-SQL-CREATEDATABASE-4"> <title> Compatibility @@ -205,8 +212,6 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re </title> <para> There is no <command>CREATE DATABASE</command> statement in SQL92. - </para> - <para> The equivalent command in standard SQL is <command>CREATE SCHEMA</command>. </para> </refsect2> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 7ba3391a669..84f4f5c958f 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEFUNCTION"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createfunction-title"> CREATE FUNCTION </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-09</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] ) @@ -47,6 +52,10 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab <listitem> <para> The data type of function arguments. + The input types may be base or complex types, or + <firstterm>opaque</firstterm>. + <literal>opaque</literal> indicates that the function + accepts arguments of an invalid type such as <type>char *</type>. </para> </listitem> </varlistentry> @@ -55,6 +64,12 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab <listitem> <para> The return data type. + The output type may be specified as a base type, complex type, + <literal>setof <replaceable class="parameter">type</replaceable></literal>, + or <literal>opaque</literal>. + The <literal>setof</literal> + modifier indicates that the function will return a set of items, + rather than a single item. </para> </listitem> </varlistentry> @@ -77,7 +92,9 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab 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. + language. See + <xref linkend="sql-createlanguage-title" endterm="sql-createlanguage-title"> + for details. </para> </listitem> </varlistentry> @@ -133,43 +150,52 @@ CREATE Notes </title> <para> - Refer to the chapter on functions -in the <citetitle>PostgreSQL Programmer's Guide</citetitle> - for further information. + Refer to the chapter in + the <citetitle>PostgreSQL Programmer's Guide</citetitle> + on extending + <productname>Postgres</productname> via functions + for further information on writing external functions. </para> + <para> Use <command>DROP FUNCTION</command> to drop user-defined functions. </para> - <para> - <productname>Postgres</productname> allows function "overloading"; - that is, the same name can be used for several different functions - so long as they have distinct argument types. This facility must be - used with caution for INTERNAL and C-language functions, however. - </para> + <para> + <productname>Postgres</productname> allows function "overloading"; + that is, the same name can be used for several different functions + so long as they have distinct argument types. This facility must be + used with caution for <literal>internal</literal> + and C-language functions, however. + </para> - <para> - Two INTERNAL functions cannot have the same C name without causing - errors at link time. To get around that, give them different C names - (for example, use the argument types as part of the C names), then - specify those names in the AS clause of <command>CREATE FUNCTION</command>. - If the AS clause is left empty then <command>CREATE FUNCTION</command> - assumes the C name of the function is the same as the SQL name. - </para> + <para> + Two <literal>internal</literal> + functions cannot have the same C name without causing + errors at link time. To get around that, give them different C names + (for example, use the argument types as part of the C names), then + specify those names in the AS clause of <command>CREATE FUNCTION</command>. + If the AS clause is left empty then <command>CREATE FUNCTION</command> + assumes the C name of the function is the same as the SQL name. + </para> - <para> - For dynamically-loaded C functions, the SQL name of the function must - be the same as the C function name, because the AS clause is used to - give the path name of the object file containing the C code. In this - situation it is best not to try to overload SQL function names. It - might work to load a C function that has the same C name as an internal - function or another dynamically-loaded function --- or it might not. - On some platforms the dynamic loader may botch the load in interesting - ways if there is a conflict of C function names. So, even if it works - for you today, you might regret overloading names later when you try - to run the code somewhere else. - </para> + <para> + For dynamically-loaded C functions, the SQL name of the function must + be the same as the C function name, because the AS clause is used to + give the path name of the object file containing the C code. In this + situation it is best not to try to overload SQL function names. It + might work to load a C function that has the same C name as an internal + function or another dynamically-loaded function --- or it might not. + On some platforms the dynamic loader may botch the load in interesting + ways if there is a conflict of C function names. So, even if it works + for you today, you might regret overloading names later when you try + to run the code somewhere else. + </para> + + <para> + A C function cannot return a set of values. + </para> </refsect2> </refsect1> @@ -195,7 +221,7 @@ SELECT one() AS answer; </para> <para> - To create a C function, calling a routine from a user-created + This example creates a C function by calling a routine from a user-created shared library. This particular routine calculates a check digit and returns TRUE if the check digit in the function parameters is correct. It is intended for use in a CHECK contraint. @@ -216,26 +242,27 @@ CREATE TABLE product ( </programlisting> </refsect1> - <refsect1 id="R1-SQL-CREATEFUNCTION-3"> - <title> - Bugs - </title> - <para> - A C function cannot return a set of values. - </para> - </refsect1> - <refsect1 id="R1-SQL-CREATEFUNCTION-4"> <title> Compatibility </title> - <para> - <command>CREATE FUNCTION</command> is - a <productname>Postgres</productname> language extension. - </para> <refsect2 id="R2-SQL-CREATEFUNCTION-4"> <refsect2info> + <date>1998-04-15</date> + </refsect2info> + <title> + SQL92 + </title> + + <para> + <command>CREATE FUNCTION</command> is + a <productname>Postgres</productname> language extension. + </para> + </refsect2> + + <refsect2 id="R2-SQL-CREATEFUNCTION-5"> + <refsect2info> <date>1998-09-09</date> </refsect2info> <title> diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index 860a793c6c2..55608187e67 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEINDEX"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createindex-title"> CREATE INDEX </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,15 +20,13 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-09</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> - ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ] - ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] ) -CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> - ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ] - ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">r">col</replaceable>le> [, ... ]) <replaceable class="parameter">ops_name</replaceable> ) +CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable> + [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] ) +CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable> + [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">r">col</replaceable>le> [, ... ]) <replaceable class="parameter">ops_name</replaceable> ) </synopsis> <refsect2 id="R2-SQL-CREATEINDEX-1"> @@ -48,6 +51,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">index_name</replaceable></term> <listitem> @@ -56,6 +60,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">table</replaceable></term> <listitem> @@ -64,6 +69,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">acc_name</replaceable></term> <listitem> @@ -71,6 +77,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> the name of the access method which is to be used for the index. The default access method is BTREE. Postgres provides three access methods for secondary indexes: + <variablelist> <varlistentry> <term>BTREE</term> @@ -81,6 +88,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term>RTREE</term> <listitem> @@ -89,6 +97,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term>HASH</term> <listitem> @@ -98,7 +107,6 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </listitem> </varlistentry> </variablelist> - </para> </listitem> </varlistentry> @@ -111,27 +119,16 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">ops_name</replaceable></term> <listitem> <para> - An associated operator class. - The following select list returns all ops_names: - - <programlisting> -SELECT am.amname AS acc_name, - opc.opcname AS ops_name, - opr.oprname AS ops_comp - FROM pg_am am, pg_amop amop, - pg_opclass opc, pg_operator opr - WHERE amop.amopid = am.oid AND - amop.amopclaid = opc.oid AND - amop.amopopr = opr.oid - ORDER BY acc_name, ops_name, ops_comp - </programlisting> + An associated operator class. See below for details. </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">func_name</replaceable></term> <listitem> @@ -190,9 +187,8 @@ ERROR: Cannot create index: 'index_name' already exists. </title> <para> <command>CREATE INDEX</command> constructs an index - <replaceable class="parameter">index_name</replaceable>. - on the specified - <replaceable class="parameter">table</replaceable>. + <replaceable class="parameter">index_name</replaceable> + on the specified <replaceable class="parameter">table</replaceable>. <tip> <para> @@ -201,6 +197,7 @@ ERROR: Cannot create index: 'index_name' already exists. </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 @@ -213,16 +210,30 @@ ERROR: Cannot create index: 'index_name' already exists. operator class is the appropriate operator class for that field type. </para> + <para> - In the second syntax, an index is defined + In the second syntax shown above, an index is defined on the result of a user-defined function <replaceable class="parameter">func_name</replaceable> applied - to one or more attributes of a single class. These functional - indexes can be used to obtain fast access to data + to one or more attributes of a single class. + These <firstterm>functional indices</firstterm> + can be used to obtain fast access to data based on operators that would normally require some transformation to apply them to the base data. </para> + <para> + Postgres provides btree, rtree and hash access methods for + secondary indices. The btree access method is an implementation of + the Lehman-Yao high-concurrency btrees. The rtree access method + implements standard rtrees using Guttman's quadratic split algorithm. + The hash access method is an implementation of Litwin's linear + hashing. We mention the algorithms used solely to indicate that all + of these access methods are fully dynamic and do not have to be + optimized periodically (as is the case with, for example, static hash + access methods). + </para> + <refsect2 id="R2-SQL-CREATEINDEX-3"> <refsect2info> <date>1998-09-09</date> @@ -230,14 +241,90 @@ ERROR: Cannot create index: 'index_name' already exists. <title> Notes </title> + + <para> + The Postgres query optimizer will consider using btree indices in a scan + whenever an indexed attribute is involved in a comparison using one of: + + <simplelist type="inline"> + <member><</member> + <member><=</member> + <member>=</member> + <member>>=</member> + <member>></member> + </simplelist> + </para> + + <para> + Both box classes support indices on the <literal>box</literal> data + type in <productname>Postgres</productname>. + The difference between them is that <literal>bigbox_ops</literal> + scales box coordinates down, to avoid floating point exceptions from + doing multiplication, addition, and subtraction on very large + floating-point coordinates. If the field on which your rectangles lie + is about 20,000 units square or larger, you should use + <literal>bigbox_ops</literal>. + The <literal>poly_ops</literal> operator class supports rtree + indices on <literal>polygon</literal> data. + </para> + + <para> + The <productname>Postgres</productname> + query optimizer will consider using an rtree index whenever + an indexed attribute is involved in a comparison using one of: + + <simplelist type="inline"> + <member><<</member> + <member>&<</member> + <member>&></member> + <member>>></member> + <member>@</member> + <member>~=</member> + <member>&&</member> + </simplelist> + </para> + + <para> + The <productname>Postgres</productname> + query optimizer will consider using a hash index whenever + an indexed attribute is involved in a comparison using + the <literal>=</literal> operator. + </para> + <para> Currently, only the BTREE access method supports multi-column indexes. Up to 7 keys may be specified. </para> + <para> - Use <command>DROP INDEX</command> + Use <xref linkend="sql-dropindex-title" endterm="sql-dropindex-title"> to remove an index. </para> + + <para> + The <literal>int24_ops</literal> + operator class is useful for constructing indices on int2 data, and + doing comparisons against int4 data in query qualifications. + Similarly, <literal>int42_ops</literal> + support indices on int4 data that is to be compared against int2 data + in queries. + </para> + + <para> + The following select list returns all ops_names: + + <programlisting> +SELECT am.amname AS acc_name, + opc.opcname AS ops_name, + opr.oprname AS ops_comp + FROM pg_am am, pg_amop amop, + pg_opclass opc, pg_operator opr + WHERE amop.amopid = am.oid AND + amop.amopclaid = opc.oid AND + amop.amopopr = opr.oid + ORDER BY acc_name, ops_name, ops_comp + </programlisting> + </para> </refsect2> </refsect1> @@ -276,8 +363,6 @@ SELECT * FROM points <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CREATEINDEX-4"> <refsect2info> diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 0089ee90ca5..7cdb4038256 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.8 1999/07/22 15:09:07 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATELANGUAGE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createlanguage-title"> CREATE LANGUAGE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-09</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname</replaceable>' @@ -59,7 +64,8 @@ CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname< <productname>Postgres</productname>. </para> </listitem> - </varlistentry> + </varlistentry> + <varlistentry> <term>HANDLER <replaceable class="parameter">call_handler</replaceable></term> <listitem> @@ -71,6 +77,7 @@ CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname< </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">comment</replaceable></term> <listitem> @@ -242,32 +249,22 @@ C |/bin/cc sql |postgres </computeroutput> </programlisting> + </para> + <para> + Since the call handler for a procedural language must be + registered with <productname>Postgres</productname> in the 'C' language, + it inherits + all the capabilities and restrictions of 'C' functions. + </para> + + <para> + At present, the definitions for a procedural language cannot be + changed once they have been created. </para> </refsect2> </refsect1> - <refsect1 id="R1-SQL-CREATELANGUAGE-4"> - <title> - Restrictions - </title> - <para> - Since the call handler for a procedural language must be - registered with <productname>Postgres</productname> in the 'C' language, - it inherits - all the capabilities and restrictions of 'C' functions. - </para> - </refsect1> - <refsect1 id="R1-SQL-CREATELANGUAGE-5"> - <title> - Bugs - </title> - <para> - At present, the definitions for a procedural language cannot be - changed once they have been created. - </para> - </refsect1> - <refsect1 id="R1-SQL-CREATELANGUAGE-6"> <title> Usage @@ -340,9 +337,6 @@ CREATE PROCEDURAL LANGUAGE 'plsample' <title> Compatibility </title> - <para> - CREATE LANGUAGE is a <productname>Postgres</productname> extension. - </para> <refsect2 id="R2-SQL-CREATELANGUAGE-5"> <refsect2info> @@ -351,7 +345,10 @@ CREATE PROCEDURAL LANGUAGE 'plsample' <title> SQL92 </title> + <para> + <command>CREATE LANGUAGE</command> + is a <productname>Postgres</productname> extension. There is no <command>CREATE LANGUAGE</command> statement in <acronym>SQL92</acronym>. </para> diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index b6bb748ce25..7f06c4cece3 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.11 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEOPERATOR"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createoperator-title"> CREATE OPERATOR </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,21 +20,14 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1999-04-14</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE OPERATOR <replaceable>name</replaceable> ( - PROCEDURE = <replaceable class="parameter">func_name</replaceable> - [, LEFTARG = <replaceable class="parameter">type1</replaceable> ] - [, RIGHTARG = <replaceable class="parameter">type2</replaceable> ] - [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] - [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ] - [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] - [, JOIN = <replaceable class="parameter">join_proc</replaceable> ] - [, HASHES ] - [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] - [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ] - ) +CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class="parameter">func_name</replaceable> + [, LEFTARG = <replaceable class="parameter">type1</replaceable> ] [, RIGHTARG = <replaceable class="parameter">type2</replaceable> ] + [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ] + [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ] + [, HASHES ] [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ] ) </synopsis> <refsect2 id="R2-SQL-CREATEOPERATOR-1"> @@ -384,9 +382,6 @@ CREATE OPERATOR === ( <title> Compatibility </title> - <para> - CREATE OPERATOR is a <productname>Postgres</productname> extension. - </para> <refsect2 id="R2-SQL-CREATEOPERATOR-4"> <refsect2info> @@ -395,8 +390,12 @@ CREATE OPERATOR === ( <title> SQL92 </title> + <para> - There is no CREATE OPERATOR statement in <acronym>SQL92</acronym>. + <command>CREATE OPERATOR</command> + is a <productname>Postgres</productname> extension. + There is no <command>CREATE OPERATOR</command> + statement in <acronym>SQL92</acronym>. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/create_rule.sgml b/doc/src/sgml/ref/create_rule.sgml index 829f584d5f3..e81de58afdb 100644 --- a/doc/src/sgml/ref/create_rule.sgml +++ b/doc/src/sgml/ref/create_rule.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.10 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATERULE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createrule-title"> CREATE RULE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-11</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable> @@ -117,6 +122,15 @@ CREATE <title> Description </title> + + <para> + The <productname>Postgres</productname> + <firstterm>rule system</firstterm> allows one to define an + alternate action to be performed on updates, inserts, or deletions + from database tables or classes. Currently, rules are used to + implement table views. + </para> + <para> The semantics of a rule is that at the time an individual instance is accessed, updated, inserted or deleted, there is a current instance (for @@ -131,6 +145,7 @@ CREATE <literal>current.</literal><replaceable class="parameter">attribute-name</replaceable> and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>. </para> + <para> The <replaceable class="parameter">action</replaceable> part of the rule executes with the same command and transaction identifier as the user @@ -209,13 +224,32 @@ CREATE RULE bad_rule_combination_2 AS SELECT * FROM emp; </programlisting></para> </example> - </para> + <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. </para> + + <para> + The object in a <acronym>SQL</acronym> rule cannot be an array reference and + cannot have parameters. + </para> + + <para> + Aside from the "oid" field, system attributes cannot be + referenced anywhere in a rule. Among other things, this + means that functions of instances (e.g., <literal>foo(emp)</literal> where + <literal>emp</literal> is a class) cannot be called anywhere in a rule. + </para> + + <para> + The rule system stores the rule text and query plans as + text attributes. This implies that creation of rules may + fail if the rule plus its various internal representations + exceed some value that is on the order of one page (8KB). + </para> </refsect2> </refsect1> @@ -284,36 +318,10 @@ CREATE RULE example_5 AS </para> </refsect1> - <refsect1 id="R1-SQL-CREATERULE-3"> - <title> - Bugs - </title> - <para> - The object in a <acronym>SQL</acronym> rule cannot be an array reference and - cannot have parameters. - </para> - <para> - Aside from the "oid" field, system attributes cannot be - referenced anywhere in a rule. Among other things, this - means that functions of instances (e.g., "<literal>foo(emp)</literal>" where - "<literal>emp</literal>" is a class) cannot be called anywhere in a rule. - </para> - <para> - The rule system stores the rule text and query plans as - text attributes. This implies that creation of rules may - 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> Compatibility </title> - <para> - <command>CREATE RULE</command> statement is a <productname>Postgres</productname> - language extension. - </para> <refsect2 id="R2-SQL-CREATERULE-4"> <refsect2info> @@ -322,7 +330,10 @@ CREATE RULE example_5 AS <title> SQL92 </title> + <para> + <command>CREATE RULE</command> statement is a <productname>Postgres</productname> + language extension. There is no <command>CREATE RULE</command> statement in <acronym>SQL92</acronym>. </para> </refsect2> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 352c839f917..6f802346fdd 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.11 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATESEQUENCE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createsequence-title"> CREATE SEQUENCE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,16 +20,12 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> - [ INCREMENT <replaceable class="parameter">increment</replaceable> ] - [ MINVALUE <replaceable class="parameter">minvalue</replaceable> ] - [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> ] - [ START <replaceable class="parameter">start</replaceable> ] - [ CACHE <replaceable class="parameter">cache</replaceable> ] - [ CYCLE ] +CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT <replaceable class="parameter">increment</replaceable> ] + [ MINVALUE <replaceable class="parameter">minvalue</replaceable> ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> ] + [ START <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ CYCLE ] </synopsis> <refsect2 id="R2-SQL-CREATESEQUENCE-1"> @@ -45,6 +46,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">increment</replaceable></term> <listitem> @@ -57,6 +59,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">minvalue</replaceable></term> <listitem> @@ -69,6 +72,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">maxvalue</replaceable></term> <listitem> @@ -81,6 +85,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">start</replaceable></term> <listitem> @@ -96,6 +101,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">cache</replaceable></term> <listitem> @@ -108,6 +114,7 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> </para> </listitem> </varlistentry> + <varlistentry> <term>CYCLE</term> <listitem> @@ -208,6 +215,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl table with the name <replaceable class="parameter">seqname</replaceable>. The generator will be "owned" by the user issuing the command. </para> + <para> After a sequence is created, you may use the function <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function> @@ -228,18 +236,24 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl <para> Use a query like + <programlisting> SELECT * FROM sequence_name; </programlisting> + to get the parameters of a sequence. + Aside from fetching the original parameters, you can use + <programlisting> SELECT last_value FROM sequence_name; </programlisting> + to obtain the last value allocated by any backend. parameters, you can use </para> + <para> Low-level locking is used to enable multiple simultaneous calls to a generator. @@ -332,10 +346,6 @@ END; <title> Compatibility </title> - <para> - <command>CREATE SEQUENCE</command> is a <productname>Postgres</productname> - language extension. - </para> <refsect2 id="R2-SQL-CREATESEQUENCE-4"> <refsect2info> @@ -344,7 +354,10 @@ END; <title> SQL92 </title> + <para> + <command>CREATE SEQUENCE</command> is a <productname>Postgres</productname> + language extension. There is no <command>CREATE SEQUENCE</command> statement in <acronym>SQL92</acronym>. </para> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 9e0732d7297..9a25bc1b5ee 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.17 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATETABLE"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-createtable-title"> CREATE TABLE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-11</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replaceable> ( @@ -56,7 +61,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replacea <term><replaceable class="PARAMETER">table</replaceable></term> <listitem> <para> - The name of a new table to be created. + The name of a new class or table to be created. </para> </listitem> </varlistentry> @@ -213,11 +218,49 @@ ERROR: DEFAULT: type mismatched <title> Description </title> + <para> - <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>CREATE TABLE</command> will enter a new class or table + into the current data base. The table will be "owned" by the user issuing the command. </para> + + <para> + Each <replaceable class="PARAMETER">type</replaceable> + may be a simple type, a complex type (set) or an array type. + Each attribute may be specified to be non-null and + each may have a default value, specified by the + <xref linkend="R1-SQL-DEFAULTCLAUSE-1-TITLE" endterm="R1-SQL-DEFAULTCLAUSE-1-TITLE">. + </para> + + <para> + <note> + <para> + As of Postgres version 6.0, consistant array dimensions within an + attribute are not enforced. This will likely change in a future + release. + </para> + </note> + </para> + + <para> + The optional INHERITS + clause specifies a collection of class names from which this class + automatically inherits all fields. If any inherited field name + appears more than once, Postgres reports an error. Postgres automatically + allows the created class to inherit functions on classes above it in + the inheritance hierarchy. Inheritance of functions is done according + to the conventions of the Common Lisp Object System (CLOS). + </para> + + <para> + Each new table or class <replaceable class="PARAMETER">table</replaceable> + is automatically created as a type. Therefore, one or more instances + from the class are automatically a type and can be used in + <xref linkend="sql-altertable-title" endterm="sql-altertable-title"> + or other <command>CREATE TABLE</command> statements. + </para> + <para> The new table is created as a heap with no initial data. A table can have no more than 1600 columns (realistically, @@ -232,7 +275,7 @@ ERROR: DEFAULT: type mismatched <refsect1info> <date>1998-09-11</date> </refsect1info> - <title> + <title id="R1-SQL-DEFAULTCLAUSE-1-TITLE"> DEFAULT Clause </title> <para> @@ -427,7 +470,7 @@ CREATE TABLE distributors ( <refsect1info> <date>1998-09-11</date> </refsect1info> - <title> + <title id="R1-SQL-COLUMNCONSTRAINT-1-TITLE"> Column CONSTRAINT Clause </title> <para> @@ -446,6 +489,7 @@ CREATE TABLE distributors ( Inputs </title> <para> + <variablelist> <varlistentry> <term><replaceable class="parameter">name</replaceable></term> @@ -523,20 +567,34 @@ CREATE TABLE distributors ( <title> Description </title> + + <para> + The optional constraint + clauses specify constraints or tests which new or updated entries + must satisfy for an insert or update operation to succeed. Each constraint + must evaluate to a boolean expression. Multiple attributes may be referenced within + a single constraint. The use of PRIMARY KEY + as a table constraint + is mutually incompatible with PRIMARY KEY as a column constraint. + </para> + <para> - A Constraint is a named rule: an SQL object which helps define + A constraint is a named rule: an SQL object which helps define valid sets of values by putting limits on the results of INSERT, UPDATE or DELETE operations performed on a Base Table. </para> + <para> There are two ways to define integrity constraints: table constraints, covered later, and column constraints, covered here. </para> + <para> A column constraint is an integrity constraint defined as part of a column definition, and logically becomes a table constraint as soon as it is created. The column constraints available are: + <simplelist columns="1"> <member>PRIMARY KEY</member> <member>REFERENCES</member> diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 27ce6df645d..9ecac6b02b2 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -1,6 +1,11 @@ -<refentry id="CREATETABLEAS"> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.3 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + +<refentry id="SQL-CREATETABLEAS"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-CREATETABLEAS-TITLE"> CREATE TABLE AS </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE TABLE <replaceable>table</replaceable> [ (<replaceable>column</replaceable> [, ...] ) ] @@ -87,8 +92,10 @@ CREATE TABLE <replaceable>table</replaceable> [ (<replaceable>column</replaceabl Description </title> <para> - <command>CREATE TABLE AS</command> enables a table to be created from the contents of - an existing table. It has functionality equivalent to <command>SELECT TABLE INTO</command>, + <command>CREATE TABLE AS</command> enables a table to be created + from the contents of an existing table. + It is functionality equivalent to + <xref linkend="sql-selectinto-title" endterm="sql-selectinto-title">, but with perhaps a more direct syntax. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 32952a29ce6..da116628cc0 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.8 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATETRIGGER"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-CREATETRIGGER-TITLE"> CREATE TRIGGER </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-21</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER } { <replaceable class="PARAMETER">event</replaceable> [OR ...] } @@ -101,29 +106,37 @@ CREATE <title> Description </title> + <para> <command>CREATE TRIGGER</command> will enter a new trigger into the current data base. The trigger will be associated with the relation <replaceable class="parameter">relname</replaceable> and will execute the specified function <replaceable class="parameter">funcname</replaceable>. </para> + <para> - The trigger can be specified to fire either before the + The trigger can be specified to fire either before BEFORE the operation is attempted on a tuple (before constraints - are checked and the INSERT, UPDATE or DELETE is attempted) or - after the operation has been attempted (e.g. after constraints - are checked and the INSERT, UPDATE or DELETE has completed). If the + are checked and the <command>INSERT</command>, <command>UPDATE</command> or + <command>DELETE</command> is attempted) or + AFTER the operation has been attempted (e.g. after constraints + are checked and the <command>INSERT</command>, + <command>UPDATE</command> or <command>DELETE</command> has + completed). If the trigger fires before the event, the trigger may skip the operation for the current tuple, or change the tuple - being inserted (for INSERT and UPDATE operations only). If + being inserted (for <command>INSERT</command> and + <command>UPDATE</command> operations only). If the trigger fires after the event, all changes, including the last insertion, update, or deletion, are "visible" to the trigger. </para> + <para> Refer to the chapters on SPI and Triggers in the -<citetitle>PostgreSQL Programmer's Guide</citetitle> for more + <citetitle>PostgreSQL Programmer's Guide</citetitle> for more information. </para> + <refsect2 id="R2-SQL-CREATETRIGGER-3"> <refsect2info> <date>1998-09-21</date> @@ -133,7 +146,7 @@ CREATE </title> <para> <command>CREATE TRIGGER</command> is a <productname>Postgres</productname> - language extension. + language extension. </para> <para> Only the relation owner may create a trigger on this relation. @@ -177,8 +190,6 @@ CREATE TRIGGER if_film_exists <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CREATETRIGGER-4"> <refsect2info> @@ -187,6 +198,7 @@ CREATE TRIGGER if_film_exists <title> SQL92 </title> + <para> There is no <command>CREATE TRIGGER</command> in <acronym>SQL92</acronym>. </para> @@ -207,7 +219,7 @@ CREATE TABLE distributors ( </para> <para> - However, foreign keys are not yet implemented (as of version 6.4) in + However, foreign keys are not yet implemented (as of version 6.5) in <productname>Postgres</productname>. </para> </refsect2> diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 93f77c188ae..91a8b7d15da 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.10 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATETYPE"> <refmeta> <refentrytitle> @@ -15,21 +20,15 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-21</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE TYPE <replaceable class="parameter">typename</replaceable> ( - INPUT = <replaceable class="parameter">input_function</replaceable> - , OUTPUT = <replaceable class="parameter">output_function</replaceable> - , INTERNALLENGTH = (<replaceable class="parameter">internallength</replaceable> | VARIABLE) - [ , EXTERNALLENGTH = (<replaceable class="parameter">externallength</replaceable> | VARIABLE) ] - [ , ELEMENT = <replaceable class="parameter">element</replaceable> ] - [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ] - [ , DEFAULT = "<replaceable class="parameter">default</replaceable>" ] - [ , SEND = <replaceable class="parameter">send_function</replaceable> ] - [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ] - [ , PASSEDBYVALUE ] -) +CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable> + , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } [ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ] + [ , DEFAULT = "<replaceable class="parameter">default</replaceable>" ] + [ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ] + [ , SEND = <replaceable class="parameter">send_function</replaceable> ] [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ] + [ , PASSEDBYVALUE ] ) </synopsis> <refsect2 id="R2-SQL-CREATETYPE-1"> @@ -50,8 +49,9 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> - <term>INTERNALLENGTH <replaceable class="parameter">internallength</replaceable></term> + <term><replaceable class="parameter">internallength</replaceable></term> <listitem> <para> A literal value, which specifies the internal length of @@ -59,8 +59,9 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> - <term>EXTERNALLENGTH <replaceable class="parameter">externallength</replaceable></term> + <term><replaceable class="parameter">externallength</replaceable></term> <listitem> <para> A literal value, which specifies the external length of @@ -68,18 +69,21 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> - <term>INPUT <replaceable class="parameter">input_function</replaceable></term> + <term><replaceable class="parameter">input_function</replaceable></term> <listitem> <para> - The name of a function, created by CREATE FUNCTION, which + The name of a function, created by + <command>CREATE FUNCTION</command>, which converts data from its external form to the type's internal form. </para> </listitem> </varlistentry> + <varlistentry> - <term>OUTPUT <replaceable class="parameter">output_function</replaceable></term> + <term><replaceable class="parameter">output_function</replaceable></term> <listitem> <para> The name of a function, created by CREATE FUNCTION, which @@ -88,6 +92,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">element</replaceable></term> <listitem> @@ -97,6 +102,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">delimiter</replaceable></term> <listitem> @@ -105,6 +111,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( </para> </listitem> </varlistentry> + <varlistentry> <term><replaceable class="parameter">default</replaceable></term> <listitem> @@ -118,10 +125,9 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( <term><replaceable class="parameter">send_function</replaceable></term> <listitem> <para> - The name of a function, created by CREATE FUNCTION, which + The name of a function, created by <command>CREATE FUNCTION</command>, which converts data of this type into a form suitable for transmission to another machine. - <comment>Is this right?</comment> </para> </listitem> </varlistentry> @@ -129,10 +135,9 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( <term><replaceable class="parameter">receive_function</replaceable></term> <listitem> <para> - The name of a function, created by CREATE FUNCTION, which + The name of a function, created by <command>CREATE FUNCTION</command>, which converts data of this type from a form suitable for transmission from another machine to internal form. - <comment>Is this right?</comment> </para> </listitem> </varlistentry> @@ -172,6 +177,7 @@ CREATE <title> Description </title> + <para> <command>CREATE TYPE</command> allows the user to register a new user data type with Postgres for use in the current data base. The @@ -180,6 +186,7 @@ CREATE the name of the new type and must be unique within the types defined for this database. </para> + <para> <command>CREATE TYPE</command> requires the registration of two functions (using create function) before defining the type. The @@ -193,6 +200,7 @@ CREATE the input and output functions must be declared to take one or two arguments of type "<literal>opaque</literal>". </para> + <para> New base data types can be fixed length, in which case <replaceable class="parameter">internallength</replaceable> is a @@ -207,6 +215,7 @@ CREATE <replaceable class="parameter">externallength</replaceable> keyword. </para> + <para> To indicate that a type is an array and to indicate that a type has array elements, indicate the type of the array @@ -214,6 +223,7 @@ CREATE an array of 4 byte integers ("int4"), specify <programlisting>ELEMENT = int4</programlisting> </para> + <para> To indicate the delimiter to be used on arrays of this type, <replaceable class="parameter">delimiter</replaceable> @@ -221,6 +231,7 @@ CREATE set to a specific character. The default delimiter is the comma ("<literal>,</literal>"). </para> + <para> A default value is optionally available in case a user wants some specific bit pattern to mean "data not present." @@ -228,8 +239,9 @@ CREATE <comment>How does the user specify that bit pattern and associate it with the fact that the data is not present></comment> </para> + <para> - The optional functions + The optional arguments <replaceable class="parameter">send_function</replaceable> and <replaceable class="parameter">receive_function</replaceable> are used when the application program requesting Postgres @@ -246,6 +258,7 @@ CREATE characters do not have to be converted if passed from a Sun-4 to a DECstation, but many other types do. </para> + <para> The optional flag, <option>PASSEDBYVALUE</option>, indicates that operators and functions which use this data type should be passed an @@ -253,6 +266,7 @@ CREATE may not pass by value types whose internal representation is more than four bytes. </para> + <para> For new base types, a user can define operators, functions and aggregates using the appropriate facilities described @@ -287,15 +301,16 @@ CREATE <para> This command creates the box data type and then uses the type in a class definition: - </para> - <programlisting> + <programlisting> CREATE TYPE box (INTERNALLENGTH = 8, INPUT = my_procedure_1, OUTPUT = my_procedure_2); CREATE TABLE myboxes (id INT4, description box); - </programlisting> + </programlisting> + </para> + <para> This command creates a variable length array type with - integer elements. + integer elements: <programlisting> CREATE TYPE int4array (INPUT = array_in, OUTPUT = array_out, @@ -303,6 +318,7 @@ CREATE TYPE int4array (INPUT = array_in, OUTPUT = array_out, CREATE TABLE myarrays (id int4, numbers int4array); </programlisting> </para> + <para> This command creates a large object type and uses it in a class definition: @@ -314,8 +330,14 @@ CREATE TABLE big_objs (id int4, obj bigobj); </programlisting> </para> - <refsect2> - <title>Restrictions</title> + <refsect2 id="R2-SQL-CREATETYPE-3"> + <refsect2info> + <date>1998-09-21</date> + </refsect2info> + <title> + Notes + </title> + <para> Type names cannot begin with the underscore character ("_") and can only be 31 characters long. This is because @@ -323,15 +345,7 @@ CREATE TABLE big_objs (id int4, obj bigobj); with a name consisting of the base type's name prepended with an underscore. </para> - </refsect2> - <refsect2 id="R2-SQL-CREATETYPE-3"> - <refsect2info> - <date>1998-09-21</date> - </refsect2info> - <title> - Notes - </title> <para> Refer to <command>DROP TYPE</command> to remove an existing type. </para> diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index 73849962a06..2fb2c24eb11 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.8 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEUSER"> <refmeta> <refentrytitle> @@ -15,13 +20,12 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-21</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> CREATE USER<replaceable class="PARAMETER"> username</replaceable> [ WITH PASSWORD <replaceable class="PARAMETER">password</replaceable> ] - [ CREATEDB | NOCREATEDB ] - [ CREATEUSER | NOCREATEUSER ] + [ CREATEDB | NOCREATEDB ] [ CREATEUSER | NOCREATEUSER ] [ IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ] [ VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' ] </synopsis> @@ -34,6 +38,7 @@ CREATE USER<replaceable class="PARAMETER"> username</replaceable> Inputs </title> <para> + <variablelist> <varlistentry> <term><replaceable class="parameter">username</replaceable></term> @@ -170,6 +175,7 @@ CREATE USER CREATE USER will add a new user to an instance of <productname>Postgres</productname>. </para> + <para> The new user will be given a <filename>usesysid</filename> of: @@ -270,8 +276,6 @@ CREATE USER manuel WITH PASSWORD jw8s0F4 CREATEDB <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CREATEUSER-4"> <refsect2info> @@ -280,6 +284,7 @@ CREATE USER manuel WITH PASSWORD jw8s0F4 CREATEDB <title> SQL92 </title> + <para> There is no <command>CREATE USER</command> statement in SQL92. </para> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 5a0048f0d92..dbfdc5261a2 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.7 1999/07/22 15:09:08 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-CREATEVIEW"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-CREATEVIEW-TITLE"> CREATE VIEW </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,11 +20,10 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-21</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> -CREATE VIEW <replaceable class="PARAMETER">view</replaceable> - AS SELECT <replaceable class="PARAMETER">query</replaceable> +CREATE VIEW <replaceable class="PARAMETER">view</replaceable> AS SELECT <replaceable class="PARAMETER">query</replaceable> </synopsis> <refsect2 id="R2-SQL-CREATEVIEW-1"> @@ -30,6 +34,7 @@ CREATE VIEW <replaceable class="PARAMETER">view</replaceable> Inputs </title> <para> + <variablelist> <varlistentry> <term><replaceable class="parameter">view</replaceable></term> @@ -116,10 +121,10 @@ CREATE VIEW vista AS SELECT 'Hello World'::text Description </title> <para> - <command>CREATE VIEW</command> will define a view of a table. This view is - not physically materialized. Specifically, a query - rewrite retrieve rule is automatically generated - to support retrieve operations on views. + <command>CREATE VIEW</command> will define a view of a table or + class. This view is not physically materialized. Specifically, a query + rewrite retrieve rule is automatically generated to support + retrieve operations on views. </para> <refsect2 id="R2-SQL-CREATEVIEW-3"> @@ -129,20 +134,13 @@ CREATE VIEW vista AS SELECT 'Hello World'::text <title> Notes </title> + <para> - Use the <command>DROP VIEW</command> statement to drop views. + Currently, views are read only. </para> - </refsect2> - <refsect2 id="R2-SQL-CREATEVIEW-4"> - <refsect2info> - <date>1998-09-21</date> - </refsect2info> - <title> - Bugs - </title> <para> - Currently, views are read only. + Use the <command>DROP VIEW</command> statement to drop views. </para> </refsect2> </refsect1> @@ -174,8 +172,6 @@ C_701|There's a Girl in my Soup|107|1970-06-11|Comedy | 01:36 <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-CREATEVIEW-5"> <refsect2info> @@ -210,6 +206,7 @@ CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable cla </para> </listitem> </varlistentry> + <varlistentry> <term>LOCAL</term> <listitem> @@ -218,6 +215,7 @@ CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable cla </para> </listitem> </varlistentry> + <varlistentry> <term>CASCADE</term> <listitem> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index f9c8e21101c..906e2dbf6e4 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.5 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-CREATEDB"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-CREATEDB-TITLE"> <application>createdb</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> createdb [ <replaceable class="parameter">dbname</replaceable> ] @@ -224,8 +229,7 @@ createdb: database creation failed on <replaceable class="parameter">dbname</rep <envar>PGREALM</envar> environment variables will be passed on to <application>psql</application> - and processed as described in <xref endterm="psql-ref" - linkend="app-psql">. + and processed as described in <xref endterm="app-psql-title" linkend="app-psql-title">. </para> </refsect1> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index 0207b4f9227..b6302506a18 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.5 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-CREATEUSER"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-CREATEUSER-TITLE"> <application>createuser</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> createuser [ <replaceable class="parameter">username</replaceable> ] @@ -246,7 +251,8 @@ database access failed <envar>PGREALM</envar> environment variables will be passed on to <application>psql</application> - and processed as described in <xref endterm="psql-ref" linkend="app-psql">. + and processed as described in + <xref endterm="app-psql-title" linkend="app-psql-title">. </para> <para> diff --git a/doc/src/sgml/ref/current_date.sgml b/doc/src/sgml/ref/current_date.sgml index 7d0e1ec8817..b1aa4604d4d 100644 --- a/doc/src/sgml/ref/current_date.sgml +++ b/doc/src/sgml/ref/current_date.sgml @@ -1,3 +1,13 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.4 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.4 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <REFENTRY ID="SQL-CURRENT-DATE"> <REFMETA> <REFENTRYTITLE> diff --git a/doc/src/sgml/ref/current_time.sgml b/doc/src/sgml/ref/current_time.sgml index be03cc0bcda..617b3dba911 100644 --- a/doc/src/sgml/ref/current_time.sgml +++ b/doc/src/sgml/ref/current_time.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_time.sgml,v 1.4 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <REFENTRY ID="SQL-CURRENT-TIME"> <REFMETA> <REFENTRYTITLE> diff --git a/doc/src/sgml/ref/current_timestamp.sgml b/doc/src/sgml/ref/current_timestamp.sgml index 35a84807c10..23438218022 100644 --- a/doc/src/sgml/ref/current_timestamp.sgml +++ b/doc/src/sgml/ref/current_timestamp.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_timestamp.sgml,v 1.4 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <REFENTRY ID="SQL-CURRENT-TIMESTAMP"> <REFMETA> <REFENTRYTITLE> diff --git a/doc/src/sgml/ref/current_user.sgml b/doc/src/sgml/ref/current_user.sgml index a70d7682b27..62a44986b33 100644 --- a/doc/src/sgml/ref/current_user.sgml +++ b/doc/src/sgml/ref/current_user.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_user.sgml,v 1.4 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <REFENTRY ID="SQL-CURRENT-USER"> <REFMETA> <REFENTRYTITLE> diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index dab2d855423..26cd9da61ba 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.7 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DECLARE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DECLARE-TITLE"> DECLARE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-04</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DECLARE <replaceable class="parameter">cursor</replaceable> [ BINARY ] [ INSENSITIVE ] [ SCROLL ] @@ -181,27 +186,25 @@ ERROR: Named portals may only be used in begin/end transaction blocks Description </title> <para> - <command>DECLARE</command> allows a user to create cursors, which can be used to retrieve - a small number of rows at a time out of a larger query. Cursors can return - data either in text or in binary foramt. + <command>DECLARE</command> allows a user to create cursors, which + can be used to retrieve + a small number of rows at a time out of a larger query. Cursors can + return data either in text or in binary format using + <xref linkend="sql-fetch-title" endterm="sql-fetch-title">. </para> <para> - Normal cursors return data in text format, either ASCII or another + Normal cursors return data in text format, either ASCII or another encoding scheme depending on how the <productname>Postgres</productname> backend was built. Since data is stored natively in binary format, the system must do a conversion to produce the text format. In addition, text formats are often larger in size than the corresponding binary format. Once the information comes back in text form, the client - application may have to convert it to a binary format to - manipulate it anyway. - </para> - - <para> + application may need to convert it to a binary format to + manipulate it. 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. + representation. </para> <para> @@ -209,23 +212,26 @@ ERROR: Named portals may only be used in begin/end transaction blocks 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'). + </para> - <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> + 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> <para> - However, string representation is architecture-neutral whereas binary - representation can differ between different machine architectures. + String representation is architecture-neutral whereas binary + representation can differ between different machine architectures + and <emphasis><productname>Postgres</productname> does not resolve + byte ordering or representation issues for binary cursors</emphasis>. Therefore, if your client machine and server machine use different representations (e.g. "big-endian" versus "little-endian"), you will probably not want your data returned in binary format. + However, binary cursors may be a + little more efficient since there is less conversion overhead in + the server to client data transfer. <tip> <para> @@ -243,23 +249,26 @@ ERROR: Named portals may only be used in begin/end transaction blocks <title> Notes </title> + <para> - Cursors are only available in transactions. + Cursors are only available in transactions. Use to + <xref linkend="sql-begin-title" endterm="sql-begin-title">, + <xref linkend="sql-commit-title" endterm="sql-commit-title"> + and + <xref linkend="sql-rollback-title" endterm="sql-rollback-title"> + to define a transaction block. </para> + <para> - <productname>Postgres</productname> - does not have an explicit <command>OPEN cursor</command> + In <acronym>SQL92</acronym> cursors are only available in + embedded <acronym>SQL</acronym> (<acronym>ESQL</acronym>) applications. + The <productname>Postgres</productname> backend + does not implement 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. - </para> - </note> + However, <application>ecpg</application>, the + embedded SQL preprocessor for <productname>Postgres</productname>, + supports the <acronym>SQL92</acronym> cursor conventions, including those + involving DECLARE and OPEN statements. </para> </refsect2> </refsect1> @@ -282,8 +291,6 @@ DECLARE liahona CURSOR <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DECLARESTATEMENT-4"> <refsect2info> diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 38a7cd81119..230a8b687f1 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.7 1999/07/22 15:09:09 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DELETE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DELETE-TITLE"> DELETE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -16,7 +21,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DELETE FROM <replaceable class="PARAMETER">table</replaceable> [ WHERE <replaceable class="PARAMETER">condition</replaceable> ] @@ -93,15 +98,18 @@ DELETE <replaceable class="parameter">count</replaceable> <title> Description </title> + <para> <command>DELETE</command> removes rows which satisfy the WHERE clause from the specified table. </para> + <para> If the <firstterm>condition</firstterm> (WHERE clause) is absent, the effect is to delete all rows in the table. The result is a valid, but empty table. </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 @@ -119,12 +127,14 @@ DELETE <replaceable class="parameter">count</replaceable> DELETE FROM films WHERE kind <> 'Musical'; SELECT * FROM films; + <computeroutput> code |title |did| date_prod|kind |len -----+-------------------------+---+----------+----------+------ UA501|West Side Story |105|1961-01-03|Musical | 02:32 TC901|The King and I |109|1956-08-11|Musical | 02:13 WD101|Bed Knobs and Broomsticks|111| |Musical | 01:57 (3 rows) + </computeroutput> </programlisting> </para> @@ -134,9 +144,11 @@ WD101|Bed Knobs and Broomsticks|111| |Musical | 01:57 DELETE FROM films; SELECT * FROM films; + <computeroutput> code|title|did|date_prod|kind|len ----+-----+---+---------+----+--- (0 rows) + </computeroutput> </programlisting> </para> </refsect1> @@ -145,8 +157,6 @@ code|title|did|date_prod|kind|len <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DELETE-4"> <refsect2info> diff --git a/doc/src/sgml/ref/destroydb.sgml b/doc/src/sgml/ref/destroydb.sgml index 8cfd13d534b..dab739c54f5 100644 --- a/doc/src/sgml/ref/destroydb.sgml +++ b/doc/src/sgml/ref/destroydb.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/destroydb.sgml,v 1.5 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-DESTROYDB"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-DESTROYDB-TITLE"> <application>destroydb</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> destroydb [ <replaceable class="parameter">dbname</replaceable> ] @@ -230,8 +235,7 @@ destroydb: database destroy failed on <replaceable class="parameter">dbname</rep <envar>PGREALM</envar> environment variables will be passed on to <application>psql</application> - and processed as described in <xref endterm="psql-ref" - linkend="app-psql">. + and processed as described in <xref endterm="app-psql-title" linkend="app-psql-title">. </para> </refsect1> diff --git a/doc/src/sgml/ref/destroyuser.sgml b/doc/src/sgml/ref/destroyuser.sgml index 697e4cc0cfa..f500da36ee6 100644 --- a/doc/src/sgml/ref/destroyuser.sgml +++ b/doc/src/sgml/ref/destroyuser.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/destroyuser.sgml,v 1.5 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-DESTROYUSER"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-DESTROYUSER-TITLE"> <application>destroyuser</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> destroyuser [ <replaceable class="parameter">username</replaceable> ] @@ -225,9 +230,9 @@ delete of user <replaceable class="parameter">username</replaceable> was UNSUCCE <envar>PGREALM</envar> environment variables will be passed on to <application>psql</application> - and processed as described in <xref endterm="psql-ref" - linkend="app-psql">. + and processed as described in <xref endterm="app-psql-title" linkend="app-psql-title">. </para> + <para> Once invoked, <application>destroyuser</application> will warn you about the databases that will be destroyed in the diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index 3bdf67037f2..5d091b8c99b 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.6 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPAGGREGATE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPAGGREGATE-TITLE"> DROP AGGREGATE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP AGGREGATE <replaceable class="PARAMETER">name</replaceable> <replaceable class="PARAMETER">type</replaceable> @@ -109,14 +114,11 @@ WARN RemoveAggregate: aggregate '<replaceable class="parameter">agg</replaceable <title> Notes </title> + <para> - The <command>DROP AGGREGATE</command> statement is a - <productname>Postgres</productname> - language extension. - </para> - <para> - Refer to the <command>CREATE AGGREGATE</command> statement to - create aggregate functions. + Use + <xref linkend="sql-createaggregate-title" endterm="sql-createaggregate-title"> + to create aggregate functions. </para> </refsect2> </refsect1> @@ -138,8 +140,6 @@ DROP AGGREGATE myavg int4; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPAGGREGATE-4"> <refsect2info> @@ -148,8 +148,12 @@ DROP AGGREGATE myavg int4; <title> SQL92 </title> + <para> - There is no DROP AGGREGATE statement in <acronym>SQL92</acronym>. + There is no <command>DROP AGGREGATE</command> statement + in <acronym>SQL92</acronym>; the statement is a + <productname>Postgres</productname> + language extension. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index d53d83efe67..a60cd7f5f69 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.6 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPDATABASE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPDATABASE-TITLE"> DROP DATABASE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP DATABASE <replaceable class="PARAMETER">name</replaceable> @@ -110,21 +115,17 @@ WARN: destroydb: database "<replaceable class="parameter">name</replaceable>" do </title> <para> - <command>DROP DATABASE</command> statement is a <productname>Postgres</productname> - language extension. - - <tip> - <para> - This query cannot be executed while connected to the target - database. It is usually preferable to use the - <command>destroydb</command> script instead. - </para> - </tip> + This query cannot be executed while connected to the target + database. It is usually preferable to use + <xref linkend="app-destroydb-title" endterm="app-destroydb-title"> + instead. </para> <para> - Refer to the <command>CREATE DATABASE</command> statement for - information on how to create a database. + Refer to + <xref linkend="app-createdb-title" endterm="app-createdb-title"> and + <xref linkend="sql-createdatabase-title" endterm="sql-createdatabase-title"> + for information on how to create a database. </para> </refsect2> </refsect1> @@ -133,8 +134,6 @@ WARN: destroydb: database "<replaceable class="parameter">name</replaceable>" do <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPDATABASE-4"> <refsect2info> @@ -143,8 +142,11 @@ WARN: destroydb: database "<replaceable class="parameter">name</replaceable>" do <title> SQL92 </title> + <para> - There is no <command>DROP DATABASE</command> in <acronym>SQL92</acronym>. + <command>DROP DATABASE</command> statement is a + <productname>Postgres</productname> language extension; + there is no such command in <acronym>SQL92</acronym>. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index bf6e778c377..888929e928e 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.7 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPFUNCTION"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPFUNCTION-TITLE"> DROP FUNCTION </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) @@ -108,9 +113,16 @@ WARN RemoveFunction: Function "<replaceable class="parameter">name</replaceable> <title> Notes </title> + + <para> + Refer to + <xref linkend="sql-createfunction-title" endterm="sql-createfunction-title"> + for information on creating aggregate functions. + </para> + <para> - Refer to <command>CREATE FUNCTION</command> - to create aggregate functions. + No checks are made to ensure that types, operators or access + methods that rely on the function have been removed first. </para> </refsect2> </refsect1> @@ -119,6 +131,7 @@ WARN RemoveFunction: Function "<replaceable class="parameter">name</replaceable> <title> Usage </title> + <para> This command removes the square root function: @@ -128,26 +141,27 @@ DROP FUNCTION sqrt(int4); </para> </refsect1> - <refsect1 id="R1-SQL-DROPFUNCTION-3"> - <title> - Bugs - </title> - <para> - No checks are made to ensure that types, operators or access - methods that rely on the function have been removed first. - </para> - </refsect1> - <refsect1 id="R1-SQL-DROPFUNCTION-4"> <title> Compatibility </title> - <para> - DROP FUNCTION is a <productname>Postgres</productname> language extension. - </para> <refsect2 id="R2-SQL-DROPFUNCTION-4"> <refsect2info> + <date>1999-07-20</date> + </refsect2info> + <title> + SQL92 + </title> + + <para> + <command>DROP FUNCTION</command> + is a <productname>Postgres</productname> language extension. + </para> + </refsect2> + + <refsect2 id="R2-SQL-DROPFUNCTION-5"> + <refsect2info> <date>1998-04-15</date> </refsect2info> <title> @@ -156,9 +170,10 @@ DROP FUNCTION sqrt(int4); <para> SQL/PSM is a proposed standard to enable function extensibility. The SQL/PSM DROP FUNCTION statement has the following syntax: - <programlisting> + + <synopsis> DROP [ SPECIFIC ] FUNCTION <replaceable class="parameter">name</replaceable> { RESTRICT | CASCADE } - </programlisting> + </synopsis> </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 54d6f12a8d9..22b7ce2c969 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_index.sgml,v 1.7 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPINDEX"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPINDEX-TITLE"> DROP INDEX </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP INDEX <replaceable class="PARAMETER">index_name</replaceable> @@ -102,8 +107,9 @@ ERROR: index "<replaceable class="PARAMETER">index_name</replaceable>" nonexiste language extension. </para> <para> - Refer to the <command>CREATE INDEX</command> statement for - information on how to create indexes. + Refer to + <xref linkend="sql-createindex-title" endterm="sql-createindex-title"> + for information on how to create indexes. </para> </refsect2> </refsect1> @@ -125,8 +131,6 @@ ERROR: index "<replaceable class="PARAMETER">index_name</replaceable>" nonexiste <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPINDEX-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 425cc9efcee..a0764724d08 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_language.sgml,v 1.7 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPLANGUAGE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPLANGUAGE-TITLE"> DROP LANGUAGE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-04-15</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP PROCEDURAL LANGUAGE '<replaceable class="PARAMETER">name</replaceable>' @@ -104,18 +109,11 @@ ERROR: Language "<replaceable class="parameter">name</replaceable>" doesn't exis a <productname>Postgres</productname> language extension. </para> <para> - Refer to <command>CREATE PROCEDURAL LANGUAGE</command> + Refer to + <xref linkend="sql-createlanguage-title" endterm="sql-createlanguage-title"> for information on how to create procedural languages. </para> - </refsect2> - - <refsect2 id="R2-SQL-DROPLANGUAGE-4"> - <refsect2info> - <date>1998-04-15</date> - </refsect2info> - <title> - Bugs - </title> + <para> No checks are made if functions or trigger procedures registered in this language still exist. To re-enable them without having @@ -143,8 +141,6 @@ DROP PROCEDURAL LANGUAGE 'plsample'; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPLANGUAGE-5"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index d70324edc79..e97c74fe476 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_operator.sgml,v 1.6 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPOPERATOR"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPOPERATOR-TITLE"> DROP OPERATOR </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -16,7 +21,7 @@ <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP OPERATOR <replaceable class="PARAMETER">id</replaceable> ( <replaceable class="PARAMETER">type</replaceable> | NONE [,...] ) @@ -138,8 +143,9 @@ ERROR: RemoveOperator: right unary operator '<replaceable class="PARAMETER">ope language extension. </para> <para> - Refer to <command>CREATE OPERATOR</command> for - information on how to create operators. + Refer to + <xref linkend="sql-createoperator-title" endterm="sql-createoperator-title"> + for information on how to create operators. </para> <para> It is the user's responsibility to remove any access methods and @@ -178,8 +184,6 @@ DROP OPERATOR ! (int4, none); <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPOPERATOR-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_rule.sgml b/doc/src/sgml/ref/drop_rule.sgml index 8634c33fcc9..cb14be418c9 100644 --- a/doc/src/sgml/ref/drop_rule.sgml +++ b/doc/src/sgml/ref/drop_rule.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_rule.sgml,v 1.6 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPRULE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPRULE-TITLE"> DROP RULE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -103,19 +108,12 @@ ERROR: RewriteGetRuleEventRel: rule "<replaceable class="parameter">name</repla <productname>Postgres</productname> language extension. </para> + <para> Refer to <command>CREATE RULE</command> for information on how to create rules. </para> - </refsect2> - <refsect2 id="R2-SQL-DROPRULE-4"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Bugs - </title> <para> Once a rule is dropped, access to historical information the rule has written may disappear. @@ -140,9 +138,7 @@ DROP RULE newrule; <title> Compatibility </title> - <para> - </para> - + <refsect2 id="R2-SQL-DROPRULE-5"> <refsect2info> <date>1998-09-22</date> diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index 13673693743..a6c39c1b6fd 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.6 1999/07/22 15:09:10 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPSEQUENCE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPSEQUENCE-TITLE"> DROP SEQUENCE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP SEQUENCE <replaceable class="PARAMETER">name</replaceable> [, ...] @@ -127,8 +132,6 @@ DROP SEQUENCE serial; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPSEQUENCE-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index 5f979f52275..5c90c18b1f5 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.6 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPTABLE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPTABLE-TITLE"> DROP TABLE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP TABLE <replaceable class="PARAMETER">name</replaceable> [, ...] @@ -127,8 +132,6 @@ DROP TABLE films, distributors; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPTABLE-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml index 333b8b9e905..beb5f202638 100644 --- a/doc/src/sgml/ref/drop_trigger.sgml +++ b/doc/src/sgml/ref/drop_trigger.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_trigger.sgml,v 1.6 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPTRIGGER"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPTRIGGER-TITLE"> DROP TRIGGER </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -135,8 +140,6 @@ DROP TRIGGER if_dist_exists ON films; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPTRIGGER-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 94745bb963e..35e1d1d391b 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.6 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPTYPE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPTYPE-TITLE"> DROP TYPE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP TYPE <replaceable class="PARAMETER">typename</replaceable> @@ -111,15 +116,7 @@ ERROR: RemoveType: type '<replaceable class="parameter">typename</replaceable>' functions, aggregates, access methods, subtypes, and classes that use a deleted type. </para> - </refsect2> - <refsect2 id="R2-SQL-DROPTYPE-4"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Bugs - </title> <para> If a built-in type is removed, the behavior of the backend is unpredictable. @@ -144,8 +141,6 @@ DROP TYPE box; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPTYPE-5"> <refsect2info> @@ -155,7 +150,7 @@ DROP TYPE box; SQL3 </title> <para> - DROP TYPE is a <acronym>SQL3</acronym> statement. + <command>DROP TYPE</command> is a <acronym>SQL3</acronym> statement. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml index c9a32f4f823..8f594b83147 100644 --- a/doc/src/sgml/ref/drop_user.sgml +++ b/doc/src/sgml/ref/drop_user.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.7 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPUSER"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPUSER-TITLE"> DROP USER </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP USER <replaceable class="PARAMETER">name</replaceable> @@ -129,8 +134,6 @@ DROP USER Jonathan; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPUSER-4"> <refsect2info> diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 32e5c34e20d..7d08cbf485e 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_view.sgml,v 1.6 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-DROPVIEW"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-DROPVIEW-TITLE"> DROP VIEW </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> DROP VIEW <replaceable class="PARAMETER">name</replaceable> @@ -126,8 +131,6 @@ DROP VIEW kinds; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-DROPVIEW-4"> <refsect2info> diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml new file mode 100644 index 00000000000..04f86d57fe0 --- /dev/null +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -0,0 +1,367 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.1 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + +<refentry id="APP-ECPG"> + <refmeta> + <refentrytitle id="app-ecpg-title"> + <application>ecpg</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + <application>ecpg</application> + </refname> + <refpurpose> + Embedded SQL C preprocessor + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1999-07-20</date> + </refsynopsisdivinfo> + <synopsis> +ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ] + </synopsis> + + <refsect2 id="R2-APP-ECPG-1"> + <refsect2info> + <date>1999-07-20</date> + </refsect2info> + <title> + Inputs + </title> + <para> + <application>ecpg</application> accepts the following command + line arguments: + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">file</replaceable></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-APP-ECPG-2"> + <refsect2info> + <date>1998-11-05</date> + </refsect2info> + <title> + Outputs + </title> + <para> + <application>ecpg</application> will create a file or + write to <filename>stdout</filename>. + + <variablelist> + <varlistentry> + <term><computeroutput> + </computeroutput></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-APP-ECPG-1"> + <refsect1info> + <date>1998-11-05</date> + </refsect1info> + <title> + Description + </title> + <para> +<!-- +.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP +.SH NAME +ecpg - embedded SQL preprocessor for C / PostgreSQL +.SH SYNOPSIS +.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ] +\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ] +.SH DESCRIPTION +.B \fIecpg\fP +is an embedded SQL preprocessor for C / PostgreSQL. It +enables development of C programs with embedded SQL code. +.PP +.B \fIecpg\fP +is ultimately intended to be as compliant as possible with the +ANSI SQL-2 standard and existing commercial ESQL/C packages. +.SH OPTIONS +.B \fIecpg\fP +interprets the following flags when it is invoked +on the command line: +.PP +.PD 0 +.TP 10 +.BI \-v +Print version information. +.PD +.TP +.B \-t +Turn off auto-transactin mode. +.PD +.TP +.PD +.TP +.B \-I include-path +Specify additional include path. Defaults are \., +/usr/local/include, the PostgreSQL include path which is defined at compile +time (default: /usr/local/pgsql/lib), /usr/include +.PD +.TP +.B \-o +Specifies that ecpg should write all its output to outfile. +If no such option is given the output is written to foo.c +(if the input file was named foo.pgc.) +If the input file was named foo.bar the output file will be +named foo.bar.c. +.PD +.TP +.B file1, file2... +The files to be processed. +.\" +.SH INSTALLATION +The +.B \fIecpg\fP +preprocessor is built during the PostgreSQL installation. Binaries and +libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... ) +subdirectories. +.SH PREPROCESSING FOR COMPILATION +.B \fIecpg\fP +.\" (-d ) (-o file) file.pgc ( 2> ecpf.log) +(-o file) file.pgc +.LP +.\" The optional \-d flag turns on debugging and 2> ecpg.log +.\" redirects the debug output. The .pgc extension is an +.\" arbitrary means of denoting ecpg source. +The .pgc extension is an arbitrary means of denoting ecpg source. +.SH COMPILING AND LINKING +Assuming the \fIPostgreSQL\fP binaries are in /usr/local/pgsql: +.LP +gcc -g -i /usr/local/pgsql/include (-o file) file.c +-L /usr/local/pgsql/lib -lecpg -lpq +.SH ECPG GRAMMAR +.LP +.SH LIBRARIES +.LP +The preprocessor will prepend two directives to the source: +.LP +\fI#include <ecpgtype.h>\fP and \fI#include <ecpglib.h>\fP +.SH VARIABLE DECLARATION +Variables declared within ecpg source code must be prepended with: +.LP +EXEC SQL BEGIN DECLARE SECTION; +.LP +Similarly, variable declaration sections must terminate with: +.LP +EXEC SQL END DECLARE SECTION; +.LP +NOTE: prior to version 2.1.0, each variable had to be declared +on a separate line. As of version 2.1.0 multiple variables may +be declared on a single line: +.LP +char foo(16), bar(16); +.LP +.SH ERROR HANDLING +The SQL communication area is defined with: +.LP +EXEC SQL INCLUDE sqlca; +.LP +NOTE: the lowercase `sqlca'. While SQL convention may be +followed, i.e., using uppercase to separate embedded SQL +from C statements, sqlca (which includes the sqlca.h +header file) MUST be lowercase. This is because the EXEC SQL +prefix indicates that this INCLUDE will be parsed by ecpg. +ecpg observes case sensitivity (SQLCA.h will not be found.) +EXEC SQL INCLUDE can be used to include other header files +as long as case sensitivity is observed. +.LP +The sqlprint command is used with the EXEC SQL WHENEVER +statement to turn on error handling throughout the +program: +.LP +EXEC SQL WHENEVER sqlerror sqlprint; +.LP +EXEC SQL WHENEVER not found sqlprint; +.LP +PLEASE NOTE: this is *not* an exhaustive example of usage for +the EXEC SQL WHENEVER statement. Further examples of usage may +be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by +Groff and Weinberg.) +.LP +.SH CONNECTING TO THE DATABASE SERVER +Prior to version 2.1.0 the database name was single quoted: +.RS +EXEC SQL CONNECT 'test1'; +.RE +.LP +As of version 2.1.0, the syntax has been simplified: +.LP +.RS +EXEC SQL CONNECT test1; +.RE +(The database name is no longer quoted.) +.LP +Specifying a server and port name in the connect statement is also possible +as of version 6.4. of PostgreSQL. The syntax is: +.LP +.RS +dbname[@server][:port] +.RE +.LP +or +.LP +.RS +<tcp|unix>:postgresql://server[:port][/dbname][?options] +.RE +.SH QUERIES +.LP +.SS Create Table: +.LP +EXEC SQL CREATE TABLE foo (number int4, ascii char(16)); +.RS +EXEC SQL CREATE UNIQUE index num1 on foo(number); +.RE +EXEC SQL COMMIT; +.LP +.SS Insert: +.LP +EXEC SQL INSERT INTO foo (number, ascii) +.RS +VALUES (9999, 'doodad'); +.RE +EXEC SQL COMMIT; +.LP +.SS Delete: +.LP +EXEC SQL DELETE FROM foo +.RS +WHERE number = 9999; +.RE +EXEC SQL COMMIT; +.LP +.SS Singleton Select: +.LP +EXEC SQL SELECT foo INTO :FooBar FROM table1 +.RS +WHERE ascii = 'doodad'; +.RE +.LP +.SS Select using Cursors: +.LP +EXEC SQL DECLARE foo_bar CURSOR FOR +.RS +SELECT number, ascii FROM foo +.RS +ORDER BY ascii; +.RE +.RE +EXEC SQL FETCH foo_bar INTO :FooBar, DooDad; +.LP +... +EXEC SQL CLOSE foo_bar; +.RS +EXEC SQL COMMIT; +.RE +.LP +.SS Updates +.LP +EXEC SQL UPDATE foo +.RS +SET ascii = 'foobar' +.RE +.RS +WHERE number = 9999; +.RE +EXEC SQL COMMIT; +.LP +.SH BUGS +.LP +The is no EXEC SQL PREPARE statement. +.LP +The complete structure definition MUST be listed +inside the declare section. +.LP +See the TODO file in the source for some more missing features. +.LP +.SH "RETURN VALUE" +.LP +ecpg returns 0 to the shell on successful completion, -1 +for errors. +.LP +.SH "SEE ALSO" +.PD 0 +.TP +\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l) +.TP +\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l) +.PD +.SH FILES +.PD 0 +.TP +.B /usr/src/pgsql/postgresql-${ver}/src/interfaces... + ./ecpg/include.......source for \fIecpg\fP header files. + ./ecpg/lib...........source for \fIecpg\fP libraries. + ./ecpg/preproc.......source for \fIecpg\fP header files. + ./ecpg/test..........source for \fIecpg\fP libraries. + (test contains examples of syntax for ecpg SQL-C.) +.PD +.TP +.B /usr/local/pgsql/bin +\fIPostgreSQL\fP binaries including \fIecpg\fP. +.PD +.TP +.B /usr/local/pgsql/include +\fIPostgreSQL\fP headers including \fIecpglib.h\fP \fIecpgtype.h\fP +and \fIsqlca.h\fP. +.PD +.TP +.B /usr/local/pgsql/lib +\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and +\fIlibecpg.so\fP. +.SH AUTHORS +Linus Tolke \fI<linus@epact.se>\fP +- original author of ECPG (up to version 0.2). +.br +.PP +Michael Meskes \fI<meskes@debian.org>\fP +- actual author and maintainer of ECPG. +.br +.PP +Thomas Good \fI<tomg@q8.nrnet.org>\fP +- author of this revision of the ecpg man page. +.br +.zZ +--> + + </para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml new file mode 100644 index 00000000000..0b5f6ce41b9 --- /dev/null +++ b/doc/src/sgml/ref/end.sgml @@ -0,0 +1,170 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.1 1999/07/22 15:09:11 thomas Exp $ +Postgres documentation +--> + +<refentry id="SQL-END"> + <refmeta> + <refentrytitle id="SQL-END-TITLE"> + END + </refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + END + </refname> + <refpurpose> + Commits the current transaction + </refpurpose> + </refnamediv> + + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1999-07-20</date> + </refsynopsisdivinfo> + <synopsis> +END [ WORK | TRANSACTION ] + </synopsis> + + <refsect2 id="R2-SQL-END-1"> + <refsect2info> + <date>1998-09-08</date> + </refsect2info> + <title> + Inputs + </title> + <para> + + <variablelist> + <varlistentry> + <term>WORK</term> + <term>TRANSACTION</term> + <listitem> + <para> + Optional keywords. They have no effect. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-SQL-END-2"> + <refsect2info> + <date>1998-09-08</date> + </refsect2info> + <title> + Outputs + </title> + <para> + + <variablelist> + <varlistentry> + <term><computeroutput> +END + </computeroutput></term> + <listitem> + <para> + Message returned if the transaction is successfully committed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput> +NOTICE EndTransactionBlock and not inprogress/abort state + </computeroutput></term> + <listitem> + <para> + If there is no transaction in progress. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-SQL-END-1"> + <refsect1info> + <date>1998-09-08</date> + </refsect1info> + <title> + Description + </title> + + <para> + <command>END</command> is a <productname>Postgres</productname> + synonym for + <xref linkend="sql-commit-title" endterm="sql-commit-title">. + </para> + + <refsect2 id="R2-SQL-END-3"> + <refsect2info> + <date>1998-09-08</date> + </refsect2info> + <title> + Notes + </title> + <para> + The keywords WORK and TRANSACTION are noise and can be omitted. + </para> + + <para> + Use <xref linkend="SQL-ROLLBACK-TITLE" endterm="SQL-ROLLBACK-TITLE"> + to abort a transaction. + </para> + </refsect2> + </refsect1> + + <refsect1 id="R1-SQL-END-2"> + <title> + Usage + </title> + <para> + To make all changes permanent: + + <programlisting> +END WORK; + </programlisting> + </para> + </refsect1> + + <refsect1 id="R1-SQL-END-3"> + <title> + Compatibility + </title> + + <refsect2 id="R2-SQL-END-4"> + <refsect2info> + <date>1998-09-08</date> + </refsect2info> + <title> + SQL92 + </title> + + <para> + <command>END</command> is a <productname>Postgres</productname> + extension which provides functionality equivalent to + <xref linkend="sql-commit-title" endterm="sql-commit-title">. + </para> + </refsect2> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 7f571125704..cc73bcf7ff7 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.8 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-EXPLAIN"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-EXPLAIN-TITLE"> EXPLAIN </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -16,7 +21,7 @@ <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-01</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> EXPLAIN [ VERBOSE ] <replaceable class="PARAMETER">query</replaceable> @@ -95,6 +100,7 @@ EXPLAIN <title> Description </title> + <para> This command outputs details about the supplied query. The default output is the computed query cost. @@ -127,16 +133,54 @@ EXPLAIN <title> Usage </title> + + <para> + To show a query plan for a simple query on a table with a single + <type>int4</type> column and 128 rows: + + <programlisting> +EXPLAIN SELECT * FROM foo; + <computeroutput> +NOTICE: QUERY PLAN: + +Seq Scan on foo (cost=5.22 rows=128 width=4) + +EXPLAIN + </computeroutput> + </programlisting> + </para> + <para> - To show a query plan for a simple query: + For the same table with an index to support an + <firstterm>equijoin</firstterm> condition on the query, + <command>EXPLAIN</command> will show a different plan: <programlisting> -EXPLAIN select * from foo; +EXPLAIN SELECT * FROM foo WHERE i = 4; + <computeroutput> NOTICE: QUERY PLAN: -Seq Scan on foo (cost=0.00 rows=0 width=4) +Index Scan using fi on foo (cost=2.05 rows=1 width=4) EXPLAIN + </computeroutput> + </programlisting> + </para> + + <para> + And finally, for the same table with an index to support an + <firstterm>equijoin</firstterm> condition on the query, + <command>EXPLAIN</command> will show the following for a query + using an aggregate function: + + <programlisting> +EXPLAIN SELECT sum(i) FROM foo WHERE i = 4; + <computeroutput> +NOTICE: QUERY PLAN: + +Aggregate (cost=2.05 rows=1 width=4) + -> Index Scan using fi on foo (cost=2.05 rows=1 width=4) + </computeroutput> </programlisting> </para> </refsect1> @@ -145,8 +189,6 @@ EXPLAIN <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-EXPLAIN-4"> <refsect2info> diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index bd384fabede..db072d9f5fa 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.7 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-FETCH"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-FETCH-TITLE"> FETCH </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-01</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> FETCH [ <replaceable class="PARAMETER">selector</replaceable> ] [ <replaceable class="PARAMETER">count</replaceable> ] { IN | FROM } <replaceable class="PARAMETER">cursor</replaceable> @@ -212,8 +217,9 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <title> Description </title> + <para> - FETCH allows a user to retrieve rows using a cursor. + <command>FETCH</command> allows a user to retrieve rows using a cursor. The number of rows retrieved is specified by <replaceable class="PARAMETER">#</replaceable>. If the number of rows remaining in the cursor is less @@ -226,38 +232,13 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <tip> <para> - Negative numbers are now allowed to be specified for the + Negative numbers are 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 - <productname>Postgres</productname>, - because mapping cursor updates back to base tables is - 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> @@ -266,11 +247,45 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <title> Notes </title> + <para> - Use <command>MOVE</command> to change cursor position. - <command>DECLARE</command> will define a cursor. - Refer to <command>BEGIN</command>, <command>COMMIT</command>, and - <command>ROLLBACK</command> + 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 + <productname>Postgres</productname>, + because mapping cursor updates back to base tables is + 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> + + <para> + Use + <xref linkend="sql-move-title" endterm="sql-move-title"> + to change cursor position. + <xref linkend="sql-declare-title" endterm="sql-declare-title"> + will define a cursor. + Refer to + <xref linkend="sql-begin-title" endterm="sql-begin-title">, + <xref linkend="sql-commit-title" endterm="sql-commit-title">, + and + <xref linkend="sql-rollback-title" endterm="sql-rollback-title"> for further information about transactions. </para> </refsect2> @@ -280,7 +295,10 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <title> Usage </title> + <para> + The following examples traverses a table using a cursor. + <programlisting> --set up and use a cursor: -- @@ -292,6 +310,7 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> -- FETCH FORWARD 5 IN liahona; + <computeroutput> code |title |did| date_prod|kind |len -----+-----------------------+---+----------+----------+------ BL101|The Third Man |101|1949-12-23|Drama | 01:44 @@ -299,15 +318,17 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> JL201|Une Femme est une Femme|102|1961-03-12|Romantic | 01:25 P_301|Vertigo |103|1958-11-14|Action | 02:08 P_302|Becket |103|1964-02-03|Drama | 02:28 - + </computeroutput> --Fetch previous row: -- FETCH BACKWARD 1 IN liahona; + <computeroutput> code |title |did| date_prod|kind |len -----+-----------------------+---+----------+----------+------ P_301|Vertigo |103|1958-11-14|Action | 02:08 + </computeroutput> -- close the cursor and commit work: -- @@ -321,11 +342,6 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <title> Compatibility </title> - <para> - The non-embedded use of cursors is a <productname>Postgres</productname> - extension. The syntax and usage of cursors is being compared - against the embedded form of cursors defined in <acronym>SQL92</acronym>. - </para> <refsect2 id="R2-SQL-FETCH-4"> <refsect2info> @@ -334,6 +350,17 @@ FETCH RELATIVE 0 FROM <replaceable class="PARAMETER">cursor</replaceable> <title> SQL92 </title> + + <para> + <note> + <para> + The non-embedded use of cursors is a <productname>Postgres</productname> + extension. The syntax and usage of cursors is being compared + against the embedded form of cursors defined in <acronym>SQL92</acronym>. + </para> + </note> + </para> + <para> <acronym>SQL92</acronym> allows absolute positioning of the cursor for FETCH, and allows placing the results into explicit variables. diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 395f90061d7..ff7f1529bc7 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.6 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-GRANT"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-GRANT-TITLE"> GRANT </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-23</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> GRANT <replaceable class="PARAMETER">privilege</replaceable> [, ...] ON <replaceable class="PARAMETER">object</replaceable> [, ...] @@ -216,6 +221,7 @@ ERROR: ChangeAcl: class "<replaceable class="PARAMETER">object</replaceable>" n <title> Description </title> + <para> <command>GRANT</command> allows the creator of an object to give specific permissions to all users (PUBLIC) or to a certain user or group. @@ -274,6 +280,7 @@ ERROR: ChangeAcl: class "<replaceable class="PARAMETER">object</replaceable>" n <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; @@ -313,8 +320,6 @@ GRANT ALL ON kinds TO manuel; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-GRANT-4"> <refsect2info> diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index f8702f27790..200c030ed48 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.5 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-INITDB"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-INITDB-TITLE"> <application>initdb</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <replaceable class="parameter">dbdir</replaceable> ] diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml index 5d47009843f..edbc6613ed0 100644 --- a/doc/src/sgml/ref/initlocation.sgml +++ b/doc/src/sgml/ref/initlocation.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.4 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-INITLOCATION"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-INITLOCATION-TITLE"> <application>initlocation</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-02</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> initlocation [ --location=<replaceable class="parameter">er">al</replaceable>ble> | -D <replaceable class="parameter">altdir</replaceable> ] diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 2860f89e1e7..933a04f26a1 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.6 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-INSERT"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-INSERT-TITLE"> INSERT </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-23</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] @@ -118,16 +123,27 @@ INSERT 0 <replaceable>#</replaceable> <title> Description </title> + <para> - <command>INSERT</command> allows one to insert new rows into a table. One can insert + <command>INSERT</command> allows one to insert new rows into a + class or 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 + </para> + + <para> + Each column not present in the target list will be inserted + using a default value, either a declared DEFAULT value + or NULL. <productname>Postgres</productname> will reject the new + column if a NULL is inserted into a column declared NOT NULL. + </para> + + <para> + 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 @@ -177,7 +193,8 @@ INSERT INTO films SELECT * FROM tmp; </para> <para> - Insert into arrays (refer to <citetitle>The PostgreSQL User's Guide</citetitle> for further + Insert into arrays (refer to + <citetitle>The PostgreSQL User's Guide</citetitle> for further information about arrays): <programlisting> @@ -197,8 +214,6 @@ INSERT INTO tictactoe (game, board) <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-INSERT-4"> <refsect2info> @@ -211,7 +226,8 @@ INSERT INTO tictactoe (game, board) <command>INSERT</command> 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. + clause are documented for + <xref linkend="sql-select-title" endterm="sql-select-title">. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/ipcclean.sgml b/doc/src/sgml/ref/ipcclean.sgml new file mode 100644 index 00000000000..6063c332937 --- /dev/null +++ b/doc/src/sgml/ref/ipcclean.sgml @@ -0,0 +1,117 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.1 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + +<refentry id="APP-IPCCLEAN"> + <refmeta> + <refentrytitle id="APP-IPCCLEAN-TITLE"> + <application>ipcclean</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + <application>ipcclean</application> + </refname> + <refpurpose> + Clean up shared memory and semaphores from aborted backends + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1999-07-20</date> + </refsynopsisdivinfo> + <synopsis> +ipcclean + </synopsis> + + <refsect2 id="R2-APP-IPCCLEAN-1"> + <refsect2info> + <date>1999-07-20</date> + </refsect2info> + <title> + Inputs + </title> + <para> + None. + </para> + </refsect2> + + <refsect2 id="R2-APP-IPCCLEAN-2"> + <refsect2info> + <date>1999-07-30</date> + </refsect2info> + <title> + Outputs + </title> + <para> + None. + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-APP-IPCCLEAN-1"> + <refsect1info> + <date>1999-07-20</date> + </refsect1info> + <title> + Description + </title> + <para> + <application>ipcclean</application> + cleans up shared memory and semaphore space from aborted backends by + deleting all instances owned by user <literal>postgres</literal>. + Only the DBA + should execute this program as it can cause bizarre behavior (i.e., + crashes) if run during multi-user execution. This program should be + executed if messages such as + + <computeroutput> +semget: No space left on device + </computeroutput> + + are encountered when starting up the + <application>postmaster</application> or the backend server. + </para> + + <para> + If this command is executed while <application>postmaster</application> + is running, the shared memory and semaphores allocated by the + <application>postmaster</application> + will be deleted. This will result in a general failure of the + backends servers started by that + <application>postmaster</application>. + </para> + + <para> + This script is a hack, but in the many years since it was written, no + one has come up with an equally effective and portable solution. + Suggestions are welcome. + </para> + + <para> + The script makes assumption about the format of output of the + <application>ipcs</application> + utility which may not be true across different operating systems. + Therefore, it may not work on your particular OS. + </para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 1cb5d259f12..b03ea67808f 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.7 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-LISTEN"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-LISTEN-TITLE"> LISTEN </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-07</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> LISTEN <replaceable class="PARAMETER">name</replaceable> @@ -85,11 +90,14 @@ NOTICE Async_Listen: We are already listening on <replaceable class="PARAMETER"> <title> Description </title> + <para> - <command>LISTEN</command> registers the current <productname>Postgres</productname> backend as a + <command>LISTEN</command> registers the current + <productname>Postgres</productname> backend as a listener on the notify condition <replaceable class="PARAMETER">name</replaceable>. </para> + <para> Whenever the command <command>NOTIFY <replaceable class="PARAMETER">name</replaceable></command> @@ -99,11 +107,13 @@ NOTICE Async_Listen: We are already listening on <replaceable class="PARAMETER"> frontend application. See the discussion of <command>NOTIFY</command> for more information. </para> + <para> A backend can be unregistered 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 @@ -116,8 +126,10 @@ NOTICE Async_Listen: We are already listening on <replaceable class="PARAMETER"> <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 + <xref linkend="sql-notify-title" endterm="sql-notify-title"> + contains a more extensive discussion of the use of <command>LISTEN</command> and <command>NOTIFY</command>. </para> @@ -129,6 +141,7 @@ NOTICE Async_Listen: We are already listening on <replaceable class="PARAMETER"> <title> Notes </title> + <para> <replaceable class="PARAMETER">name</replaceable> can be any string valid as a name; diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index 77a154c7c45..8fb5fafdb89 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.7 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-LOAD"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-LOAD-TITLE"> LOAD </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> LOAD '<replaceable class="PARAMETER">filename</replaceable>' @@ -86,12 +91,14 @@ ERROR: LOAD: could not open file '<replaceable class="PARAMETER">filename</repl <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>, @@ -102,6 +109,7 @@ ERROR: LOAD: could not open file '<replaceable class="PARAMETER">filename</repl 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> @@ -109,6 +117,7 @@ ERROR: LOAD: could not open file '<replaceable class="PARAMETER">filename</repl <title> Notes </title> + <para> Functions in loaded object files should not call functions in other object files loaded through the @@ -157,8 +166,6 @@ LOAD '/usr/postgres/demo/circle.o' <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-LOAD-4"> <refsect2info> diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index 9147f6a0854..79d558da129 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/lock.sgml,v 1.13 1999/07/22 15:09:12 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-LOCK"> <refmeta> - <refentrytitle> + <refentrytitle id="sql-lock-title"> LOCK </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> LOCK [ TABLE ] <replaceable class="PARAMETER">table</replaceable> @@ -356,8 +361,6 @@ COMMIT WORK; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-LOCK-4"> <refsect2info> @@ -369,7 +372,7 @@ COMMIT WORK; <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. We support that too; see + concurrency levels on transactions. We support that too; see <xref linkend="SQL-SET-TITLE" endterm="SQL-SET-TITLE"> for details. </para> </refsect2> diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index fdac32aca4b..eeb74bd9aae 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.6 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-MOVE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-MOVE-TITLE"> MOVE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> MOVE [ <replaceable class="PARAMETER">selector</replaceable> ] [ <replaceable class="PARAMETER">count</replaceable> ] @@ -39,7 +44,9 @@ MOVE [ <replaceable class="PARAMETER">selector</replaceable> ] [ <replaceable cl not return rows. </para> <para> - Refer to the <command>FETCH</command> command for details on syntax and usage. + Refer to + <xref linkend="sql-fetch-title" endterm="sql-fetch-title"> + for details on syntax and usage. </para> <refsect2 id="R2-SQL-MOVE-3"> @@ -49,16 +56,24 @@ MOVE [ <replaceable class="PARAMETER">selector</replaceable> ] [ <replaceable cl <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 + Refer to + <xref linkend="sql-fetch-title" endterm="sql-fetch-title"> + for a description of valid arguments. + Refer to + <xref linkend="sql-declare-title" endterm="sql-declare-title"> + to define a cursor. + Refer to + <xref linkend="sql-begin-title" endterm="sql-begin-title">, + <xref linkend="sql-commit-title" endterm="sql-commit-title">, + and + <xref linkend="sql-rollback-title" endterm="sql-rollback-title"> for further information about transactions. </para> </refsect2> @@ -100,8 +115,6 @@ COMMIT WORK; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-MOVE-4"> <refsect2info> @@ -111,10 +124,10 @@ COMMIT WORK; SQL92 </title> <para> - There is no SQL92 <command>MOVE</command> statement. + There is no <acronym>SQL92</acronym> <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. + implicitly moving the cursor to the correct position. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index bf35a5c403f..91dc5f4a100 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/notify.sgml,v 1.10 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-NOTIFY"> <refmeta> - <refentrytitle id="sql-notify-ref"> + <refentrytitle id="sql-notify-title"> NOTIFY </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-07</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> NOTIFY <replaceable class="PARAMETER">name</replaceable> @@ -215,8 +220,6 @@ ASYNC NOTIFY of 'virtual' from backend pid '11239' received <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-NOTIFY-4"> <refsect2info> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index f96d278b4b4..a11a366b435 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,6 +1,11 @@ -<refentry id="APP-PG-DUMP"> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.12 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + +<refentry id="APP-PGDUMP"> <refmeta> - <refentrytitle id="pg-dump"> + <refentrytitle id="app-pgdump-title"> <application>pg_dump</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-11-05</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> pg_dump [ <replaceable class="parameter">dbname</replaceable> ] diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index f06d430e697..b604ed6c55b 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -1,6 +1,11 @@ -<refentry id="APP-PG-DUMPALL"> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.5 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + +<refentry id="APP-PGDUMPALL"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-PGDUMPALL-TITLE"> <application>pg_dumpall</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-04</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> pg_dumpall @@ -256,7 +261,7 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed </para> <para> Refer to - <xref endterm="pg-dump" linkend="app-pg-dump"> + <xref endterm="app-pgdump-title" linkend="app-pgdump-title"> for more information on this capability. </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_passwd.sgml b/doc/src/sgml/ref/pg_passwd.sgml new file mode 100644 index 00000000000..19d776abc92 --- /dev/null +++ b/doc/src/sgml/ref/pg_passwd.sgml @@ -0,0 +1,170 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.1 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + +<refentry id="APP-PG-PASSWD"> + <refmeta> + <refentrytitle id="APP-PG-PASSWD-TITLE"> + <application>pg_passwd</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + <application>pg_passwd</application> + </refname> + <refpurpose> + Manipulate the flat password file + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1999-07-20</date> + </refsynopsisdivinfo> + <synopsis> +pg_passwd <replaceable class="parameter">filename</replaceable> + </synopsis> + </refsynopsisdiv> + + <refsect1 id="R1-APP-PG-PASSWD-1"> + <refsect1info> + <date>1999-07-20</date> + </refsect1info> + <title> + Description + </title> + <para> + <application>pg_passwd</application> + is a tool to manipulate the + flat password file functionality of + <productname>Postgres</productname>. This style of password + authentication is not <emphasis>required</emphasis> in an + installation, but is one of several supported security mechanisms. + </para> + + <para> + Specify the password file in the same style of + <literal>Ident</literal> authentication in + <filename>$PGDATA/pg_hba.conf</filename>: + + <programlisting> +host unv 133.65.96.250 255.255.255.255 password passwd + </programlisting> + + where the above line allows access from 133.65.96.250 using the passwords listed + in <filename>$PGDATA/passwd</filename>. + The format of the password file follows those of + <filename>/etc/passwd</filename> + and + <filename>/etc/shadow</filename>. + The first field is the user name, and the second field + is the encrypted password. + The rest is completely ignored. + Thus the following three sample lines specify the same user and password pair: + + <programlisting> +pg_guest:/nB7.w5Auq.BY:10031:::::: +pg_guest:/nB7.w5Auq.BY:93001:930::/home/guest:/bin/tcsh +pg_guest:/nB7.w5Auq.BY:93001 + </programlisting> + </para> + + <para> + Supply the password file to the pg_passwd command. + In the case described above, after changing the working directory to + <envar>PGDATA</envar>, the following command execution specify + the new password for <literal>pg_guest</literal>: + + <programlisting> + % pg_passwd passwd + Username: pg_guest + Password: + Re-enter password: + </programlisting> + + where the <literal>Password:</literal> + and <literal>Re-enter password:</literal> + prompts require the same password input which are not displayed + on the terminal. + The original password file is renamed to + <filename>passwd.bk</filename>. + </para> + + <para> + <application>psql</application> + uses the <option>-u</option> + option to invoke this style of + authentication. + </para> + + <para> + The following lines show the sample usage of the option: + +<programlisting> +% psql -h hyalos -u unv +Username: pg_guest +Password: +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: unv +unv=> + </programlisting> + </para> + + <para> + Perl5 authentication + uses the new style of the <filename>Pg.pm</filename> like this: + + <programlisting> +$conn = Pg::connectdb("host=hyalos dbname=unv + user=pg_guest password=xxxxxxx"); + </programlisting> + + For more details, refer to + <filename>src/interfaces/perl5/Pg.pm</filename>. + </para> + + <para> + Pg{tcl,tk}sh authentication + uses the + <function>pg_connect</function> + command with the + <option>-conninfo</option> + option thusly: + +<programlisting> +% set conn [pg_connect -conninfo \\ + "host=hyalos dbname=unv \\ + user=pg_guest password=xxxxxxx "] + </programlisting> + + You can list all of the keys for the option by executing the following + command: + + <programlisting> +% puts [ pg_conndefaults] + </programlisting> + </para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/ref/pg_upgrade.sgml b/doc/src/sgml/ref/pg_upgrade.sgml index 46ad32c7a93..78f67cb9a4a 100644 --- a/doc/src/sgml/ref/pg_upgrade.sgml +++ b/doc/src/sgml/ref/pg_upgrade.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_upgrade.sgml,v 1.5 1999/07/22 15:09:13 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-PG-UPGRADE"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-PG-UPGRADE-TITLE"> <application>pg_upgrade</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -12,9 +17,10 @@ <refpurpose> Allows upgrade from a previous release without reloading data </refpurpose> + </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-04</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> pg_upgrade @@ -29,10 +35,14 @@ pg_upgrade [ -f <replaceable class="parameter">filename</replaceable> ] <replace <title> Description </title> + <para> <application>pg_upgrade</application> is a utility for upgrading from a previous PostgreSQL release without reloading all the data. + Not all <productname>Postgres</productname> releases can be handled + this way; check the release notes for details on your installation. + </para> <procedure> <title>Upgrading <productname>Postgres</productname></title> @@ -107,6 +117,8 @@ pg_upgrade [ -f <replaceable class="parameter">filename</replaceable> ] <replace You can delete the <filename>data.old/</filename> directory when you are finished. </para> + </step> + </procedure> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/pgaccess-ref.sgml b/doc/src/sgml/ref/pgaccess-ref.sgml index 2f7b94d8f23..469f8100f58 100644 --- a/doc/src/sgml/ref/pgaccess-ref.sgml +++ b/doc/src/sgml/ref/pgaccess-ref.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgaccess-ref.sgml,v 1.3 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-PGACCESS"> <refmeta> <refentrytitle id="pgaccess-ref"> diff --git a/doc/src/sgml/ref/pgadmin-ref.sgml b/doc/src/sgml/ref/pgadmin-ref.sgml index b605505d619..1ffd7056732 100644 --- a/doc/src/sgml/ref/pgadmin-ref.sgml +++ b/doc/src/sgml/ref/pgadmin-ref.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgadmin-ref.sgml,v 1.3 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-PGADMIN"> <refmeta> <refentrytitle id="pgadmin-ref"> diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 57775152f89..add30e27e42 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.5 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-POSTGRES"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-POSTGRES-TITLE"> <application>postgres</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1999-05-19</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> postgres [ <replaceable class="parameter">dbname</replaceable> ] diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 33081915f29..7b249d17e23 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.4 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-POSTMASTER"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-POSTMASTER-TITLE"> <application>postmaster</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1999-05-19</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -i ] diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 22c3f96fb06..7d148873fe5 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.10 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-PSQL"> <refmeta> - <refentrytitle id="psql-ref"> + <refentrytitle id="app-psql-title"> <application>psql</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-26</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> psql [ <replaceable class="parameter">dbname</replaceable> ] diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index 9b1452816b8..3630fcc54ba 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.7 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-RESET"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-RESET-TITLE"> RESET </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> RESET <replaceable class="PARAMETER">variable</replaceable> @@ -34,7 +39,9 @@ RESET <replaceable class="PARAMETER">variable</replaceable> <term><replaceable class="PARAMETER">variable</replaceable></term> <listitem> <para> - Refer to the SET statement for more information on available + Refer to + <xref linkend="sql-set-title" endterm="sql-set-title"> + for more information on available variables. </para> </listitem> @@ -80,10 +87,14 @@ RESET VARIABLE <para> <command>RESET</command> restores variables to the default values. - Refer to the <command>SET</command> command for details on - allowed values and defaults. + Refer to + <xref linkend="sql-set-title" endterm="sql-set-title"> + for details on allowed values and defaults. <command>RESET</command> is an alternate form for - <command>SET <replaceable class="parameter">variable</replaceable> = DEFAULT</command> + + <synopsis> +SET <replaceable class="parameter">variable</replaceable> = DEFAULT + </synopsis> </para> <refsect2 id="R2-SQL-RESET-3"> @@ -93,12 +104,17 @@ RESET VARIABLE <title> Notes </title> + <para> - The RESET statement is a <productname>Postgres</productname> + <command>RESET</command> is a <productname>Postgres</productname> language extension. </para> + <para> - Refer to SET/SHOW statements to set/show variable values. + Use to + <xref linkend="sql-set-title" endterm="sql-set-title"> and + <xref linkend="sql-show-title" endterm="sql-show-title"> + to manipulate variable values. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index c267651a655..b769a815cf6 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/revoke.sgml,v 1.8 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-REVOKE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-REVOKE-TITLE"> REVOKE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> REVOKE <replaceable class="PARAMETER">privilege</replaceable> [, ...] @@ -84,7 +89,8 @@ REVOKE <replaceable class="PARAMETER">privilege</replaceable> [, ...] <listitem> <para> Privilege to define rules on table/view. - (See <command>CREATE RULE</command>). + (See + <xref linkend="sql-createrule-title" endterm="sql-createrule-title">). </para> </listitem> </varlistentry> @@ -297,6 +303,7 @@ REVOKE ALL ON kinds FROM manuel; <title> SQL92 </title> + <para> The SQL92 syntax for <command>REVOKE</command> has additional capabilities for rescinding @@ -316,7 +323,9 @@ REVOKE { INSERT | UPDATE | REFERENCES } [, ...] [ ( <replaceable class="paramete </term> <listitem> <para> - Refer to <command>GRANT</command> for details on individual fields. + Refer to + <xref linkend="sql-grant-title" endterm="sql-grant-title"> + for details on individual fields. </para> </listitem> </varlistentry> @@ -333,8 +342,9 @@ REVOKE GRANT OPTION FOR <replaceable class="parameter">privilege</replaceable> [ <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. + Refer to + <xref linkend="sql-grant-title" endterm="sql-grant-title"> + for details on individual fields. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index 2ad271e2468..17832debd16 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/rollback.sgml,v 1.6 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-ROLLBACK"> <refmeta> <refentrytitle id="SQL-ROLLBACK-TITLE"> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> ROLLBACK [ WORK | TRANSACTION ] @@ -97,6 +102,8 @@ ABORT <para> Use <xref linkend="SQL-COMMIT-TITLE" endterm="SQL-COMMIT-TITLE"> to successfully terminate a transaction. + <xref linkend="SQL-ABORT-TITLE" endterm="SQL-ABORT-TITLE"> is a + synonym for <command>ROLLBACK</command>. </para> </refsect2> </refsect1> @@ -118,8 +125,6 @@ ROLLBACK WORK; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-ROLLBACK-4"> <refsect2info> diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 9e9d7d7ed1b..0e17cc1c8b3 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.21 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-SELECT"> <refmeta> <refentrytitle id="sql-select-title"> @@ -14,7 +19,7 @@ </refpurpose></refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> SELECT [ ALL | DISTINCT [ ON <replaceable class="PARAMETER">column</replaceable> ] ] @@ -264,16 +269,31 @@ SELECT [ ALL | DISTINCT [ ON <replaceable class="PARAMETER">column</replaceable> <title id="where-title"> WHERE Clause </title> + <para> The optional WHERE condition has the general form: <synopsis> -WHERE <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">ETER">c</replaceable>e<replaceable class="PARAMETER">"PAR</replaceable>replaceable> [ <replaceable class="PARAMETER">log_op</replaceable> ... ] +WHERE <replaceable class="PARAMETER">boolean_expr</replaceable> </synopsis> - where <replaceable class="PARAMETER">cond_op</replaceable> can be - one of: =, <, <=, >, >= or <>, - a conditional operator like ALL, ANY, IN, LIKE, et cetera or a + <replaceable class="PARAMETER">boolean_expr</replaceable> + can consist of any expression which evaluates to a boolean value. + In many cases, this expression will be + + <synopsis> + <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">cond_op</replaceable> <replaceable class="PARAMETER">expr</replaceable> + </synopsis> + + or + + <synopsis> + <replaceable class="PARAMETER">log_op</replaceable> <replaceable class="PARAMETER">expr</replaceable> + </synopsis> + + where <replaceable class="PARAMETER">cond_op</replaceable> + can be one of: =, <, <=, >, >= or <>, + a conditional operator like ALL, ANY, IN, LIKE, or a locally-defined operator, and <replaceable class="PARAMETER">log_op</replaceable> can be one of: AND, OR, NOT. @@ -624,8 +644,6 @@ Woody Allen <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-SELECT-4"> <refsect2info> diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index a75d5a028b5..6617d07e5a6 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.4 1999/07/22 15:09:14 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-SELECTINTO"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-SELECTINTO-TITLE"> SELECT INTO </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -14,7 +19,7 @@ </refpurpose></refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-22</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...] @@ -70,7 +75,8 @@ SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable <note> <para> - CREATE TABLE AS is functionally equivalent to the SELECT INTO command. + <xref linkend="sql-createtableas-title" endterm="sql-createtableas-title"> + is functionally equivalent to the <command>SELECT INTO</command> command. </para> </note> </para> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 39aa7c6ea08..51177570649 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,12 +1,17 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.28 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-SET"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-SET-TITLE"> SET </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> </refmeta> <refnamediv> - <refname id="SQL-SET-TITLE"> + <refname> SET </refname> <refpurpose> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> SET <replaceable class="PARAMETER">variable</replaceable> { TO | = } { '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT } @@ -662,8 +667,6 @@ SELECT CURRENT_TIMESTAMP AS today; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-SET-4"> <refsect2info> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index e19a8cf0e84..14b43d82344 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.7 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-SHOW"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-SHOW-TITLE"> SHOW </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> SHOW <replaceable class="PARAMETER">keyword</replaceable> @@ -157,8 +162,6 @@ NOTICE:GEQO is ON <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-SHOW-4"> <refsect2info> diff --git a/doc/src/sgml/ref/unlisten.sgml b/doc/src/sgml/ref/unlisten.sgml index 51e5c0c93ac..d872dd98a0e 100644 --- a/doc/src/sgml/ref/unlisten.sgml +++ b/doc/src/sgml/ref/unlisten.sgml @@ -1,3 +1,8 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.8 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-UNLISTEN"> <refmeta> <refentrytitle> @@ -95,7 +100,7 @@ UNLISTEN { <replaceable class="PARAMETER">notifyname</replaceable> | * } </para> <para> - <xref endterm="sql-notify-ref" linkend="sql-notify"> + <xref endterm="sql-notify-title" linkend="sql-notify-title"> contains a more extensive discussion of the use of <command>LISTEN</command> and <command>NOTIFY</command>. diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 7383e7de68b..8808f9e799d 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.6 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + <refentry id="SQL-UPDATE"> <refmeta> - <refentrytitle> + <refentrytitle id="SQL-UPDATE-TITLE"> UPDATE </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-09-24</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> UPDATE <replaceable class="PARAMETER">table</replaceable> SET <replaceable class="PARAMETER">R">col</replaceable>le> = <replaceable class="PARAMETER">expression</replaceable> [, ...] @@ -119,11 +124,12 @@ UPDATE <replaceable class="parameter">#</replaceable> <para> <command>UPDATE</command> changes the values of the columns specified for all rows which satisfy condition. Only the columns - to be modified need appear as column. + to be modified need appear as columns in the statement. </para> <para> - Array references use the same syntax found in SELECT. + Array references use the same syntax found in + <xref linkend="sql-select-title" endterm="sql-select-title">. That is, either single array elements, a range of array elements or the entire array may be replaced with a single query. @@ -165,8 +171,6 @@ SELECT * FROM films WHERE kind = 'Dramatic' OR kind = 'Drama'; <title> Compatibility </title> - <para> - </para> <refsect2 id="R2-SQL-UPDATE-4"> <refsect2info> @@ -176,7 +180,8 @@ SELECT * FROM films WHERE kind = 'Dramatic' OR kind = 'Drama'; SQL92 </title> <para> - SQL92 defines a different syntax for positioned UPDATE statement: + <acronym>SQL92</acronym> defines a different syntax for + the positioned UPDATE statement: <synopsis> UPDATE table SET column = expression [, ...] diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 2e9a3fe6531..87666f47276 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -1,6 +1,11 @@ -<refentry id="SQL-VACUUM-1"> +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.5 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + +<refentry id="SQL-VACUUM"> <refmeta> - <refentrytitle id="vacuum"> + <refentrytitle id="sql-vacuum-title"> VACUUM </refentrytitle> <refmiscinfo>SQL - Language Statements</refmiscinfo> @@ -15,7 +20,7 @@ </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> - <date>1998-10-04</date> + <date>1999-07-20</date> </refsynopsisdivinfo> <synopsis> VACUUM [ VERBOSE ] [ ANALYZE ] [ <replaceable class="PARAMETER">table</replaceable> ] @@ -225,6 +230,7 @@ VACUUM <title> Compatibility </title> + <refsect2 id="R2-SQL-VACUUM-4"> <refsect2info> <date>1998-10-04</date> @@ -233,7 +239,7 @@ VACUUM SQL92 </title> <para> - There is no <command>VACUUM</command> statement in SQL92. + There is no <command>VACUUM</command> statement in <acronym>SQL92</acronym>. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 55774395e3a..1bff5bb1c0d 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -1,6 +1,11 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.5 1999/07/22 15:09:15 thomas Exp $ +Postgres documentation +--> + <refentry id="APP-VACUUMDB"> <refmeta> - <refentrytitle> + <refentrytitle id="APP-VACUUMDB-TITLE"> <application>vacuumdb</application> </refentrytitle> <refmiscinfo>Application</refmiscinfo> @@ -225,7 +230,7 @@ FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable> </title> <para> - See <xref endterm="vacuum" linkend="vacuum"> for more details. + See <xref endterm="sql-vacuum-title" linkend="sql-vacuum-title"> for more details. </para> </refsect1> |