diff options
Diffstat (limited to 'doc/src/sgml/ref')
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/ref/commands.sgml | 166 | ||||
| -rw-r--r-- | doc/src/sgml/ref/lock.sgml | 375 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgaccess-ref.sgml | 74 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgadmin-ref.sgml | 74 | ||||
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 2136 | ||||
| -rw-r--r-- | doc/src/sgml/ref/set.sgml | 1325 |
7 files changed, 2197 insertions, 1961 deletions
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index dabbedf5fc5..385224a934f 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -62,7 +62,7 @@ <!entity close system "close.sgml"> <!entity cluster system "cluster.sgml"> <!entity commit system "commit.sgml"> -<!entity copy system "copy.sgml"> +<!entity copyTable system "copy.sgml"> <!entity createAggregate system "create_aggregate.sgml"> <!entity createDatabase system "create_database.sgml"> <!entity createFunction system "create_function.sgml"> @@ -117,8 +117,10 @@ <!entity destroyuser system "destroyuser.sgml"> <!entity initdb system "initdb.sgml"> <!entity initlocation system "initlocation.sgml"> -<!entity pgDump system "pg_dump.sgml"> -<!entity pgDumpall system "pg_dumpall.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 pgUpgrade system "pg_upgrade.sgml"> <!entity psqlRef system "psql-ref.sgml"> <!entity vacuumdb system "vacuumdb.sgml"> diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index 005dbb4d6a9..770c3a20543 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -1,67 +1,69 @@ -<chapter id="sql-commands"> -<Title>SQL Commands</Title> + <chapter id="sql-commands"> + <Title>SQL Commands</Title> -<Para> -This is reference information for the <acronym>SQL</acronym> -commands supported by <productname>Postgres</productname>. -</Para> + <abstract> + <Para> + This is reference information for the <acronym>SQL</acronym> + commands supported by <productname>Postgres</productname>. + </Para> + </abstract> -&abort; -&alterTable; -&alterUser; -&begin; -&close; -&cluster; -&commit; -© -&createAggregate; -&createDatabase; -&createFunction; -&createIndex; -&createLanguage; -&createOperator; -&createRule; -&createSequence; -&createTable; -&createTrigger; -&createType; -&createUser; -&createView; -&declare; -&delete; -&dropAggregate; -&dropDatabase; -&dropFunction; -&dropIndex; -&dropLanguage; -&dropOperator; -&dropRule; -&dropSequence; -&dropTable; -&dropTrigger; -&dropType -&dropUser; -&dropView; -&explain; -&fetch; -&grant; -&insert; -&listen; -&load; -&lock; -&move; -¬ify; -&reset; -&revoke; -&rollback; -&select; -&set; -&show; -&unlisten; -&update; -&vacuum; - -</Chapter> + &abort; + &alterTable; + &alterUser; + &begin; + &close; + &cluster; + &commit; + ©Table; + &createAggregate; + &createDatabase; + &createFunction; + &createIndex; + &createLanguage; + &createOperator; + &createRule; + &createSequence; + &createTable; + &createTrigger; + &createType; + &createUser; + &createView; + &declare; + &delete; + &dropAggregate; + &dropDatabase; + &dropFunction; + &dropIndex; + &dropLanguage; + &dropOperator; + &dropRule; + &dropSequence; + &dropTable; + &dropTrigger; + &dropType + &dropUser; + &dropView; + &explain; + &fetch; + &grant; + &insert; + &listen; + &load; + &lock; + &move; + ¬ify; + &reset; + &revoke; + &rollback; + &select; + &set; + &show; + &unlisten; + &update; + &vacuum; + + </Chapter> <!-- Disable this chapter until we have more functions documented. @@ -84,31 +86,35 @@ functions supported by <productname>Postgres</productname>. --> -<chapter Id="utilities"> -<title>Utility Applications</title> + <chapter Id="utilities"> + <title>Utility Applications</title> -<para> -This is reference information for the -<productname>Postgres</productname> support utilities. -</para> + <abstract> + <para> + This is reference information for the + <productname>Postgres</productname> support utilities. + </para> + </abstract> -&createdb; -&createuser; -&destroydb; -&destroyuser; -&initdb; -&initlocation; -&pgDump; -&pgDumpall; -&psqlRef; -&vacuumdb; + &createdb; + &createuser; + &destroydb; + &destroyuser; + &initdb; + &initlocation; + &pgAccess; + &pgAdmin; + &pgDump; + &pgDumpall; + &psqlRef; + &vacuumdb; -</chapter> + </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml -sgml-omittag:t +sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index 0d2c5047523..dc702b0cdb8 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -1,190 +1,207 @@ <REFENTRY ID="SQL-LOCK"> -<REFMETA> -<REFENTRYTITLE> -LOCK -</REFENTRYTITLE> -<REFMISCINFO>SQL - Language Statements</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME> -LOCK -</REFNAME> -<REFPURPOSE> -Explicit lock of a table inside a transaction -</REFPURPOSE> - </refnamediv> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-09-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -LOCK [ TABLE ] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> -</SYNOPSIS> + <REFMETA> + <REFENTRYTITLE> + LOCK + </REFENTRYTITLE> + <REFMISCINFO>SQL - Language Statements</REFMISCINFO> + </REFMETA> + <REFNAMEDIV> + <REFNAME> + LOCK + </REFNAME> + <REFPURPOSE> + Explicit lock of a table inside a transaction + </REFPURPOSE> + </refnamediv> + <REFSYNOPSISDIV> + <REFSYNOPSISDIVINFO> + <DATE>1998-09-24</DATE> + </REFSYNOPSISDIVINFO> + <SYNOPSIS> + LOCK [ TABLE ] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> + </SYNOPSIS> - <REFSECT2 ID="R2-SQL-LOCK-1"> - <REFSECT2INFO> - <DATE>1998-09-01</DATE> - </REFSECT2INFO> - <TITLE> - Inputs - </TITLE> - <PARA> - </PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> - </TERM> - <LISTITEM> - <PARA> - The name of an existing table to lock. - </para> - </listitem> - </varlistentry> - </VARIABLELIST> + <REFSECT2 ID="R2-SQL-LOCK-1"> + <REFSECT2INFO> + <DATE>1998-09-01</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + </PARA> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> + </TERM> + <LISTITEM> + <PARA> + The name of an existing table to lock. + </para> + </listitem> + </varlistentry> + </VARIABLELIST> - </REFSECT2> + </REFSECT2> - <REFSECT2 ID="R2-SQL-LOCK-2"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - DELETE 0 - </TERM> - <LISTITEM> - <PARA> - Message returned on a successful lock. - <command>LOCK</command> is implemented as a - <command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command> - which is guaranteed to not delete any rows. - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist. - </TERM> - <LISTITEM> - <PARA> - Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> - does not exist. - </para> - </listitem> - </varlistentry> - </VARIABLELIST> - </para> - </REFSECT2> - </REFSYNOPSISDIV> + <REFSECT2 ID="R2-SQL-LOCK-2"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + DELETE 0 + </TERM> + <LISTITEM> + <PARA> + Message returned on a successful lock. + <command>LOCK</command> is implemented as a + <command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command> + which is guaranteed to not delete any rows. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist. + </TERM> + <LISTITEM> + <PARA> + Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> + does not exist. + </para> + </listitem> + </varlistentry> + </VARIABLELIST> + </para> + </REFSECT2> + </REFSYNOPSISDIV> - <REFSECT1 ID="R1-SQL-LOCK-1"> - <REFSECT1INFO> - <DATE>1998-09-24</DATE> - </REFSECT1INFO> - <TITLE> - Description - </TITLE> - <PARA> - <command>LOCK</command> locks in exclusive mode a table inside - a transaction. The classic use for this is - the case where you want to select some data, then - update it inside a transaction. - If you don't explicit lock a table using LOCK statement, it will be - implicit locked only at the first - <command>UPDATE</command>, <command>INSERT</command>, - or <command>DELETE</command> operation. - If you don't exclusive lock the table before the select, some - other user may also read the selected data, and try and do - their own update, causing a deadlock while you both wait - for the other to release the select-induced shared lock so - you can get an exclusive lock to do the update. - </para> - <para> - Another example of deadlock is where one user locks one - table, and another user locks a second table. While both - keep their existing locks, the first user tries to lock - the second user's table, and the second user tries to lock - the first user's table. Both users deadlock waiting for - the tables to become available. The only solution to this - is for both users to lock tables in the same order, so - user's lock acquisitions and requests to not form a deadlock. - </para> - <note> - <para> - <productname>Postgres</productname> does detect deadlocks and will - rollback transactions to resolve the deadlock. Usually, at least one - of the deadlocked transactions will complete successfully. - </para> - </note> + <REFSECT1 ID="R1-SQL-LOCK-1"> + <REFSECT1INFO> + <DATE>1998-09-24</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + <command>LOCK</command> locks in exclusive mode a table inside + a transaction. The classic use for this is + the case where you want to select some data, then + update it inside a transaction. + If you don't explicit lock a table using LOCK statement, it will be + implicit locked only at the first + <command>UPDATE</command>, <command>INSERT</command>, + or <command>DELETE</command> operation. + If you don't exclusive lock the table before the select, some + other user may also read the selected data, and try and do + their own update, causing a deadlock while you both wait + for the other to release the select-induced shared lock so + you can get an exclusive lock to do the update. + </para> + <para> + Another example of deadlock is where one user locks one + table, and another user locks a second table. While both + keep their existing locks, the first user tries to lock + the second user's table, and the second user tries to lock + the first user's table. Both users deadlock waiting for + the tables to become available. The only solution to this + is for both users to lock tables in the same order, so + user's lock acquisitions and requests to not form a deadlock. + </para> + <note> + <para> + <productname>Postgres</productname> does detect deadlocks and will + rollback transactions to resolve the deadlock. Usually, at least one + of the deadlocked transactions will complete successfully. + </para> + </note> - <REFSECT2 ID="R2-SQL-LOCK-3"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - Notes - </TITLE> - <para> - <command>LOCK</command> is a <productname>Postgres</productname> - language extension. - </para> - <para> - <command>LOCK</command> works only inside transactions. - - <note> - <title>Bug</title> - <para> - If the locked table is dropped then it will be automatically - unlocked even if a transaction is still in progress. - </para> - </note> - </para> - </REFSECT2> - </refsect1> + <REFSECT2 ID="R2-SQL-LOCK-3"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Notes + </TITLE> + <para> + <command>LOCK</command> is a <productname>Postgres</productname> + language extension. + </para> + <para> + <command>LOCK</command> works only inside transactions. + + <note> + <title>Bug</title> + <para> + If the locked table is dropped then it will be automatically + unlocked even if a transaction is still in progress. + </para> + </note> + </para> + </REFSECT2> + </refsect1> - <REFSECT1 ID="R1-SQL-LOCK-2"> - <TITLE> - Usage - </TITLE> - <PARA> - </PARA> - <ProgramListing> - --Explicit locking to prevent deadlock: - -- - BEGIN WORK; - LOCK films; - SELECT * FROM films; - UPDATE films SET len = INTERVAL '100 minute' - WHERE len = INTERVAL '117 minute'; - COMMIT WORK; - </ProgramListing> + <REFSECT1 ID="R1-SQL-LOCK-2"> + <TITLE> + Usage + </TITLE> + <PARA> + </PARA> + <ProgramListing> + --Explicit locking to prevent deadlock: + -- + BEGIN WORK; + LOCK films; + SELECT * FROM films; + UPDATE films SET len = INTERVAL '100 minute' + WHERE len = INTERVAL '117 minute'; + COMMIT WORK; + </ProgramListing> - </REFSECT1> + </REFSECT1> - <REFSECT1 ID="R1-SQL-LOCK-3"> - <TITLE> - Compatibility - </TITLE> + <REFSECT1 ID="R1-SQL-LOCK-3"> + <TITLE> + Compatibility + </TITLE> - <REFSECT2 ID="R2-SQL-LOCK-4"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - SQL92 - </TITLE> - <PARA> - There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>, - which instead uses <command>SET TRANSACTION</command> to specify - concurrency level on transactions. - </para> - </refsect2> - </refsect1> + <REFSECT2 ID="R2-SQL-LOCK-4"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + SQL92 + </TITLE> + <PARA> + There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>, + which instead uses <command>SET TRANSACTION</command> to specify + concurrency level on transactions. + </para> + </refsect2> + </refsect1> </REFENTRY> + +<!-- 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/pgaccess-ref.sgml b/doc/src/sgml/ref/pgaccess-ref.sgml new file mode 100644 index 00000000000..ec9b9a1b65a --- /dev/null +++ b/doc/src/sgml/ref/pgaccess-ref.sgml @@ -0,0 +1,74 @@ +<REFENTRY ID="APP-PGACCESS"> + <REFMETA> + <REFENTRYTITLE id="pgaccess-ref"> + <application>pgaccess</application> + </REFENTRYTITLE> + <REFMISCINFO>Application</REFMISCINFO> + </REFMETA> + <REFNAMEDIV> + <REFNAME> + <application>pgaccess</application> + </REFNAME> + <REFPURPOSE> + <productname>Postgres</productname> graphical interactive client + </REFPURPOSE> + </refnamediv> + <REFSYNOPSISDIV> + <REFSYNOPSISDIVINFO> + <DATE>1999-05-19</DATE> + </REFSYNOPSISDIVINFO> + <SYNOPSIS> +pgaccess [ <replaceable class="parameter">dbname</replaceable> ] + </SYNOPSIS> + + <REFSECT2 ID="R2-APP-PGACCESS-1"> + <REFSECT2INFO> + <DATE>1999-05-19</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PGACCESS-2"> + <REFSECT2INFO> + <DATE>1999-05-19</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + </para> + </refsect2> + </refsynopsisdiv> + + <REFSECT1 ID="R1-APP-PGACCESS-1"> + <REFSECT1INFO> + <DATE>1999-05-19</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + </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/pgadmin-ref.sgml b/doc/src/sgml/ref/pgadmin-ref.sgml new file mode 100644 index 00000000000..476923a455d --- /dev/null +++ b/doc/src/sgml/ref/pgadmin-ref.sgml @@ -0,0 +1,74 @@ +<REFENTRY ID="APP-PGADMIN"> + <REFMETA> + <REFENTRYTITLE id="pgadmin-ref"> + <application>pgadmin</application> + </REFENTRYTITLE> + <REFMISCINFO>Application</REFMISCINFO> + </REFMETA> + <REFNAMEDIV> + <REFNAME> + <application>pgadmin</application> + </REFNAME> + <REFPURPOSE> + <productname>Postgres</productname> graphical interactive client + </REFPURPOSE> + </refnamediv> + <REFSYNOPSISDIV> + <REFSYNOPSISDIVINFO> + <DATE>1999-05-19</DATE> + </REFSYNOPSISDIVINFO> + <SYNOPSIS> +pgadmin [ <replaceable class="parameter">dbname</replaceable> ] + </SYNOPSIS> + + <REFSECT2 ID="R2-APP-PGADMIN-1"> + <REFSECT2INFO> + <DATE>1999-05-19</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PGADMIN-2"> + <REFSECT2INFO> + <DATE>1999-05-19</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + </para> + </refsect2> + </refsynopsisdiv> + + <REFSECT1 ID="R1-APP-PGADMIN-1"> + <REFSECT1INFO> + <DATE>1999-05-19</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + </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/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 96860281f94..454e4c0ec4f 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,1063 +1,1111 @@ <REFENTRY ID="APP-PSQL"> -<REFMETA> -<REFENTRYTITLE id="psql-ref"> -<application>psql</application> -</REFENTRYTITLE> -<REFMISCINFO>Application</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME> -<application>psql</application> -</REFNAME> -<REFPURPOSE> -<productname>Postgres</productname> interactive client -</REFPURPOSE> - </refnamediv> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-09-26</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> + <REFMETA> + <REFENTRYTITLE id="psql-ref"> + <application>psql</application> + </REFENTRYTITLE> + <REFMISCINFO>Application</REFMISCINFO> + </REFMETA> + <REFNAMEDIV> + <REFNAME> + <application>psql</application> + </REFNAME> + <REFPURPOSE> + <productname>Postgres</productname> interactive client + </REFPURPOSE> + </refnamediv> + <REFSYNOPSISDIV> + <REFSYNOPSISDIVINFO> + <DATE>1998-09-26</DATE> + </REFSYNOPSISDIVINFO> + <SYNOPSIS> psql [ <replaceable class="parameter">dbname</replaceable> ] psql -A [ -c <replaceable class="parameter">query</replaceable> ] [ -d <replaceable class="parameter">dbname</replaceable> ] -e -E [ -f <replaceable class="parameter">filename</replaceable> ] [ -F <replaceable class="parameter">separator</replaceable> ] [ -h <replaceable class="parameter">hostname</replaceable> ] -Hln [ -o <replaceable class="parameter">filename</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] -qsSt ] [ -T <replaceable class="parameter">table_options</replaceable> ] -ux [ <replaceable class="parameter">dbname</replaceable> ] -</SYNOPSIS> - - <REFSECT2 ID="R2-APP-PSQL-1"> - <REFSECT2INFO> - <DATE>1998-09-26</DATE> - </REFSECT2INFO> - <TITLE> - Inputs - </TITLE> - <PARA> - <application>psql</application> accepts many command-line arguments, - a rich set of meta-commands, and the full <acronym>SQL</acronym> language - supported by <productname>Postgres</productname>. The most common - command-line arguments are: - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE> - </TERM> - <LISTITEM> - <PARA> - The name of an existing database to access. - <replaceable class="parameter">dbname</replaceable> - defaults to the value of the - <envar>USER</envar> - environment variable or, if that's not set, to the Unix account name of the - current user. - - </PARA> - </LISTITEM> - </VARLISTENTRY> + </SYNOPSIS> + + <REFSECT2 ID="R2-APP-PSQL-1"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> + <application>psql</application> accepts many command-line arguments, + a rich set of meta-commands, and the full <acronym>SQL</acronym> language + supported by <productname>Postgres</productname>. The most common + command-line arguments are: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE> + </TERM> + <LISTITEM> + <PARA> + The name of an existing database to access. + <replaceable class="parameter">dbname</replaceable> + defaults to the value of the + <envar>USER</envar> + environment variable or, if that's not set, to the Unix account name of the + current user. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + -c <replaceable class="parameter">query</replaceable> + </TERM> + <LISTITEM> + <PARA> + A single query to run. <application>psql</application> will exit on completion. + </PARA> + </LISTITEM> + </VARLISTENTRY> - <VARLISTENTRY> - <TERM> - -c <replaceable class="parameter">query</replaceable> - </TERM> - <LISTITEM> - <PARA> - A single query to run. <application>psql</application> will exit on completion. - </PARA> - </LISTITEM> - </VARLISTENTRY> + </variablelist> + </para> + <para> + The full set of command-line arguments and meta-commands are described in a subsequent + section. + </para> + <para> + There are some environment variables which can be used in liu of + command line arguments. + Additionally, the <productname>Postgres</productname> frontend library used by + the <application>psql</application> application + looks for other optional environment variables to configure, for example, + the style of date/time representation and the local time zone. Refer + to the chapter on <filename>libpq</filename> in the + <citetitle>Programmer's Guide</citetitle> for more details. + </para> + <para> + You may set any of the following environment variables to avoid + specifying command-line options: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <envar>PGHOST</envar> + </TERM> + <LISTITEM> + <PARA> + The <acronym>DNS</acronym> host name of the database server. + Setting <envar>PGHOST</envar> to a non-zero-length string causes + <acronym>TCP/IP</acronym> communication + to be used, rather than the default local Unix domain sockets. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGPORT</envar> + </TERM> + <LISTITEM> + <PARA> + The port number on which a <productname>Postgres</productname> server is listening. + Defaults to <literal>5432</literal>. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGTTY</envar> + </TERM> + <LISTITEM> + <PARA> + The target for display of messages from the client support library. + Not required. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGOPTION</envar> + </TERM> + <LISTITEM> + <PARA> + If <envar>PGOPTION</envar> + is specified, then the options it contains are parsed + <emphasis>before</emphasis> + any command-line options. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM> + <envar>PGREALM</envar> + </TERM> + <LISTITEM> + <PARA> + <envar>PGREALM</envar> + only applies if + <productname>Kerberos</productname> + authentication is in use. + If this environment variable is set, <productname>Postgres</productname> + will attempt authentication with servers for this realm and will use + separate ticket files to avoid conflicts with local ticket files. + See the <citetitle>PostgreSQL Administrator's Guide</citetitle> + for additional information on + <productname>Kerberos</productname>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PSQL-2"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + <application>psql</application> + returns 0 to the shell on successful completion of all queries, + 1 for errors, 2 for abrupt disconnection from the backend. + The default TAB delimiter is used. + <application>psql</application> + will also return 1 if the connection to a database could not be made for + any reason. + </para> + </refsect2> + </refsynopsisdiv> + + <REFSECT1 ID="R1-APP-PSQL-1"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + <application>psql</application> is a character-based front-end to + <productname>Postgres</productname>. + It enables you to + type in queries interactively, issue them to <productname>Postgres</productname>, + and see the query + results. + </para> + <para> + <application>psql</application> + is a <productname>Postgres</productname> client application. Hence, a + <application>postmaster</application> process + must be running on the database server host before + <application>psql</application> + is executed. In addition, the correct parameters to identify + the database server, such as the + <application>postmaster</application> host name, + may need to be specified + as described below. + </para> + <para> + When + <application>psql</application> + starts, it reads SQL commands from + <filename>/etc/psqlrc</filename> + and then from + <filename>$(<envar>HOME</envar>)/.psqlrc</filename> + This allows SQL commands like + <command>SET</command> + which can be used to set the date style to be run at the start of + every session. + </para> + + <REFSECT2 ID="R2-APP-PSQL-3"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Connecting To A Database + </TITLE> + <para> + <application>psql</application> + attempts to make a connection to the database at the hostname and + port number specified on the command line. If the connection could not + be made for any reason (e.g. insufficient privileges, postmaster is not + running on the server, etc) + .IR <application>psql</application> + will return an error that says + <programlisting> + Connection to database failed. + </programlisting> + The reason for the connection failure is not provided. + </para> + </refsect2> + + <REFSECT2 ID="R2-APP-PSQL-4"> + <REFSECT2INFO> + <DATE>1998-09-26</DATE> + </REFSECT2INFO> + <TITLE> + Entering Queries + </TITLE> + <para> + In normal operation, + <application>psql</application> provides a prompt with the name of the + database that <application>psql</application> is current connected to + followed by the string "=>". + For example, + <programlisting> +$ <userinput>psql testdb</userinput> +Welcome to the POSTGRESQL interactive sql monitor: + Please read the file COPYRIGHT for copyright terms of POSTGRESQL +[PostgreSQL 6.5.0 on i686-pc-linux-gnu, compiled by gcc 2.7.2.3] + + 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: testdb - </variablelist> +testdb=> + </programlisting> + </para> + <para> + At the prompt, the user may type in <acronym>SQL</acronym> queries. + Unless the -S option + is set, input lines are sent to the backend when a query-terminating + semicolon is reached. + </para> + <para> + Whenever a query is executed, + <application>psql</application> also polls for asynchronous notification + events generated by <command>LISTEN</command> and <command>NOTIFY</command>. + </para> + <para> + <application>psql</application> + can be used in a pipe sequence, and automatically detects when it + is not listening or talking to a real tty. + </para> + </refsect2> + + <refsect2 id="R2-APP-PSQL-5"> + <Title>Paging To Screen</Title> + + <Note> + <Title>Author</Title> + <Para> + From Brett McCormick on the mailing list 1998-04-04. + </Para> + </Note> + + <Para> + To affect the paging behavior of your <Command>psql</Command> output, + set or unset your PAGER environment variable. I always have to set mine + before it will pause. And of course you have to do this before + starting the program. + </para> + + <Para> + In csh/tcsh or other C shells: + + <ProgramListing> +% unsetenv PAGER + </ProgramListing> + + while in sh/bash or other Bourne shells: + + <ProgramListing> +% unset PAGER + </ProgramListing> + </para> + </refsect2> + </refsect1> + + <REFSECT1 ID="R1-APP-PSQL-2"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + Command-line Options + </TITLE> + <para> + <application>psql</application> + understands the following command-line options: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + -A + </TERM> + <LISTITEM> + <PARA> + Turn off fill justification when printing out table elements. </para> - <para> - The full set of command-line arguments and meta-commands are described in a subsequent - section. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -c <replaceable class="parameter">query</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies that + <application>psql</application> + is to execute one query string, + <replaceable class="parameter">query</replaceable>, + and then exit. This is useful for shell scripts, typically in + conjunction with the <option>-q</option> option in shell scripts. </para> - <para> - There are some environment variables which can be used in liu of - command line arguments. - Additionally, the <productname>Postgres</productname> frontend library used by - the <application>psql</application> application - looks for other optional environment variables to configure, for example, - the style of date/time representation and the local time zone. Refer - to the chapter on <filename>libpq</filename> in the - <citetitle>Programmer's Guide</citetitle> for more details. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -d <replaceable class="parameter">dbname</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the name of the database to connect to. This is equivalent to specifying + <replaceable class="parameter">dbname</replaceable> as the last field in the + command line. </para> - <para> - You may set any of the following environment variables to avoid - specifying command-line options: - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <envar>PGHOST</envar> - </TERM> - <LISTITEM> - <PARA> - The <acronym>DNS</acronym> host name of the database server. - Setting <envar>PGHOST</envar> to a non-zero-length string causes - <acronym>TCP/IP</acronym> communication - to be used, rather than the default local Unix domain sockets. - </PARA> - </LISTITEM> - </VARLISTENTRY> - - <VARLISTENTRY> - <TERM> - <envar>PGPORT</envar> - </TERM> - <LISTITEM> - <PARA> - The port number on which a <productname>Postgres</productname> server is listening. - Defaults to <literal>5432</literal>. - </PARA> - </LISTITEM> - </VARLISTENTRY> - - <VARLISTENTRY> - <TERM> - <envar>PGTTY</envar> - </TERM> - <LISTITEM> - <PARA> - The target for display of messages from the client support library. - Not required. - </PARA> - </LISTITEM> - </VARLISTENTRY> - - <VARLISTENTRY> - <TERM> - <envar>PGOPTION</envar> - </TERM> - <LISTITEM> - <PARA> - If <envar>PGOPTION</envar> - is specified, then the options it contains are parsed - <emphasis>before</emphasis> - any command-line options. - </PARA> - </LISTITEM> - </VARLISTENTRY> - - <VARLISTENTRY> - <TERM> - <envar>PGREALM</envar> - </TERM> - <LISTITEM> - <PARA> - <envar>PGREALM</envar> - only applies if - <productname>Kerberos</productname> - authentication is in use. - If this environment variable is set, <productname>Postgres</productname> - will attempt authentication with servers for this realm and will use - separate ticket files to avoid conflicts with local ticket files. - See the <citetitle>PostgreSQL Administrator's Guide</citetitle> - for additional information on - <productname>Kerberos</productname>. - </para> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -e + </TERM> + <LISTITEM> + <PARA> + Echo the query sent to the backend </para> - </refsect2> - - <REFSECT2 ID="R2-APP-PSQL-2"> - <REFSECT2INFO> - <DATE>1998-09-26</DATE> - </REFSECT2INFO> - <TITLE> - Outputs - </TITLE> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -E + </TERM> + <LISTITEM> <PARA> - - <application>psql</application> - returns 0 to the shell on successful completion of all queries, - 1 for errors, 2 for abrupt disconnection from the backend. - The default TAB delimiter is used. - <application>psql</application> - will also return 1 if the connection to a database could not be made for - any reason. + Echo the actual query generated by \d and other backslash commands </para> - </refsect2> - </refsynopsisdiv> - - <REFSECT1 ID="R1-APP-PSQL-1"> - <REFSECT1INFO> - <DATE>1998-09-26</DATE> - </REFSECT1INFO> - <TITLE> - Description - </TITLE> - <PARA> - <application>psql</application> is a character-based front-end to - <productname>Postgres</productname>. - It enables you to - type in queries interactively, issue them to <productname>Postgres</productname>, - and see the query - results. - </para> - <para> - <application>psql</application> - is a <productname>Postgres</productname> client application. Hence, a - <application>postmaster</application> process - must be running on the database server host before - <application>psql</application> - is executed. In addition, the correct parameters to identify - the database server, such as the - <application>postmaster</application> host name, - may need to be specified - as described below. - </para> - <para> - When - <application>psql</application> - starts, it reads SQL commands from - <filename>/etc/psqlrc</filename> - and then from - <filename>$(<envar>HOME</envar>)/.psqlrc</filename> - This allows SQL commands like - <command>SET</command> - which can be used to set the date style to be run at the start of - every session. - </para> - - <REFSECT2 ID="R2-APP-PSQL-3"> - <REFSECT2INFO> - <DATE>1998-09-26</DATE> - </REFSECT2INFO> - <TITLE> - Connecting To A Database - </TITLE> - <para> - <application>psql</application> - attempts to make a connection to the database at the hostname and - port number specified on the command line. If the connection could not - be made for any reason (e.g. insufficient privileges, postmaster is not - running on the server, etc) - .IR <application>psql</application> - will return an error that says - <programlisting> - Connection to database failed. - </programlisting> - The reason for the connection failure is not provided. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -f <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Use the file <replaceable class="parameter">filename</replaceable> + as the source of queries instead of reading queries interactively. + This file must be specified for and visible to the client frontend. </para> - </refsect2> - - <REFSECT2 ID="R2-APP-PSQL-4"> - <REFSECT2INFO> - <DATE>1998-09-26</DATE> - </REFSECT2INFO> - <TITLE> - Entering Queries - </TITLE> - <para> - In normal operation, - <application>psql</application> provides a prompt with the name of the - database that <application>psql</application> is current connected to - followed by the string "=>". - For example, - <programlisting> - $ <userinput>psql testdb</userinput> - Welcome to the POSTGRESQL interactive sql monitor: - Please read the file COPYRIGHT for copyright terms of POSTGRESQL - - type \e? for help on slash commands - type \eq to quit - type \eg or terminate with semicolon to execute query - You are currently connected to the database: testdb - - testdb=> - </programlisting> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -F <replaceable class="parameter">separator</replaceable> + </TERM> + <LISTITEM> + <PARA> + Use <replaceable class="parameter">separator</replaceable> + as the field separator. + The default is an ASCII vertical bar ("|"). </para> - <para> - At the prompt, the user may type in <acronym>SQL</acronym> queries. - Unless the -S option - is set, input lines are sent to the backend when a query-terminating - semicolon is reached. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -h <replaceable class="parameter">hostname</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the host name of the machine on which the + <application>postmaster</application> + is running. + Without this option, communication is performed using + local Unix domain sockets. </para> - <para> - Whenever a query is executed, - <application>psql</application> also polls for asynchronous notification - events generated by <command>LISTEN</command> and <command>NOTIFY</command>. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -H + </TERM> + <LISTITEM> + <PARA> + Turns on + <acronym>HTML 3.0</acronym> + tabular output. </para> - <para> - <application>psql</application> - can be used in a pipe sequence, and automatically detects when it - is not listening or talking to a real tty. + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -l + </TERM> + <LISTITEM> + <PARA> + Lists all available databases, then exit. Other non-connection options are ignored. </para> - </refsect2> - </refsect1> - - <REFSECT1 ID="R1-APP-PSQL-2"> - <REFSECT1INFO> - <DATE>1998-09-26</DATE> - </REFSECT1INFO> - <TITLE> - Command-line Options - </TITLE> - <para> - <application>psql</application> - understands the following command-line options: - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - -A - </TERM> - <LISTITEM> - <PARA> - Turn off fill justification when printing out table elements. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -c <replaceable class="parameter">query</replaceable> - </TERM> - <LISTITEM> - <PARA> - Specifies that - <application>psql</application> - is to execute one query string, - <replaceable class="parameter">query</replaceable>, - and then exit. This is useful for shell scripts, typically in - conjunction with the <option>-q</option> option in shell scripts. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -d <replaceable class="parameter">dbname</replaceable> - </TERM> - <LISTITEM> - <PARA> - Specifies the name of the database to connect to. This is equivalent to specifying - <replaceable class="parameter">dbname</replaceable> as the last field in the - command line. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -e - </TERM> - <LISTITEM> - <PARA> - Echo the query sent to the backend - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -E - </TERM> - <LISTITEM> - <PARA> - Echo the actual query generated by \d and other backslash commands - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -f <replaceable class="parameter">filename</replaceable> - </TERM> - <LISTITEM> - <PARA> - Use the file <replaceable class="parameter">filename</replaceable> - as the source of queries instead of reading queries interactively. - This file must be specified for and visible to the client frontend. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -F <replaceable class="parameter">separator</replaceable> - </TERM> - <LISTITEM> - <PARA> - Use <replaceable class="parameter">separator</replaceable> - as the field separator. - The default is an ASCII vertical bar ("|"). - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -h <replaceable class="parameter">hostname</replaceable> - </TERM> - <LISTITEM> - <PARA> - Specifies the host name of the machine on which the - <application>postmaster</application> - is running. - Without this option, communication is performed using - local Unix domain sockets. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -H - </TERM> - <LISTITEM> - <PARA> - Turns on - <acronym>HTML 3.0</acronym> - tabular output. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -l - </TERM> - <LISTITEM> - <PARA> - Lists all available databases, then exit. Other non-connection options are ignored. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -n - </TERM> - <LISTITEM> - <PARA> - Do not use the readline library for input line editing and command history. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -o <replaceable class="parameter">filename</replaceable> - </TERM> - <LISTITEM> - <PARA> - Put all output into file <replaceable class="parameter">filename</replaceable>. - The path must be writable by the client. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -p <replaceable class="parameter">port</replaceable> - </TERM> - <LISTITEM> - <PARA> - Specifies the TCP/IP port or, by omission, the local Unix domain socket file - extension on which the - <application>postmaster</application> - is listening for connections. Defaults to the value of the - <envar>PGPORT</envar> - environment variable, if set, or to 5432. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -q - </TERM> - <LISTITEM> - <PARA> - Specifies that - <application>psql</application> - should do its work quietly. By default, it - prints welcome and exit messages and prompts for each query, and prints - out the number of rows returned from a query. - If this option is used, none of this happens. This is useful with the - <option>-c</option> option. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -s - </TERM> - <LISTITEM> - <PARA> - Run in single-step mode where the user is prompted for each query before - it is sent to the backend. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -S - </TERM> - <LISTITEM> - <PARA> - Runs in single-line mode where each query is terminated by a newline, - instead of a semicolon. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -t - </TERM> - <LISTITEM> - <PARA> - Turn off printing of column names. - This is useful with the - <option>-c</option> - option in shell scripts. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -T <replaceable class="parameter">table_options</replaceable> - </TERM> - <LISTITEM> - <PARA> - Allows you to specify options to be placed within the - <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym> - tabular output.For example, <literal>border</literal> - will give you tables with borders. - This must be used in conjunction with the <option>-H</option> option. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -u - </TERM> - <LISTITEM> - <PARA> - Asks the user for the user name and password before connecting to the database. - If the database does not require password authentication then these are - ignored. If the option is not used (and the PGPASSWORD environment variable - is not set) and the database requires password authentication, then the - connection will fail. The user name is ignored anyway. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - -x - </TERM> - <LISTITEM> - <PARA> - Turns on extended row format mode. When enabled each row will have its column - names printed on the left with the column values printed on the right. - This is useful for rows which are otherwise too long to fit into - one screen line. HTML row output supports this mode also. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - You may set environment variables to avoid typing some of the above - options. See the section on environment variables below. - </para> - </refsect1> - - <REFSECT1 ID="R1-APP-PSQL-3"> - <REFSECT1INFO> - <DATE>1998-09-26</DATE> - </REFSECT1INFO> - <TITLE> - <application>psql</application> Meta-Commands - </TITLE> - <para> - Anything you enter in <application>psql</application> - that begins with an unquoted backslash is a <application>psql</application> - meta-command. Anything else is <acronym>SQL</acronym> - and simply goes into the current query buffer - (and once you have at least one complete query, it gets automatically - submitted to the backend). - <Application>psql</Application> meta-commands are also called slash commands. - </para> - <para> - The format of a <application>psql</application> command is the backslash, - followed immediately by - a command verb, then any arguments. The arguments are separated from the - command verb and each other by any number of white space characters. - </para> - <para> - With single character command verbs, you don't actually need to separate the - command verb from the argument with white space, for historical reasons. - You should anyway. - </para> - <para> - The following meta-commands are defined: - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <literal>\a</literal> - </TERM> - <LISTITEM> - <PARA> - Toggle field alignment when printing out table elements. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\C</literal> <replaceable class="parameter">caption</replaceable> - </TERM> - <LISTITEM> - <PARA> - Set the HTML3.0 table caption to - <quote><replaceable class="parameter">caption</replaceable></quote>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Establish a connection to a new database, using the default - <replaceable class="parameter">username</replaceable> if none is specified. - The previous connection is closed. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable> - </TERM> - <LISTITEM> - <PARA> - Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, - but instead of the backend reading or writing the specified file, and - consequently requiring backend access and special user privilege, - <application>psql</application> reads or writes the - file and routes the data to or from the backend. The default <literal>tab</literal> - delimiter is used. - </para> - <tip> - <para> - This operation is not as efficient as the <acronym>SQL</acronym> - <command>COPY</command> command because all data must pass through the - client/server IP or socket connection. For large amounts of data this other - technique may be preferable. - </para> - </tip> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - List tables in the database, or if <replaceable class="parameter">table</replaceable> - is specified, list the columns in that table. - If table name is specified as an asterisk (<quote>*</quote>), - list all tables and column information for each tables. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\da</literal> - </TERM> - <LISTITEM> - <PARA> - List all available aggregates. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\dd</literal> <replaceable class="parameter">object</replaceable> - </TERM> - <LISTITEM> - <PARA> - List the description from <literal>pg_description</literal> - of the specified object, which can be a - table, table.column, type, operator, or aggregate. - </para> - <tip> - <para> - Not all objects have a description in <literal>pg_description</literal>. - This meta-command can be useful to get a quick description of a native - <productname>Postgres</productname> feature. - </para> - </tip> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\df</literal> - </TERM> - <LISTITEM> - <PARA> - List functions. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\di</literal> - </TERM> - <LISTITEM> - <PARA> - List only indexes. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\do</literal> - </TERM> - <LISTITEM> - <PARA> - List only operators. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\ds</literal> - </TERM> - <LISTITEM> - <PARA> - List only sequences. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\dS</literal> - </TERM> - <LISTITEM> - <PARA> - List system tables and indexes. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\dt</literal> - </TERM> - <LISTITEM> - <PARA> - List only non-system tables. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\dT</literal> - </TERM> - <LISTITEM> - <PARA> - List types. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Edit the current query buffer or the contents of the file - <replaceable class="parameter">filename</replaceable>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Edit the current query buffer or the contents of the file - <replaceable class="parameter">filename</replaceable> - and execute it upon editor exit. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Set the field separator. Default is a single blank space. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] - </TERM> - <LISTITEM> - <PARA> - Send the current query input buffer to the backend and optionally - save the output in <replaceable class="parameter">filename</replaceable> - or pipe the output into a separate Unix shell to execute - <replaceable class="parameter">command</replaceable>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Give syntax help on the specified SQL command. - If <replaceable class="parameter">command</replaceable> is not a defined SQL command - (or is not documented in <application>psql</application>), or if - <replaceable class="parameter">command</replaceable> is not specified, - then <application>psql</application> will - list all the commands for which syntax help is - available. If <replaceable class="parameter">command</replaceable> - is an asterisk (<quote>*</quote>), then - give syntax help on all SQL commands. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\H</literal> - </TERM> - <LISTITEM> - <PARA> - Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option> - command-line option. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\i</literal> <replaceable class="parameter">filename</replaceable> - </TERM> - <LISTITEM> - <PARA> - Read queries from the file <replaceable class="parameter">filename</replaceable> - into the query input buffer. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\l</literal> - </TERM> - <LISTITEM> - <PARA> - List all the databases in the server. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\m</literal> - </TERM> - <LISTITEM> - <PARA> - Toggle the old monitor-like table display, which includes border characters - surrounding the table. - This is standard SQL output. - By default, <application>psql</application> includes only field separators - between columns. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] - </TERM> - <LISTITEM> - <PARA> - Save future query results to the file - <replaceable class="parameter">filename</replaceable> or pipe future - results into a separate Unix shell to execute - <replaceable class="parameter">command</replaceable>. - If no arguments are specified, send query results to - <filename>stdout</filename>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\p</literal> - </TERM> - <LISTITEM> - <PARA> - Print the current query buffer. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\q</literal> - </TERM> - <LISTITEM> - <PARA> - Quit the <application>psql</application> program. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\r</literal> - </TERM> - <LISTITEM> - <PARA> - Reset(clear) the query buffer. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Print or save the command line history to - <replaceable class="parameter">filename</replaceable>. - If <replaceable class="parameter">filename</replaceable> is omitted, - do not save subsequent commands to a history file. - This option is only available if <application>psql</application> is - configured to use readline. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\t</literal> - </TERM> - <LISTITEM> - <PARA> - Toggle display of output column name headings and row count footer (defaults to on). - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\T</literal> <replaceable class="parameter">table_options</replaceable> - </TERM> - <LISTITEM> - <PARA> - Allows you to specify options to be placed within the - <sgmltag>table ...</sgmltag> tag - for <acronym>HTML 3.0</acronym> - tabular output.For example, <literal>border</literal> - will give you tables with borders. - This must be used in conjunction with the <command>\H</command> meta-command. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\x</literal> - </TERM> - <LISTITEM> - <PARA> - Toggles extended row format mode. When enabled each row will have its column - names printed on the left with the column values printed on the right. - This is useful for rows which are otherwise too long to fit into - one screen line. <acronym>HTML</acronym> row output mode supports this flag too. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\w</literal> <replaceable class="parameter">filename</replaceable> - </TERM> - <LISTITEM> - <PARA> - Outputs the current query buffer to the file - <replaceable class="parameter">filename</replaceable>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\z</literal> - </TERM> - <LISTITEM> - <PARA> - Produces a list of all tables in the database with their appropriate ACLs - (grant/revoke permissions) listed. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ] - </TERM> - <LISTITEM> - <PARA> - Escape to a separate Unix shell or execute the Unix command - <replaceable class="parameter">command</replaceable>. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <literal>\?</literal> - </TERM> - <LISTITEM> - <PARA> - Get help information about the slash (<quote>\</quote>) commands. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect1> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -n + </TERM> + <LISTITEM> + <PARA> + Do not use the readline library for input line editing and command history. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -o <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Put all output into file <replaceable class="parameter">filename</replaceable>. + The path must be writable by the client. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -p <replaceable class="parameter">port</replaceable> + </TERM> + <LISTITEM> + <PARA> + Specifies the TCP/IP port or, by omission, the local Unix domain socket file + extension on which the + <application>postmaster</application> + is listening for connections. Defaults to the value of the + <envar>PGPORT</envar> + environment variable, if set, or to 5432. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -q + </TERM> + <LISTITEM> + <PARA> + Specifies that + <application>psql</application> + should do its work quietly. By default, it + prints welcome and exit messages and prompts for each query, and prints + out the number of rows returned from a query. + If this option is used, none of this happens. This is useful with the + <option>-c</option> option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -s + </TERM> + <LISTITEM> + <PARA> + Run in single-step mode where the user is prompted for each query before + it is sent to the backend. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -S + </TERM> + <LISTITEM> + <PARA> + Runs in single-line mode where each query is terminated by a newline, + instead of a semicolon. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -t + </TERM> + <LISTITEM> + <PARA> + Turn off printing of column names. + This is useful with the + <option>-c</option> + option in shell scripts. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -T <replaceable class="parameter">table_options</replaceable> + </TERM> + <LISTITEM> + <PARA> + Allows you to specify options to be placed within the + <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym> + tabular output.For example, <literal>border</literal> + will give you tables with borders. + This must be used in conjunction with the <option>-H</option> option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -u + </TERM> + <LISTITEM> + <PARA> + Asks the user for the user name and password before connecting to the database. + If the database does not require password authentication then these are + ignored. If the option is not used (and the PGPASSWORD environment variable + is not set) and the database requires password authentication, then the + connection will fail. The user name is ignored anyway. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + -x + </TERM> + <LISTITEM> + <PARA> + Turns on extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. HTML row output supports this mode also. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + You may set environment variables to avoid typing some of the above + options. See the section on environment variables below. + </para> + </refsect1> + + <REFSECT1 ID="R1-APP-PSQL-3"> + <REFSECT1INFO> + <DATE>1998-09-26</DATE> + </REFSECT1INFO> + <TITLE> + <application>psql</application> Meta-Commands + </TITLE> + <para> + Anything you enter in <application>psql</application> + that begins with an unquoted backslash is a <application>psql</application> + meta-command. Anything else is <acronym>SQL</acronym> + and simply goes into the current query buffer + (and once you have at least one complete query, it gets automatically + submitted to the backend). + <Application>psql</Application> meta-commands are also called slash commands. + </para> + <para> + The format of a <application>psql</application> command is the backslash, + followed immediately by + a command verb, then any arguments. The arguments are separated from the + command verb and each other by any number of white space characters. + </para> + <para> + With single character command verbs, you don't actually need to separate the + command verb from the argument with white space, for historical reasons. + You should anyway. + </para> + <para> + The following meta-commands are defined: + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <literal>\a</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle field alignment when printing out table elements. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\C</literal> <replaceable class="parameter">caption</replaceable> + </TERM> + <LISTITEM> + <PARA> + Set the HTML3.0 table caption to + <quote><replaceable class="parameter">caption</replaceable></quote>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Establish a connection to a new database, using the default + <replaceable class="parameter">username</replaceable> if none is specified. + The previous connection is closed. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, + but instead of the backend reading or writing the specified file, and + consequently requiring backend access and special user privilege, + <application>psql</application> reads or writes the + file and routes the data to or from the backend. The default <literal>tab</literal> + delimiter is used. + </para> + <tip> + <para> + This operation is not as efficient as the <acronym>SQL</acronym> + <command>COPY</command> command because all data must pass through the + client/server IP or socket connection. For large amounts of data this other + technique may be preferable. + </para> + </tip> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + List tables in the database, or if <replaceable class="parameter">table</replaceable> + is specified, list the columns in that table. + If table name is specified as an asterisk (<quote>*</quote>), + list all tables and column information for each tables. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\da</literal> + </TERM> + <LISTITEM> + <PARA> + List all available aggregates. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dd</literal> <replaceable class="parameter">object</replaceable> + </TERM> + <LISTITEM> + <PARA> + List the description from <literal>pg_description</literal> + of the specified object, which can be a + table, table.column, type, operator, or aggregate. + </para> + <tip> + <para> + Not all objects have a description in <literal>pg_description</literal>. + This meta-command can be useful to get a quick description of a native + <productname>Postgres</productname> feature. + </para> + </tip> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\df</literal> + </TERM> + <LISTITEM> + <PARA> + List functions. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\di</literal> + </TERM> + <LISTITEM> + <PARA> + List only indexes. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\do</literal> + </TERM> + <LISTITEM> + <PARA> + List only operators. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\ds</literal> + </TERM> + <LISTITEM> + <PARA> + List only sequences. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dS</literal> + </TERM> + <LISTITEM> + <PARA> + List system tables and indexes. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dt</literal> + </TERM> + <LISTITEM> + <PARA> + List only non-system tables. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\dT</literal> + </TERM> + <LISTITEM> + <PARA> + List types. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Edit the current query buffer or the contents of the file + <replaceable class="parameter">filename</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Edit the current query buffer or the contents of the file + <replaceable class="parameter">filename</replaceable> + and execute it upon editor exit. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Set the field separator. Default is a single blank space. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] + </TERM> + <LISTITEM> + <PARA> + Send the current query input buffer to the backend and optionally + save the output in <replaceable class="parameter">filename</replaceable> + or pipe the output into a separate Unix shell to execute + <replaceable class="parameter">command</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Give syntax help on the specified SQL command. + If <replaceable class="parameter">command</replaceable> is not a defined SQL command + (or is not documented in <application>psql</application>), or if + <replaceable class="parameter">command</replaceable> is not specified, + then <application>psql</application> will + list all the commands for which syntax help is + available. If <replaceable class="parameter">command</replaceable> + is an asterisk (<quote>*</quote>), then + give syntax help on all SQL commands. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\H</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option> + command-line option. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\i</literal> <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Read queries from the file <replaceable class="parameter">filename</replaceable> + into the query input buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\l</literal> + </TERM> + <LISTITEM> + <PARA> + List all the databases in the server. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\m</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle the old monitor-like table display, which includes border characters + surrounding the table. + This is standard SQL output. + By default, <application>psql</application> includes only field separators + between columns. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ] + </TERM> + <LISTITEM> + <PARA> + Save future query results to the file + <replaceable class="parameter">filename</replaceable> or pipe future + results into a separate Unix shell to execute + <replaceable class="parameter">command</replaceable>. + If no arguments are specified, send query results to + <filename>stdout</filename>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\p</literal> + </TERM> + <LISTITEM> + <PARA> + Print the current query buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\q</literal> + </TERM> + <LISTITEM> + <PARA> + Quit the <application>psql</application> program. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\r</literal> + </TERM> + <LISTITEM> + <PARA> + Reset(clear) the query buffer. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Print or save the command line history to + <replaceable class="parameter">filename</replaceable>. + If <replaceable class="parameter">filename</replaceable> is omitted, + do not save subsequent commands to a history file. + This option is only available if <application>psql</application> is + configured to use readline. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\t</literal> + </TERM> + <LISTITEM> + <PARA> + Toggle display of output column name headings and row count footer (defaults to on). + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\T</literal> <replaceable class="parameter">table_options</replaceable> + </TERM> + <LISTITEM> + <PARA> + Allows you to specify options to be placed within the + <sgmltag>table ...</sgmltag> tag + for <acronym>HTML 3.0</acronym> + tabular output.For example, <literal>border</literal> + will give you tables with borders. + This must be used in conjunction with the <command>\H</command> meta-command. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\x</literal> + </TERM> + <LISTITEM> + <PARA> + Toggles extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. <acronym>HTML</acronym> row output mode supports this flag too. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\w</literal> <replaceable class="parameter">filename</replaceable> + </TERM> + <LISTITEM> + <PARA> + Outputs the current query buffer to the file + <replaceable class="parameter">filename</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\z</literal> + </TERM> + <LISTITEM> + <PARA> + Produces a list of all tables in the database with their appropriate ACLs + (grant/revoke permissions) listed. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ] + </TERM> + <LISTITEM> + <PARA> + Escape to a separate Unix shell or execute the Unix command + <replaceable class="parameter">command</replaceable>. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <literal>\?</literal> + </TERM> + <LISTITEM> + <PARA> + Get help information about the slash (<quote>\</quote>) commands. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> </refentry> + +<!-- 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/set.sgml b/doc/src/sgml/ref/set.sgml index bac4c069148..12c9e47fcc5 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,689 +1,704 @@ <REFENTRY ID="SQL-SET"> -<REFMETA> -<REFENTRYTITLE> -SET -</REFENTRYTITLE> -<REFMISCINFO>SQL - Language Statements</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME> -SET -</REFNAME> -<REFPURPOSE> + <REFMETA> + <REFENTRYTITLE> + SET + </REFENTRYTITLE> + <REFMISCINFO>SQL - Language Statements</REFMISCINFO> + </REFMETA> + <REFNAMEDIV> + <REFNAME> + SET + </REFNAME> + <REFPURPOSE> Set run-time parameters for session -</REFPURPOSE> - </refnamediv> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-09-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -<REPLACEABLE CLASS="PARAMETER"> -</REPLACEABLE> + </REFPURPOSE> + </refnamediv> + <REFSYNOPSISDIV> + <REFSYNOPSISDIVINFO> + <DATE>1998-09-24</DATE> + </REFSYNOPSISDIVINFO> + <SYNOPSIS> SET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> { TO | = } { '<REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>' | DEFAULT } SET TIME ZONE { '<REPLACEABLE CLASS="PARAMETER">timezone</REPLACEABLE>' | LOCAL }; -</SYNOPSIS> + </SYNOPSIS> - <REFSECT2 ID="R2-SQL-SET-1"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - Inputs - </TITLE> - <PARA> + <REFSECT2 ID="R2-SQL-SET-1"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Inputs + </TITLE> + <PARA> - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> - </TERM> - <LISTITEM> - <para> - Settable global parameter. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> - </term> - <listitem> - <PARA> - New value of parameter. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - The possible variables and allowed values are: + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> + </TERM> + <LISTITEM> + <para> + Settable global parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> + </term> + <listitem> + <PARA> + New value of parameter. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The possible variables and allowed values are: - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - DateStyle - </TERM> - <LISTITEM> - <PARA> + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + DateStyle + </TERM> + <LISTITEM> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + ISO + </TERM> + <LISTITEM> + <PARA> + use ISO 8601-style dates and times + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + SQL + </TERM> + <LISTITEM> + <PARA> + use Oracle/Ingres-style dates and times + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + Postgres + </TERM> + <LISTITEM> + <PARA> + use traditional <productname>Postgres</productname> format + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + European + </TERM> + <LISTITEM> + <PARA> + use dd/mm/yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + NonEuropean + </TERM> + <LISTITEM> + <PARA> + use mm/dd/yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + German + </TERM> + <LISTITEM> + <PARA> + use dd.mm.yyyy for numeric date representations. + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + US + </TERM> + <LISTITEM> + <PARA> + same as 'NonEuropean' + </para> + </listitem> + </varlistentry> + <VARLISTENTRY> + <TERM> + default + </TERM> + <LISTITEM> + <PARA> + restores the default values ('US,Postgres') + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Date format initialization my be done by: + <simplelist> + <member> + Setting PGDATESTYLE environment variable. + </member> + <member> + Running postmaster using -oe parameter to set + dates to the 'European' convention. + Note that this affects only the some combinations of date styles; for example + the ISO style is not affected by this parameter. + </member> + <member> + Changing variables in + <filename>src/backend/utils/init/globals.c</filename>. + </member> + </simplelist> + </para> + <para> + The variables in <filename>globals.c</filename> which can be changed are: + <simplelist> + <member> + bool EuroDates = false | true + </member> + <member> + int DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES + </member> + </simplelist> + + </para> + <para> + <variablelist> + <varlistentry> + <term> + TIMEZONE + </term> + <listitem> + <para> + The possible values for timezone depends on your operating + system. For example on Linux /usr/lib/zoneinfo contains the + database of timezones. + </para> + <para> + Here are some valid values for timezone: - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - ISO - </TERM> - <LISTITEM> - <PARA> - use ISO 8601-style dates and times - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - SQL - </TERM> - <LISTITEM> - <PARA> - use Oracle/Ingres-style dates and times - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - Postgres - </TERM> - <LISTITEM> - <PARA> - use traditional <productname>Postgres</productname> format - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - European - </TERM> - <LISTITEM> - <PARA> - use dd/mm/yyyy for numeric date representations. - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - NonEuropean - </TERM> - <LISTITEM> - <PARA> - use mm/dd/yyyy for numeric date representations. - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - German - </TERM> - <LISTITEM> - <PARA> - use dd.mm.yyyy for numeric date representations. - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - US - </TERM> - <LISTITEM> - <PARA> - same as 'NonEuropean' - </para> - </listitem> - </varlistentry> - <VARLISTENTRY> - <TERM> - default - </TERM> - <LISTITEM> - <PARA> - restores the default values ('US,Postgres') - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <variablelist> + <varlistentry> + <term> + 'PST8PDT' + </term> + <listitem> + <para> + set the timezone for California + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + 'Portugal' + </term> + <listitem> + <para> + set time zone for Portugal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + 'Europe/Rome' + </term> + <listitem> + <para> + set time zone for Italy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + set time zone to your local timezone + (value of the TZ environment variable). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + If an invalid time zone is specified, the time zone + becomes GMT (on most systems anyway). + </para> + <para> + A frontend which uses libpq may be initialized by setting the PGTZ + environment variable. + </para> + <para> + The second syntax shown above, allows one to set the timezone + with a syntax similar to SQL92 <command>SET TIME ZONE</command>. + The LOCAL keyword is just an alternate form + of DEFAULT for SQL92 compatibility. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + There are also several internal or optimization + parameters which can be specified + by the <command>SET</command> command: + + <variablelist> + <varlistentry> + <term> + COST_HEAP + </term> + <listitem> + <para> + Sets the default cost of a heap scan for use by the optimizer. + + <variablelist> + <varlistentry> + <term> + <replaceable class="parameter">float4</replaceable> + </term> + <listitem> + <para> + Set the cost of a heap scan to the specified floating point value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> + <para> + Sets the cost of a heap scan to the default value. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The frontend may be initialized by setting the PGCOSTHEAP + environment variable. + </para> + <variablelist> + <varlistentry> + <term> + COST_INDEX + </term> + <listitem> <para> - Date format initialization my be done by: - <simplelist> - <member> - Setting PGDATESTYLE environment variable. - </member> - <member> - Running postmaster using -oe parameter to set - dates to the 'European' convention. - Note that this affects only the some combinations of date styles; for example - the ISO style is not affected by this parameter. - </member> - <member> - Changing variables in - <filename>src/backend/utils/init/globals.c</filename>. - </member> - </simplelist> + Sets the default cost of an index scan for use by the optimizer. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <replaceable class="parameter">float4</replaceable> + </term> + <listitem> <para> - The variables in <filename>globals.c</filename> which can be changed are: - <programlisting> - bool EuroDates = false - true - int DateStyle = USE_ISO_DATES - USE_POSTGRES_DATES - USE_ISO_DATES - USE_SQL_DATES - USE_GERMAN_DATES - </programlisting> + Set the cost of an index scan to the specified floating point value. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> <para> - <variablelist> - <varlistentry> - <term> - TIMEZONE - </term> - <listitem> - <para> - The possible values for timezone depends on your operating - system. For example on Linux /usr/lib/zoneinfo contains the - database of timezones. - </para> - <para> - Here are some valid values for timezone: - - <variablelist> - <varlistentry> - <term> - 'PST8PDT' - </term> - <listitem> - <para> - set the timezone for California - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - 'Portugal' - </term> - <listitem> - <para> - set time zone for Portugal. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - 'Europe/Rome' - </term> - <listitem> - <para> - set time zone for Italy. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - set time zone to your local timezone - (value of the TZ environment variable). - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - If an invalid time zone is specified, the time zone - becomes GMT (on most systems anyway). - </para> - <para> - A frontend which uses libpq may be initialized by setting the PGTZ - environment variable. - </para> - <para> - The second syntax shown above, allows one to set the timezone - with a syntax similar to SQL92 <command>SET TIME ZONE</command>. - The LOCAL keyword is just an alternate form - of DEFAULT for SQL92 compatibility. - </para> - </listitem> - </varlistentry> - </variablelist> + Sets the cost of an index scan to the default value. </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The frontend may be initialized by setting the PGCOSTINDEX + environment variable. + + <variablelist> + <varlistentry> + <term> + GEQO + </term> + <listitem> + <para> + Sets the threshold for using the genetic optimizer algorithm. + </para> + + <variablelist> + <varlistentry> + <term> + On + </term> + <listitem> <para> - There are also several internal or optimization - parameters which can be specified - by the <command>SET</command> command: - - <variablelist> - <varlistentry> - <term> - COST_HEAP - </term> - <listitem> - <para> - Sets the default cost of a heap scan for use by the optimizer. - - <variablelist> - <varlistentry> - <term> - <replaceable class="parameter">float4</replaceable> - </term> - <listitem> - <para> - Set the cost of a heap scan to the specified floating point value. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - Sets the cost of a heap scan to the default value. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - The frontend may be initialized by setting the PGCOSTHEAP - environment variable. - </para> - <variablelist> - <varlistentry> - <term> - COST_INDEX - </term> - <listitem> - <para> - Sets the default cost of an index scan for use by the optimizer. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <replaceable class="parameter">float4</replaceable> - </term> - <listitem> - <para> - Set the cost of an index scan to the specified floating point value. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - Sets the cost of an index scan to the default value. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> + enables the genetic optimizer algorithm + for statements with 6 or more tables. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + On=<replaceable class="parameter">#</replaceable> + </term> + <listitem> <para> - The frontend may be initialized by setting the PGCOSTINDEX - environment variable. - - <variablelist> - <varlistentry> - <term> - GEQO - </term> - <listitem> - <para> - Sets the threshold for using the genetic optimizer algorithm. - </para> - - <variablelist> - <varlistentry> - <term> - On - </term> - <listitem> - <para> - enables the genetic optimizer algorithm - for statements with 6 or more tables. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - On=<replaceable class="parameter">#</replaceable> - </term> - <listitem> - <para> - Takes an integer argument to enable the genetic optimizer algorithm - for statements with <replaceable class="parameter">#</replaceable> - or more tables in the query. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - Off - </term> - <listitem> - <para> - disables the genetic optimizer algorithm. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - Equivalent to specifying <command>SET GEQO='on'</command> - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> + Takes an integer argument to enable the genetic optimizer algorithm + for statements with <replaceable class="parameter">#</replaceable> + or more tables in the query. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Off + </term> + <listitem> <para> - This algorithm is on by default, which used GEQO for - statements of eleven or more tables. - (See the chapter on GEQO in the Programmer's Guide - for more information). + disables the genetic optimizer algorithm. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> <para> - The frontend may be initialized by setting PGGEQO - environment variable. + Equivalent to specifying <command>SET GEQO='on'</command> </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + This algorithm is on by default, which used GEQO for + statements of eleven or more tables. + (See the chapter on GEQO in the Programmer's Guide + for more information). + </para> + <para> + The frontend may be initialized by setting PGGEQO + environment variable. + </para> + <para> + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + + <variablelist> + <varlistentry> + <term> + KSQO + </term> + <listitem> + <para> + <firstterm>Key Set Query Optimizer</firstterm> forces the query optimizer + to optimize repetative OR clauses such as generated by + <productname>MicroSoft Access</productname>: + </para> + + <variablelist> + <varlistentry> + <term> + On + </term> + <listitem> <para> - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. - - <variablelist> - <varlistentry> - <term> - KSQO - </term> - <listitem> - <para> - <firstterm>Key Set Query Optimizer</firstterm> forces the query optimizer - to optimize repetative OR clauses such as generated by - <productname>MicroSoft Access</productname>: - </para> - - <variablelist> - <varlistentry> - <term> - On - </term> - <listitem> - <para> - enables this optimization. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Off - </term> - <listitem> - <para> - disables this optimization. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - Equivalent to specifying <command>SET KSQO='off'</command>. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> + enables this optimization. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Off + </term> + <listitem> <para> - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. + disables this optimization. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DEFAULT + </term> + <listitem> <para> - The frontend may be initialized by setting the PGKSQO - environment variable. - <variablelist> - <varlistentry> - <term> - QUERY_LIMIT - </term> - <listitem> - <para> - Sets the number of rows returned by a query. - </para> - - <variablelist> - <varlistentry> - <term> - Value - </term> - <listitem> - <para> - Maximum number of rows to return for a query. The default is to allow - an unlimited number of rows. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <replaceable class="parameter">#</replaceable> - </term> - <listitem> - <para> - Sets the maximum number of rows returned by a - query to <replaceable class="parameter">#</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - DEFAULT - </term> - <listitem> - <para> - Sets the maximum number of rows returned by a query to be unlimited. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - By default, there is no limit to the number of rows - returned by a query. - </para> - </listitem> - </varlistentry> - </variablelist> + Equivalent to specifying <command>SET KSQO='off'</command>. </para> - </REFSECT2> - - <REFSECT2 ID="R2-SQL-SET-2"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - - <VARIABLELIST> - <VARLISTENTRY> - <TERM> - <returnvalue>SET VARIABLE</returnvalue> - </TERM> - <LISTITEM> - <PARA> - Message returned if successfully. - </para> - </listitem> - </varlistentry> - - <VARLISTENTRY> - <TERM> - <returnvalue>WARN: Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)</returnvalue> - </TERM> - <LISTITEM> - <PARA> - If the command fails to set variable. - </para> - </listitem> - </varlistentry> - - </VARIABLELIST> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + </para> + <para> + The frontend may be initialized by setting the PGKSQO + environment variable. + <variablelist> + <varlistentry> + <term> + QUERY_LIMIT + </term> + <listitem> + <para> + Sets the number of rows returned by a query. + </para> + + <variablelist> + <varlistentry> + <term> + Value + </term> + <listitem> + <para> + Maximum number of rows to return for a query. The default is to allow + an unlimited number of rows. </para> - </REFSECT2> - </REFSYNOPSISDIV> - - <REFSECT1 ID="R1-SQL-SET-1"> - <REFSECT1INFO> - <DATE>1998-09-24</DATE> - </REFSECT1INFO> - <TITLE> - Description - </TITLE> - <PARA> - <command>SET</command> will modify configuration parameters for variable during - a session. - </para> - <para> - Current values can be obtained using <command>SHOW</command>, and values - can be restored to the defaults using <command>RESET</command>. - Parameters and values are case-insensitive. Note that the value - field is always specified as a string, so is enclosed in - single-quotes. - </para> - <para> - <command>SET TIME ZONE</command> changes the session's - default time zone offset. - A SQL-session always begins with an initial default time zone - offset. - The <command>SET TIME ZONE</command> statement is used to change the default - time zone offset for the current SQL session. - </para> - - <REFSECT2 ID="R2-SQL-SET-3"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - Notes - </TITLE> - <PARA> - The <command>SET <replaceable class="parameter">variable</replaceable></command> - statement is a <productname>Postgres</productname> language extension. + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable class="parameter">#</replaceable> + </term> + <listitem> + <para> + Sets the maximum number of rows returned by a + query to <replaceable class="parameter">#</replaceable>. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + DEFAULT + </term> + <listitem> <para> - Refer to <command>SHOW</command> and <command>RESET</command> to - display or reset the current values. + Sets the maximum number of rows returned by a query to be unlimited. </para> - </REFSECT2> - </REFSECT1> - - <REFSECT1 ID="R1-SQL-SET-2"> - <TITLE> - Usage - </TITLE> - <PARA> - </PARA> - <ProgramListing> - --Set the style of date to ISO: - -- - SET DATESTYLE TO 'ISO'; - </programlisting> - <programlisting> - --Enable GEQO for queries with 4 or more tables - -- - SET GEQO ON=4; - </programlisting> - <programlisting> - --Set GEQO to default: - -- - SET GEQO = DEFAULT; - </programlisting> - <programlisting> - --set the timezone for Berkeley, California: - SET TIME ZONE 'PST8PDT'; - - SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 07:41:21-08 - </programlisting> - <programlisting> - --set the timezone for Italy: - SET TIME ZONE 'Europe/Rome'; - - SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 17:41:31+02 - </ProgramListing> - - </REFSECT1> + </listitem> + </varlistentry> + </variablelist> + <para> + By default, there is no limit to the number of rows + returned by a query. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </REFSECT2> + + <REFSECT2 ID="R2-SQL-SET-2"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Outputs + </TITLE> + <PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM> + <returnvalue>SET VARIABLE</returnvalue> + </TERM> + <LISTITEM> + <PARA> + Message returned if successfully. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM> + <returnvalue>WARN: Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)</returnvalue> + </TERM> + <LISTITEM> + <PARA> + If the command fails to set variable. + </para> + </listitem> + </varlistentry> + + </VARIABLELIST> + </para> + </REFSECT2> + </REFSYNOPSISDIV> + + <REFSECT1 ID="R1-SQL-SET-1"> + <REFSECT1INFO> + <DATE>1998-09-24</DATE> + </REFSECT1INFO> + <TITLE> + Description + </TITLE> + <PARA> + <command>SET</command> will modify configuration parameters for variable during + a session. + </para> + <para> + Current values can be obtained using <command>SHOW</command>, and values + can be restored to the defaults using <command>RESET</command>. + Parameters and values are case-insensitive. Note that the value + field is always specified as a string, so is enclosed in + single-quotes. + </para> + <para> + <command>SET TIME ZONE</command> changes the session's + default time zone offset. + A SQL-session always begins with an initial default time zone + offset. + The <command>SET TIME ZONE</command> statement is used to change the default + time zone offset for the current SQL session. + </para> + + <REFSECT2 ID="R2-SQL-SET-3"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + Notes + </TITLE> + <PARA> + The <command>SET <replaceable class="parameter">variable</replaceable></command> + statement is a <productname>Postgres</productname> language extension. + </para> + <para> + Refer to <command>SHOW</command> and <command>RESET</command> to + display or reset the current values. + </para> + </REFSECT2> + </REFSECT1> + + <REFSECT1 ID="R1-SQL-SET-2"> + <TITLE> + Usage + </TITLE> + <PARA> + </PARA> + <ProgramListing> + --Set the style of date to ISO: + -- + SET DATESTYLE TO 'ISO'; + </programlisting> + <programlisting> + --Enable GEQO for queries with 4 or more tables + -- + SET GEQO ON=4; + </programlisting> + <programlisting> + --Set GEQO to default: + -- + SET GEQO = DEFAULT; + </programlisting> + <programlisting> + --set the timezone for Berkeley, California: + SET TIME ZONE 'PST8PDT'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 07:41:21-08 + </programlisting> + <programlisting> + --set the timezone for Italy: + SET TIME ZONE 'Europe/Rome'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 17:41:31+02 + </ProgramListing> + + </REFSECT1> - <REFSECT1 ID="R1-SQL-SET-3"> - <TITLE> - Compatibility - </TITLE> - <PARA> - </PARA> - - <REFSECT2 ID="R2-SQL-SET-4"> - <REFSECT2INFO> - <DATE>1998-09-24</DATE> - </REFSECT2INFO> - <TITLE> - SQL92 - </TITLE> - <PARA> - There is no - <command>SET <replaceable class="parameter">variable</replaceable></command> - in <acronym>SQL92</acronym>. - - The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command> - is slightly different, - allowing only a single integer value for time zone specification: - - <programlisting> - SET TIME ZONE { interval_value_expression | LOCAL } - </programlisting> - </para> - </refsect2> - </refsect1> + <REFSECT1 ID="R1-SQL-SET-3"> + <TITLE> + Compatibility + </TITLE> + <PARA> + </PARA> + + <REFSECT2 ID="R2-SQL-SET-4"> + <REFSECT2INFO> + <DATE>1998-09-24</DATE> + </REFSECT2INFO> + <TITLE> + SQL92 + </TITLE> + <PARA> + There is no + <command>SET <replaceable class="parameter">variable</replaceable></command> + in <acronym>SQL92</acronym>. + + The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command> + is slightly different, + allowing only a single integer value for time zone specification: + + <programlisting> + SET TIME ZONE { interval_value_expression | LOCAL } + </programlisting> + </para> + </refsect2> + </refsect1> </REFENTRY> + +<!-- 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: +--> |