From 06ad580f75dd54db254d9b1a9665975b9a47570c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut <peter_e@gmx.net> Date: Sun, 28 Jul 2002 15:22:21 +0000 Subject: [PATCH] Structure reference pages consistently. Document that structure. Add information about environment variables. --- doc/src/sgml/docguide.sgml | 192 +- doc/src/sgml/ref/createdb.sgml | 115 +- doc/src/sgml/ref/createlang.sgml | 109 +- doc/src/sgml/ref/createuser.sgml | 129 +- doc/src/sgml/ref/dropdb.sgml | 101 +- doc/src/sgml/ref/droplang.sgml | 109 +- doc/src/sgml/ref/dropuser.sgml | 113 +- doc/src/sgml/ref/ecpg-ref.sgml | 115 +- doc/src/sgml/ref/initlocation.sgml | 13 +- doc/src/sgml/ref/pg_ctl-ref.sgml | 49 +- doc/src/sgml/ref/pg_dump.sgml | 30 +- doc/src/sgml/ref/pg_dumpall.sgml | 22 +- doc/src/sgml/ref/pg_restore.sgml | 21 +- doc/src/sgml/ref/postgres-ref.sgml | 24 +- doc/src/sgml/ref/postmaster.sgml | 87 +- doc/src/sgml/ref/psql-ref.sgml | 2971 ++++++++++++++-------------- doc/src/sgml/ref/vacuumdb.sgml | 107 +- 17 files changed, 2449 insertions(+), 1858 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 7df4995cfb..10c0463844 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.41 2002/03/22 19:20:08 petere Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ --> <appendix id="docguide"> <title>Documentation</title> @@ -1254,6 +1254,196 @@ End: </sect1> + + <sect1 id="doc-style"> + <title>Style Guide</title> + + <sect2> + <title>Reference Pages</title> + + <para> + Reference pages should follow a standard layout. This allows + users to find the desired information more quickly, and it also + encourages writers to document all relevant aspects of a command. + Consistency is not only desired among + <productname>PostgreSQL</productname> reference pages, but also + with reference pages provided by the operating system and other + packages. Hence the following guidelines have been developed. + They are for the most part consistent with similar guidelines + established by various operating systems. + </para> + + <para> + Reference pages that describe executable commands should contain + the following sections, in this order. Sections that do not apply + may be omitted. Additional top-level sections should only be used + in special circumstances; often that information belongs in the + <quote>Usage</quote> section. + + <variablelist> + <varlistentry> + <term>Name</term> + <listitem> + <para> + This section is generated automatically. It contains the + command name and a half-sentence summary of its functionality. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Synopsis</term> + <listitem> + <para> + This section contains the syntax diagram of the command. The + synopsis should normally not list each command-line option; + that is done below. Instead, list the major components of the + command line, such as where input and output files go. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Description</term> + <listitem> + <para> + Several paragraphs explaining what the command does. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Options</term> + <listitem> + <para> + A list describing each command-line option. If there are a + lot of options, subsections may be used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Exit Status</term> + <listitem> + <para> + If the program uses 0 for success and non-zero for failure, + then you don't need to document it. If there is a meaning + behind the different non-zero exit codes, list them here. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Usage</term> + <listitem> + <para> + Describe any sublanguage or run-time interface of the program. + If the program is not interactive, this section can usually be + omitted. Otherwise, this section is a catch-all for + describing run-time features. Use subsections if appropriate. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Environment</term> + <listitem> + <para> + List all environment variables that the program might use. + Try to be complete; even seemingly trivial variables like + <envar>SHELL</envar> might be of interest to the user. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Files</term> + <listitem> + <para> + List any files that the program might access implicitly. That + is, do not list input and output files that were specified on + the command line, but list configuration files, etc. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Diagnostics</term> + <listitem> + <para> + Explain any unusual output that the program might create. + Refrain from listing every possible error message. This is a + lot of work and has little use in practice. But if, say, the + error messages have a standard format that the user can parse, + this would be the place to explain it. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Notes</term> + <listitem> + <para> + Anything that doesn't fit elsewhere, but in particular bugs, + implementation flaws, security considerations, compatibility + issues. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Examples</term> + <listitem> + <para> + Examples + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>History</term> + <listitem> + <para> + If there were some major milestones in the history of the + program, they might be listed here. Usually, this section can + be omitted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>See Also</term> + <listitem> + <para> + Cross-references, listed in the following order: other + <productname>PostgreSQL</productname> command reference pages, + <productname>PostgreSQL</productname> SQL command reference + pages, citation of <productname>PostgreSQL</productname> + manuals, other reference pages (e.g., operating system, other + packages), other documentation. Items in the same group are + listed alphabetically. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + Reference pages describing SQL commands should contain the + following sections: Name, Synopsis, Description, Parameters, + Usage, Diagnostics, Notes, Examples, Compatibility, History, See + Also. The Parameters section is like the Options section, but + there is more freedom about which clauses of the command can be + listed. The Compatibility section should explain to what extent + this command conforms to the SQL standard(s), or to which other + database system it is compatible. The See Also section of SQL + commands should list SQL commands before cross-references to + programs. + </para> + </sect2> + + </sect1> </appendix> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 8c3723ca0e..d0849388cd 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.27 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -22,12 +22,42 @@ PostgreSQL documentation <arg><replaceable>dbname</replaceable></arg> <arg><replaceable>description</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-CREATEDB-1"> - <title> - Inputs - </title> - <para> + + <refsect1 id="R1-APP-CREATEDB-1"> + <title> + Description + </title> + <para> + <application>createdb</application> creates a new <productname>PostgreSQL</productname> + database. + </para> + + <para> + Normally, the database user who executes this command becomes the owner of + the new database. + However a different owner can be specified via the <option>-O</option> + option, if the executing user has appropriate privileges. + </para> + + <para> + <application>createdb</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about creating databases via this or other methods. This means + that the <application>psql</application> program must be found by the script and that + a database server must be running at the targeted port. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library will apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -149,6 +179,7 @@ PostgreSQL documentation </variablelist> + <para> The options <option>-h</option>, <option>-p</option>, <option>-U</option>, <option>-W</option>, and <option>-e</option> are passed on literally to <xref linkend="app-psql">. @@ -160,13 +191,12 @@ PostgreSQL documentation endterm="SQL-CREATEDATABASE-title">; see there for more information about them. </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATEDB-2"> - <title> - Outputs - </title> - <para> <variablelist> <varlistentry> <term><computeroutput>CREATE DATABASE</computeroutput></term> @@ -195,45 +225,37 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> + </refsect1> - <refsect1 id="R1-APP-CREATEDB-1"> - <title> - Description - </title> - <para> - <application>createdb</application> creates a new <productname>PostgreSQL</productname> - database. - </para> - <para> - Normally, the database user who executes this command becomes the owner of - the new database. - However a different owner can be specified via the <option>-O</option> - option, if the executing user has appropriate privileges. - </para> + <refsect1> + <title>Environment</title> - <para> - <application>createdb</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about creating databases via this or other methods. This means - that the <application>psql</application> program must be found by the script and that - a database server must be running at the targeted port. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library will apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. <envar>PGUSER</envar> also + determines the name of the database to create, if it is not + specified in the command line. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1 id="R1-APP-CREATEDB-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -262,6 +284,17 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-dropdb"></member> + <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml index 279f967412..7ad26ae82e 100644 --- a/doc/src/sgml/ref/createlang.sgml +++ b/doc/src/sgml/ref/createlang.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.24 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.25 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -11,7 +11,7 @@ PostgreSQL documentation </refmeta> <refnamediv> - <refname id="createlang">createlang</refname> + <refname>createlang</refname> <refpurpose>define a new <productname>PostgreSQL</productname> procedural language</refpurpose> </refnamediv> @@ -27,11 +27,33 @@ PostgreSQL documentation <group choice="plain"><arg>--list</arg><arg>-l</arg></group> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + + <refsect1> + <title>Description</title> + + <para> + <application>createlang</application> is a utility for adding a new + programming language to a <productname>PostgreSQL</productname> database. + <application>createlang</application> can handle all the languages + supplied in the default <productname>PostgreSQL</> distribution, but + not languages provided by other parties. + </para> + <para> + Although backend programming languages can be added directly using + several <acronym>SQL</acronym> commands, it is recommended to use + <application>createlang</application> because it performs a number + of checks and is much easier to use. See + <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> + for more. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-CREATELANG-1"> - <title> - Inputs - </title> <para> <application>createlang</application> accepts the following command line arguments: @@ -138,12 +160,31 @@ PostgreSQL documentation </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATELANG-2"> - <title> - Outputs - </title> <para> Most error messages are self-explanatory. If not, run <application>createlang</application> with the <option>--echo</option> @@ -151,35 +192,12 @@ PostgreSQL documentation for details. Check also under <xref linkend="APP-PSQL"> for more possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-CREATELANG-1"> - <title> - Description - </title> - - <para> - <application>createlang</application> is a utility for adding a new - programming language to a <productname>PostgreSQL</productname> database. - <application>createlang</application> can handle all the languages - supplied in the default <productname>PostgreSQL</> distribution, but - not languages provided by other parties. - </para> - <para> - Although backend programming languages can be added directly using - several <acronym>SQL</acronym> commands, it is recommended to use - <application>createlang</application> because it performs a number - of checks and is much easier to use. See - <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> - for more. - </para> </refsect1> - <refsect1 id="R1-APP-CREATELANG-2"> - <title> - Notes - </title> + + <refsect1> + <title>Notes</title> + <para> Use <xref linkend="app-droplang"> to remove a language. </para> @@ -192,8 +210,9 @@ PostgreSQL documentation </para> </refsect1> - <refsect1 id="R1-APP-CREATELANG-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -205,6 +224,16 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-droplang"></member> + <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index ed92bb2d86..d4be6e7b25 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.25 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.26 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,46 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg><replaceable>username</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + - <refsect2 id="R2-APP-CREATEUSER-1"> - <title> - Inputs - </title> - <para> + <refsect1> + <title>Description</title> + <para> + <application>createuser</application> creates a + new <productname>PostgreSQL</productname> user. + Only superusers (users with <literal>usesuper</literal> set in + the <literal>pg_shadow</literal> table) can create + new <productname>PostgreSQL</productname> users, + so <application>createuser</application> must be + invoked by someone who is a <productname>PostgreSQL</productname> + superuser. + </para> + + <para> + Being a superuser also implies the ability to bypass access permission + checks within the database, so superuser-dom should not be granted lightly. + </para> + + <para> + <application>createuser</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about creating users via this or other methods. This means + that the <application>psql</application> application must be found by the + script and that + a database server must be running at the targeted host. Also, any default + settings and environment variables used by <application>psql</application> + and the <application>libpq</application> front-end library will apply. + </para> + + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -162,6 +196,7 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> You will be prompted for a name and other missing information if it is not specified on the command line. </para> @@ -172,13 +207,31 @@ PostgreSQL documentation <application>psql</application> options <literal>-U</literal> and <literal>-W</literal> are available as well, but their use can be confusing in this context. </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATEUSER-2"> - <title> - Outputs - </title> - <para> <variablelist> <varlistentry> <term><computeroutput>CREATE USER</computeroutput></term> @@ -200,52 +253,16 @@ PostgreSQL documentation </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-CREATEUSER-1"> - <title> - Description - </title> - <para> - <application>createuser</application> creates a - new <productname>PostgreSQL</productname> user. - Only superusers (users with <literal>usesuper</literal> set in - the <literal>pg_shadow</literal> table) can create - new <productname>PostgreSQL</productname> users, - so <application>createuser</application> must be - invoked by someone who is a <productname>PostgreSQL</productname> - superuser. - </para> - - <para> - Being a superuser also implies the ability to bypass access permission - checks within the database, so superuser-dom should not be granted lightly. - </para> - - <para> - <application>createuser</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about creating users via this or other methods. This means - that the <application>psql</application> application must be found by the - script and that - a database server must be running at the targeted host. Also, any default - settings and environment variables used by <application>psql</application> - and the <application>libpq</application> front-end library will apply. - </para> - </refsect1> - <refsect1 id="R1-APP-CREATEUSER-2"> - <title>Usage</title> + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -274,6 +291,16 @@ PostgreSQL documentation </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-dropuser"></member> + <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index ecbfef2b82..e2fd2e3ecc 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,36 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-DROPDB-1"> - <title> - Inputs - </title> - <para> + + <refsect1> + <title>Description</title> + + <para> + <application>dropdb</application> destroys an existing + <productname>PostgreSQL</productname> database. + The user who executes this command must be a database + superuser or the owner of the database. + </para> + + <para> + <application>dropdb</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about dropping databases via this or other methods. This means + that the <application>psql</application> must be found by the script and that + a database server is running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -110,18 +134,16 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> The options <literal>-h</literal>, <literal>-p</literal>, <literal>-U</literal>, <literal>-W</literal>, and <literal>-e</literal> are passed on literally to <xref linkend="APP-PSQL">. </para> - </refsect2> + </refsect1> - <refsect2 id="R2-APP-DROPDB-2"> - <title> - Outputs - </title> - <para> + <refsect1> + <title>Diagnostics</title> <variablelist> <varlistentry> @@ -139,41 +161,35 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> + </refsect1> - <refsect1 id="R1-APP-DROPDB-1"> - <title> - Description - </title> - <para> - <application>dropdb</application> destroys an existing - <productname>PostgreSQL</productname> database. - The user who executes this command must be a database - superuser or the owner of the database. - </para> + <refsect1> + <title>Environment</title> - <para> - <application>dropdb</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about dropping databases via this or other methods. This means - that the <application>psql</application> must be found by the script and that - a database server is running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1 id="R1-APP-DROPDB-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -201,6 +217,17 @@ DROP DATABASE</computeroutput> </para> </informalexample> </refsect1> + + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createdb"></member> + <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml index c6eadb401f..186af6e2a0 100644 --- a/doc/src/sgml/ref/droplang.sgml +++ b/doc/src/sgml/ref/droplang.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -11,7 +11,7 @@ PostgreSQL documentation </refmeta> <refnamediv> - <refname id="droplang">droplang</refname> + <refname>droplang</refname> <refpurpose>remove a <productname>PostgreSQL</productname> procedural language</refpurpose> </refnamediv> @@ -27,11 +27,34 @@ PostgreSQL documentation <group choice="plain"><arg>--list</arg><arg>-l</arg></group> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="R1-APP-DROPLANG-1"> + <title> + Description + </title> + + <para> + <application>droplang</application> is a utility for removing an + existing programming language from a + <productname>PostgreSQL</productname> database. + <application>droplang</application> can drop any procedural language, + even those not supplied by the <productname>PostgreSQL</> distribution. + </para> + <para> + Although backend programming languages can be removed directly using + several <acronym>SQL</acronym> commands, it is recommended to use + <application>droplang</application> because it performs a number + of checks and is much easier to use. See + <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"> + for more. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-DROPLANG-1"> - <title> - Inputs - </title> <para> <application>droplang</application> accepts the following command line arguments: @@ -126,12 +149,31 @@ PostgreSQL documentation </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-DROPLANG-2"> - <title> - Outputs - </title> <para> Most error messages are self-explanatory. If not, run <application>droplang</application> with the <option>--echo</option> @@ -139,43 +181,20 @@ PostgreSQL documentation for details. Check also under <xref linkend="APP-PSQL"> for more possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-DROPLANG-1"> - <title> - Description - </title> - - <para> - <application>droplang</application> is a utility for removing an - existing programming language from a - <productname>PostgreSQL</productname> database. - <application>droplang</application> can drop any procedural language, - even those not supplied by the <productname>PostgreSQL</> distribution. - </para> - <para> - Although backend programming languages can be removed directly using - several <acronym>SQL</acronym> commands, it is recommended to use - <application>droplang</application> because it performs a number - of checks and is much easier to use. See - <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"> - for more. - </para> </refsect1> - <refsect1 id="R1-APP-DROPLANG-2"> - <title> - Notes - </title> + + <refsect1> + <title>Notes</title> <para> Use <xref linkend="app-createlang"> to add a language. </para> </refsect1> - <refsect1 id="R1-APP-DROPLANG-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -186,6 +205,16 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createlang"></member> + <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index 9741d10707..5d45347ee1 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,38 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg><replaceable>username</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-DROPUSER-1"> - <title> - Inputs - </title> - <para> + + <refsect1> + <title>Description</title> + + <para> + <application>dropuser</application> removes an existing + <productname>PostgreSQL</productname> user + <emphasis>and</emphasis> the databases which that user owned. + Only users with <literal>usesuper</literal> set in + the <literal>pg_shadow</literal> table can destroy + <productname>PostgreSQL</productname> users. + </para> + + <para> + <application>dropuser</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about removing users via this or other methods. This means + that the <application>psql</application> must be found by the script and that + a database server is running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -91,7 +117,6 @@ PostgreSQL documentation </listitem> </varlistentry> </variablelist> - </para> <para> The options <literal>-h</literal>, <literal>-p</literal>, and <literal>-e</literal>, @@ -99,14 +124,31 @@ PostgreSQL documentation <application>psql</application> options <literal>-U</literal> and <literal>-W</literal> are available as well, but they can be confusing in this context. </para> - </refsect2> + </refsect1> - <refsect2 id="R2-APP-DROPUSER-2"> - <title> - Outputs - </title> - <para> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> + <variablelist> <varlistentry> <term><computeroutput>DROP USER</computeroutput></term> @@ -128,43 +170,16 @@ PostgreSQL documentation </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-DROPUSER-1"> - <title> - Description - </title> - <para> - <application>dropuser</application> removes an existing - <productname>PostgreSQL</productname> user - <emphasis>and</emphasis> the databases which that user owned. - Only users with <literal>usesuper</literal> set in - the <literal>pg_shadow</literal> table can destroy - <productname>PostgreSQL</productname> users. - </para> - - <para> - <application>dropuser</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about removing users via this or other methods. This means - that the <application>psql</application> must be found by the script and that - a database server is running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> - </refsect1> - <refsect1 id="R1-APP-DROPUSER-2"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -193,6 +208,16 @@ DROP USER</computeroutput> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createuser"></member> + <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index e7e5a4a8a3..44711a8d19 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.19 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.20 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -9,6 +9,7 @@ PostgreSQL documentation <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> + <refnamediv> <refname> <application>ecpg</application> @@ -17,6 +18,7 @@ PostgreSQL documentation embedded SQL C preprocessor </refpurpose> </refnamediv> + <refsynopsisdiv> <refsynopsisdivinfo> <date>1999-07-20</date> @@ -29,14 +31,33 @@ PostgreSQL documentation <arg choice="opt">-o <replaceable>outfile</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="APP-ECPG-description"> + <title>Description</title> + + <para> + <application>ecpg</application> + is an embedded SQL preprocessor for the C language and the + <productname>PostgreSQL</productname>. It + enables development of C programs with embedded SQL code. + </para> + + <para> + Linus Tolke (<email>linus@epact.se</email>) was the + original author of <application>ecpg</application> (up to version 0.2). + Michael Meskes (<email>meskes@debian.org</email>) + is the current author and maintainer of <application>ecpg</application>. + Thomas Good (<email>tomg@q8.nrnet.org</email>) + is the author of the last revision of the <application>ecpg</application> man page, on which + this document is based. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-ECPG-1"> - <refsect2info> - <date>1999-07-20</date> - </refsect2info> - <title> - Inputs - </title> <para> <application>ecpg</application> accepts the following command line arguments: @@ -104,58 +125,23 @@ PostgreSQL documentation </varlistentry> </variablelist> </para> - </refsect2> - - <refsect2 id="R2-APP-ECPG-2"> - <refsect2info> - <date>1998-11-05</date> - </refsect2info> - <title> - Outputs - </title> - <para> - <application>ecpg</application> will create a file or - write to <filename>stdout</filename>. + </refsect1> - <variablelist> - <varlistentry> - <term>Return value</term> - <listitem> - <para> - <application>ecpg</application> returns 0 to the shell on successful completion, non-zero - for errors. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> - </refsynopsisdiv> - <refsect1 id="R1-APP-ECPG-description"> - <title>Description</title> - <para> - <application>ecpg</application> - is an embedded SQL preprocessor for the C language and the - <productname>PostgreSQL</productname>. It - enables development of C programs with embedded SQL code. - </para> + <refsect1> + <title>Exit Status</title> <para> - Linus Tolke (<email>linus@epact.se</email>) was the - original author of <application>ecpg</application> (up to version 0.2). - Michael Meskes (<email>meskes@debian.org</email>) - is the current author and maintainer of <application>ecpg</application>. - Thomas Good (<email>tomg@q8.nrnet.org</email>) - is the author of the last revision of the <application>ecpg</application> man page, on which - this document is based. + <application>ecpg</application> returns 0 to the shell on + successful completion, non-zero for errors. </para> </refsect1> - <refsect1 id="R1-APP-ECPG-2"> + + <refsect1> <title>Usage</title> - <refsect2 id="R2-APP-ECPG-preprocessing"> + <refsect2 id="APP-ECPG-preprocessing"> <title>Preprocessing for Compilation</title> <para> @@ -175,7 +161,7 @@ ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceabl </para> </refsect2> - <refsect2 id="R2-APP-ECPG-compiling"> + <refsect2 id="APP-ECPG-compiling"> <title>Compiling and Linking</title> <para> @@ -190,10 +176,10 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla </refsect2> </refsect1> - <refsect1 id="R1-APP-ECPG-grammar"> + <refsect1 id="APP-ECPG-grammar"> <title>Grammar</title> - <refsect2 id="R2-APP-ECPG-library"> + <refsect2 id="APP-ECPG-library"> <title>Libraries</title> <para> @@ -206,7 +192,7 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla </para> </refsect2> - <refsect2 id="R2-APP-declaration"> + <refsect2 id="APP-ecpg-declaration"> <title>Variable Declaration</title> <para> @@ -237,7 +223,7 @@ char foo[16], bar[16]; </para> </refsect2> - <refsect2 id="R2-APP-ECPG-errors"> + <refsect2 id="APP-ECPG-errors"> <title>Error Handling</title> <para> @@ -292,7 +278,7 @@ EXEC SQL WHENEVER not found sqlprint; </note> </refsect2> - <refsect2 id="R2-APP-ECPG-connecting"> + <refsect2 id="APP-ECPG-connecting"> <title>Connecting to the Database Server</title> <para> @@ -322,7 +308,7 @@ EXEC SQL CONNECT TO <replaceable>dbname</replaceable>; </para> </refsect2> - <refsect2 id="R2-APP-ECPG-queries"> + <refsect2 id="APP-ECPG-queries"> <title>Queries</title> <para> @@ -393,7 +379,7 @@ EXEC SQL COMMIT; </refsect2> </refsect1> - <refsect1 id="R1-APP-ECPG-notes"> + <refsect1 id="APP-ECPG-notes"> <title>Notes</title> <para> The complete structure definition MUST be listed @@ -406,6 +392,17 @@ EXEC SQL COMMIT; </para> </refsect1> + + + <refsect1> + <title>See Also</title> + + <para> + <citetitle>PostgreSQL Programmer's Guide</citetitle> for a more + detailed description of the embedded SQL interface. + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml index 917deadbbe..e37e0a40e1 100644 --- a/doc/src/sgml/ref/initlocation.sgml +++ b/doc/src/sgml/ref/initlocation.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -39,7 +39,7 @@ PostgreSQL documentation </refsect1> <refsect1 id="R1-APP-INITLOCATION-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -68,6 +68,15 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><citetitle>PostgreSQL Administrator's Guide</citetitle></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index da545ab6fe..397098302e 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.14 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.15 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -225,9 +225,32 @@ PostgreSQL documentation </variablelist> </para> </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> - <refsect2> - <title>Files</title> + <variablelist> + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + For others, see <xref linkend="app-postmaster">. + </para> + </refsect1> + + + <refsect1> + <title>Files</title> <para> If the file <filename>postmaster.opts.default</filename> exists in @@ -235,8 +258,17 @@ PostgreSQL documentation options to the <application>postmaster</application>, unless overridden by the <option>-o</option> option. </para> - </refsect2> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + Waiting for complete start is not a well-defined operation and may + fail if access control is set up so that a local client cannot + connect without manual interaction. It should be avoided. + </para> </refsect1> @@ -330,15 +362,6 @@ Command line was: </refsect2> </refsect1> - <refsect1> - <title>Bugs</title> - - <para> - Waiting for complete start is not a well-defined operation and may - fail if access control is set up so that a local client cannot - connect without manual interaction. It should be avoided. - </para> - </refsect1> <refsect1> <title>See Also</title> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index d2ab719fe3..7969489f11 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.45 2002/05/10 22:36:26 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.46 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -582,6 +582,34 @@ PostgreSQL documentation </refsect1> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGDATABASE</envar></term> + + <listitem> + <para> + Database to dump, unless overridden on the command line. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 id="app-pgdump-diagnostics"> <title>Diagnostics</title> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 44e38f28bc..9e5f4452d0 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.28 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -152,6 +152,26 @@ PostgreSQL documentation </refsect2> </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="app-pg-dumpall-ex"> <title>Examples</title> <para> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 0d951621d1..e89d76bbc1 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.28 2002/07/13 00:55:53 momjian Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ --> <refentry id="APP-PGRESTORE"> <docinfo> @@ -496,6 +496,25 @@ </refsect1> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="app-pgrestore-diagnostics"> <title>Diagnostics</title> diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index f78c053320..a242dcc863 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.27 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> @@ -349,6 +349,28 @@ PostgreSQL documentation </refsect2> </refsect1> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + For others, which have little influence during single-user mode, + see <xref linkend="app-postmaster">. + </para> + </refsect1> + <refsect1> <title>Usage</title> diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 0d2a7e93dd..f052e5af6e 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.30 2002/06/15 19:52:56 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.31 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> @@ -338,10 +338,82 @@ PostgreSQL documentation </para> </refsect2> - <refsect2 id="R2-APP-POSTMASTER-2"> - <title> - Outputs - </title> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGCLIENTENCODING</envar></term> + + <listitem> + <para> + Default character encoding used by clients. (The clients may + override this invidiually.) This value can also be set in the + configuration file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATASTYLE</envar></term> + + <listitem> + <para> + Default value of the <literal>datestyle</literal> run-time + parameter. (The use of this environment variable is deprecated.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGPORT</envar></term> + + <listitem> + <para> + Default port (preferrably set in the configuration file) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>TZ</envar></term> + + <listitem> + <para> + Server time zone + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>others</term> + + <listitem> + <para> + Other environment variables may be used to designate alternative + data storage locations. See the <citetitle>Administrator's + Guide</citetitle> for more information. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> <para> <variablelist> @@ -417,7 +489,6 @@ StreamServerPort: cannot bind to port </varlistentry> </variablelist> </para> - </refsect2> </refsect1> <refsect1> @@ -457,8 +528,8 @@ StreamServerPort: cannot bind to port </refsect1> - <refsect1 id="app-postmaster-usage"> - <title>Usage</title> + <refsect1 id="app-postmaster-examples"> + <title>Examples</title> <para> To start <application>postmaster</application> in the background using default values, type: diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 923a874111..b9f8554abf 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,13 +1,9 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.68 2002/07/15 01:56:25 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.69 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> <refentry id="APP-PSQL"> - <docinfo> - <date>2000-12-25</date> - </docinfo> - <refmeta> <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle> <manvolnum>1</manvolnum> @@ -21,19 +17,17 @@ PostgreSQL documentation </refpurpose> </refnamediv> - <refsynopsisdiv> - <refsynopsisdivinfo> - <date>1999-10-26</date> - </refsynopsisdivinfo> - - <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis> + <refsynopsisdiv> + <cmdsynopsis> + <command>psql</command> + <arg><replaceable class="parameter">options</replaceable></arg> + <arg><replaceable class="parameter">dbname</replaceable> + <arg><replaceable class="parameter">user</replaceable></arg></arg> + </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-PSQL-1"> - <refsect2info> - <date>1998-09-26</date> - </refsect2info> - - <title>Summary</title> + <refsect1> + <title>Description</title> <para> <application>psql</application> is a terminal-based front-end to @@ -44,1127 +38,1161 @@ PostgreSQL documentation number of meta-commands and various shell-like features to facilitate writing scripts and automating a wide variety of tasks. </para> + </refsect1> - </refsect2> + <refsect1 id="R1-APP-PSQL-3"> + <title>Options</title> -</refsynopsisdiv> + <para> + If so configured, <application>psql</application> understands both + standard Unix short options, and <acronym>GNU</acronym>-style long + options. The latter are not available on all systems. + </para> -<refsect1 id="R1-APP-PSQL-1"> - <refsect1info> - <date>1998-10-26</date> - </refsect1info> + <variablelist> + <varlistentry> + <term>-a, --echo-all</term> + <listitem> + <para> + Print all the lines to the screen as they are read. This is more + useful for script processing rather than interactive mode. This is + equivalent to setting the variable <envar>ECHO</envar> to + <literal>all</literal>. + </para> + </listitem> + </varlistentry> - <title>Description</title> + <varlistentry> + <term>-A, --no-align</term> + <listitem> + <para> + Switches to unaligned output mode. (The default output mode is + otherwise aligned.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-c, --command <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 in shell scripts. + </para> + <para> + <replaceable class="parameter">query</replaceable> must be either + a query string that is completely parseable by the backend (i.e., + it contains no <application>psql</application> specific features), + or it is a single backslash command. Thus you cannot mix + <acronym>SQL</acronym> and <application>psql</application> + meta-commands. To achieve that, you could pipe the string into + <application>psql</application>, like this: <literal>echo "\x \\ + select * from foo;" | psql</literal>. + </para> + </listitem> + </varlistentry> - <refsect2 id="R2-APP-PSQL-connecting"> - <refsect2info> - <date>2000-01-14</date> - </refsect2info> - - <title>Connecting To A Database</title> + <varlistentry> + <term>-d, --dbname <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 first non-option + argument on the command line. + </para> + </listitem> + </varlistentry> - <para> - <application>psql</application> is a regular - <productname>PostgreSQL</productname> client application. In order - to connect to a database you need to know the name of your target - database, the host name and port number of the server and what user - name you want to connect as. <application>psql</application> can be - told about those parameters via command line options, namely - <option>-d</option>, <option>-h</option>, <option>-p</option>, and - <option>-U</option> respectively. If an argument is found that does - not belong to any option it will be interpreted as the database name - (or the user name, if the database name is also given). Not all - these options are required, defaults do apply. If you omit the host - name psql will connect via a Unix domain socket to a server on the - local host. The default port number is compile-time determined. - Since the database server uses the same default, you will not have - to specify the port in most cases. The default user name is your - Unix user name, as is the default database name. Note that you can't - just connect to any database under any user name. Your database - administrator should have informed you about your access rights. To - save you some typing you can also set the environment variables - <envar>PGDATABASE</envar>, <envar>PGHOST</envar>, - <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate - values. - </para> + <varlistentry> + <term>-e, --echo-queries</term> + <listitem> + <para> + Show all queries that are sent to the backend. This is equivalent + to setting the variable <envar>ECHO</envar> to + <literal>queries</literal>. + </para> + </listitem> + </varlistentry> - <para> - If the connection could not be made for any reason (e.g., insufficient - privileges, postmaster is not running on the server, etc.), - <application>psql</application> will return an error and terminate. - </para> - </refsect2> + <varlistentry> + <term>-E, --echo-hidden</term> + <listitem> + <para> + Echoes the actual queries generated by \d and other backslash + commands. You can use this if you wish to include similar + functionality into your own programs. This is equivalent to + setting the variable <envar>ECHO_HIDDEN</envar> from within + <application>psql</application>. + </para> + </listitem> + </varlistentry> - <refsect2 id="R2-APP-PSQL-4"> - <refsect2info> - <date>1998-09-26</date> - </refsect2info> + <varlistentry> + <term>-f, --file <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. + After the file is processed, <application>psql</application> + terminates. This is in many ways equivalent to the internal + command <command>\i</command>. + </para> - <title>Entering Queries</title> + <para> + If <replaceable>filename</replaceable> is <literal>-</literal> + (hyphen), then standard input is read. + </para> - <para> - In normal operation, <application>psql</application> provides a - prompt with the name of the database to which - <application>psql</application> is currently connected, followed by - the string <literal>=></literal>. For example, -<programlisting> -$ <userinput>psql testdb</userinput> -Welcome to psql, the PostgreSQL interactive terminal. + <para> + Using this option is subtly different from writing <literal>psql + < <replaceable + class="parameter">filename</replaceable></literal>. In general, + both will do what you expect, but using <literal>-f</literal> + enables some nice features such as error messages with line + numbers. There is also a slight chance that using this option will + reduce the start-up overhead. On the other hand, the variant using + the shell's input redirection is (in theory) guaranteed to yield + exactly the same output that you would have gotten had you entered + everything by hand. + </para> + </listitem> + </varlistentry> -Type: \copyright for distribution terms - \h for help with SQL commands - \? for help on internal slash commands - \g or terminate with semicolon to execute query - \q to quit + <varlistentry> + <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term> + <listitem> + <para> + Use <replaceable class="parameter">separator</replaceable> as the + field separator. This is equivalent to <command>\pset + fieldsep</command> or <command>\f</command>. + </para> + </listitem> + </varlistentry> -testdb=> -</programlisting> - </para> + <varlistentry> + <term>-h, --host <replaceable class="parameter">hostname</replaceable></term> + <listitem> + <para> + Specifies the host name of the machine on which the + <application>postmaster</application> is running. If host begins + with a slash, it is used as the directory for the unix domain + socket. + </para> + </listitem> + </varlistentry> - <para> - At the prompt, the user may type in <acronym>SQL</acronym> queries. - Ordinarily, input lines are sent to the backend when a - query-terminating semicolon is reached. An end of line does not - terminate a query! Thus queries can be spread over several lines for - clarity. If the query was sent and without error, the query results - are displayed on the screen. - </para> + <varlistentry> + <term>-H, --html</term> + <listitem> + <para> + Turns on <acronym>HTML</acronym> tabular output. This is + equivalent to <literal>\pset format html</literal> or the + <command>\H</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-l, --list</term> + <listitem> + <para> + Lists all available databases, then exits. Other non-connection + options are ignored. This is similar to the internal command + <command>\list</command>. + </para> + </listitem> + </varlistentry> - <para> - Whenever a query is executed, <application>psql</application> also polls - for asynchronous notification events generated by - <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and - <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">. - </para> - </refsect2> -</refsect1> + <varlistentry> + <term>-o, --output <replaceable class="parameter">filename</replaceable></term> + <listitem> + <para> + Put all query output into file <replaceable + class="parameter">filename</replaceable>. This is equivalent to + the command <command>\o</command>. + </para> + </listitem> + </varlistentry> -<refsect1 id="R1-APP-PSQL-2"> - <refsect1info> - <date>1998-09-26</date> - </refsect1info> + <varlistentry> + <term>-p, --port <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 or, if not set, to the port specified at + compile time, usually 5432. + </para> + </listitem> + </varlistentry> - <title><application>psql</application> Meta-Commands</title> + <varlistentry> + <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term> + <listitem> + <para> + Allows you to specify printing options in the style of + <command>\pset</command> on the command line. Note that here you + have to separate name and value with an equal sign instead of a + space. Thus to set the output format to LaTeX, you could write + <literal>-P format=latex</literal>. + </para> + </listitem> + </varlistentry> - <para> - Anything you enter in <application>psql</application> that begins - with an unquoted backslash is a <application>psql</application> - meta-command that is processed by <application>psql</application> - itself. These commands are what makes - <application>psql</application> interesting for administration or - scripting. Meta-commands are more commonly called slash or backslash - 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 - whitespace characters. - </para> - - <para> - To include whitespace into an argument you must quote it with a - single quote. To include a single quote into such an argument, - precede it by a backslash. Anything contained in single quotes is - furthermore subject to C-like substitutions for - <literal>\n</literal> (new line), <literal>\t</literal> (tab), - <literal>\</literal><replaceable>digits</replaceable>, - <literal>\0</literal><replaceable>digits</replaceable>, and - <literal>\0x</literal><replaceable>digits</replaceable> (the - character with the given decimal, octal, or hexadecimal code). - </para> - - <para> - If an unquoted argument begins with a colon (<literal>:</literal>), - it is taken as a variable and the value of the variable is taken as - the argument instead. - </para> - - <para> - Arguments that are quoted in <quote>backticks</quote> - (<literal>`</literal>) are taken as a command line that is passed to - the shell. The output of the command (with a trailing newline - removed) is taken as the argument value. The above escape sequences - also apply in backticks. - </para> - - <para> - Some commands take the name of an <acronym>SQL</acronym> identifier - (such as a table name) as argument. These arguments follow the - syntax rules of <acronym>SQL</acronym> regarding double quotes: an - identifier without double quotes is coerced to lower-case. For all - other commands double quotes are not special and will become part of - the argument. - </para> - - <para> - Parsing for arguments stops when another unquoted backslash occurs. - This is taken as the beginning of a new meta-command. The special - sequence <literal>\\</literal> (two backslashes) marks the end of - arguments and continues parsing <acronym>SQL</acronym> queries, if - any. That way <acronym>SQL</acronym> and - <application>psql</application> commands can be freely mixed on a - line. But in any case, the arguments of a meta-command cannot - continue beyond the end of the line. - </para> - - <para> - The following meta-commands are defined: + <varlistentry> + <term>-q</term> + <listitem> + <para> + Specifies that <application>psql</application> should do its work + quietly. By default, it prints welcome messages and various + informational output. If this option is used, none of this + happens. This is useful with the <option>-c</option> option. + Within <application>psql</application> you can also set the + <envar>QUIET</envar> variable to achieve the same effect. + </para> + </listitem> + </varlistentry> - <variablelist> - <varlistentry> - <term><literal>\a</literal></term> - <listitem> - <para> - If the current table output format is unaligned, switch to aligned. - If it is not unaligned, set it to unaligned. This command is - kept for backwards compatibility. See <command>\pset</command> for a - general solution. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term> + <listitem> + <para> + Use <replaceable class="parameter">separator</replaceable> as the + record separator. This is equivalent to the <command>\pset + recordsep</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-s, --single-step</term> + <listitem> + <para> + Run in single-step mode. That means the user is prompted before + each query is sent to the backend, with the option to cancel + execution as well. Use this to debug scripts. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term> - <listitem> - <para> - Change the current working directory to - <replaceable>directory</replaceable>. Without argument, change - to the current user's home directory. - </para> + <varlistentry> + <term>-S, --single-line</term> + <listitem> + <para> + Runs in single-line mode where a newline terminates a query, as a + semicolon does. + </para> - <tip> - <para> - To print your current working directory, use <literal>\!pwd</literal>. - </para> - </tip> - </listitem> - </varlistentry> + <note> + <para> + This mode is provided for those who insist on it, but you are not + necessarily encouraged to use it. In particular, if you mix + <acronym>SQL</acronym> and meta-commands on a line the order of + execution might not always be clear to the inexperienced user. + </para> + </note> + </listitem> + </varlistentry> - <varlistentry> - <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term> - <listitem> - <para> - Set the title of any tables being printed as the result of a - query or unset any such title. This command is equivalent to - <literal>\pset title <replaceable - class="parameter">title</replaceable></literal>. (The name of - this command derives from <quote>caption</quote>, as it was - previously only used to set the caption in an - <acronym>HTML</acronym> table.) - </para> - </listitem> - </varlistentry> + <varlistentry> + <term>-t, --tuples-only</term> + <listitem> + <para> + Turn off printing of column names and result row count footers, + etc. It is completely equivalent to the <command>\t</command> + meta-command. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term> - <listitem> - <para> - Establishes a connection to a new database and/or under a user - name. The previous connection is closed. If <replaceable - class="parameter">dbname</replaceable> is <literal>-</literal> - the current database name is assumed. - </para> + <varlistentry> + <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term> + <listitem> + <para> + Allows you to specify options to be placed within the + <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See + <command>\pset</command> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-u</term> + <listitem> + <para> + Makes <application>psql</application> prompt for the user name and + password before connecting to the database. + </para> - <para> - If <replaceable class="parameter">username</replaceable> is - omitted the current user name is assumed. </para> + <para> + This option is deprecated, as it is conceptually flawed. + (Prompting for a non-default user name and prompting for a + password because the backend requires it are really two different + things.) You are encouraged to look at the <option>-U</option> and + <option>-W</option> options instead. + </para> + </listitem> + </varlistentry> - <para> - As a special rule, <command>\connect</command> without any - arguments will connect to the default database as the default - user (as you would have gotten by starting - <application>psql</application> without any arguments). - </para> + <varlistentry> + <term>-U, --username <replaceable class="parameter">username</replaceable></term> + <listitem> + <para> + Connects to the database as the user <replaceable + class="parameter">username</replaceable> instead of the default. + (You must have permission to do so, of course.) + </para> + </listitem> + </varlistentry> - <para> - If the connection attempt failed (wrong user name, access - denied, etc.), the previous connection will be kept if and only - if <application>psql</application> is in interactive mode. When - executing a non-interactive script, processing will immediately - stop with an error. This distinction was chosen as a user - convenience against typos on the one hand, and a safety - mechanism that scripts are not accidentally acting on the wrong - database on the other hand. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term> + <listitem> + <para> + Performs a variable assignment, like the <command>\set</command> + internal command. Note that you must separate name and value, if + any, by an equal sign on the command line. To unset a variable, + leave off the equal sign. To just set a variable without a value, + use the equal sign but leave off the value. These assignments are + done during a very early stage of start-up, so variables reserved + for internal purposes might get overwritten later. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable> - { <literal>from</literal> | <literal>to</literal> } - <replaceable class="parameter">filename</replaceable> | stdin | stdout - [ <literal>with</literal> ] - [ <literal>oids</literal> ] - [ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ] - [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ] - </term> + <varlistentry> + <term>-V, --version</term> + <listitem> + <para> + Shows the <application>psql</application> version. + </para> + </listitem> + </varlistentry> - <listitem> - <para> - Performs a frontend (client) copy. This is an operation that - runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY" - endterm="SQL-COPY-title"> command, but instead of the backend's - reading or writing the specified file, and consequently - requiring backend access and special user privilege, as well as - being bound to the file system accessible by the backend, - <application>psql</application> reads or writes the file and - routes the data between the backend and the local file system. - </para> + <varlistentry> + <term>-W, --password</term> + <listitem> + <para> + Requests that <application>psql</application> should prompt for a + password before connecting to a database. This will remain set for + the entire session, even if you change the database connection + with the meta-command <command>\connect</command>. + </para> - <para> - The syntax of the command is similar to that of the - <acronym>SQL</acronym> <command>COPY</command> command (see its - description for the details). Note that, because of this, - special parsing rules apply to the <command>\copy</command> - command. In particular, the variable substitution rules and - backslash escapes do not apply. - </para> + <para> + In the current version, <application>psql</application> + automatically issues a password prompt whenever the backend + requests password authentication. Because this is currently based + on a hack, the automatic recognition might mysteriously fail, + hence this option to force a prompt. If no password prompt is + issued and the backend requires password authentication the + connection attempt will fail. + </para> + </listitem> + </varlistentry> - <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 the other technique may be preferable. - </para> - </tip> + <varlistentry> + <term>-x, --expanded</term> + <listitem> + <para> + Turns on extended row format mode. This is equivalent to the + command <command>\x</command>. + </para> + </listitem> + </varlistentry> - <note> - <para> - Note the difference in interpretation of - <literal>stdin</literal> and <literal>stdout</literal> between - frontend and backend copies: in a frontend copy these always - refer to <application>psql</application>'s input and output - stream. On a backend copy <literal>stdin</literal> comes from - wherever the <command>COPY</command> itself came from (for - example, a script run with the <option>-f</option> option), and - <literal>stdout</literal> refers to the query output stream (see - <command>\o</command> meta-command below). - </para> - </note> - </listitem> - </varlistentry> + <varlistentry> + <term>-X, --no-psqlrc</term> + <listitem> + <para> + Do not read the start-up file <filename>~/.psqlrc</filename>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term><literal>\copyright</literal></term> - <listitem> - <para> - Shows the copyright and distribution terms of - <application>PostgreSQL</application>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Shows help about <application>psql</application> command line + arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> - <varlistentry> - <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term> - <listitem> - <para> - Shows all columns of <replaceable - class="parameter">relation</replaceable> (which could be a - table, view, index, or sequence), their types, and any special - attributes such as <literal>NOT NULL</literal> or defaults, if - any. If the relation is, in fact, a table, any defined indices, - primary keys, unique constraints and check constraints are also - listed. If the relation is a view, the view definition is also - shown. - </para> + <refsect1> + <title>Exit Status</title> - <para> - The command form <literal>\d+</literal> is identical, but any - comments associated with the table columns are shown as well. - </para> + <para> + <application>psql</application> returns 0 to the shell if it + finished normally, 1 if a fatal error of its own (out of memory, + file not found) occurs, 2 if the connection to the backend went bad + and the session is not interactive, and 3 if an error occurred in a + script and the variable <envar>ON_ERROR_STOP</envar> was set. + </para> + </refsect1> - <note> - <para> - If <command>\d</command> is called without any arguments, it is - equivalent to <command>\dtvs</command> which will show a list of - all tables, views, and sequences. This is purely a convenience - measure. - </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> + <refsect1> + <title>Usage</title> - <listitem> - <para> - Lists all available aggregate functions, together with the data - type they operate on. If <replaceable - class="parameter">pattern</replaceable> (a regular expression) - is specified, only matching aggregates are shown. - </para> - </listitem> - </varlistentry> + <refsect2 id="R2-APP-PSQL-connecting"> + <title>Connecting To A Database</title> - <varlistentry> - <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term> - <listitem> - <para> - Shows the descriptions of <replaceable - class="parameter">object</replaceable> (which can be a regular - expression), or of all objects if no argument is given. - (<quote>Object</quote> covers aggregates, functions, operators, - types, relations (tables, views, indexes, sequences, large - objects), rules, and triggers.) For example: -<programlisting> -=> <userinput>\dd version</userinput> - Object descriptions - Name | What | Description ----------+----------+--------------------------- - version | function | PostgreSQL version string -(1 row) -</programlisting> - </para> + <para> + <application>psql</application> is a regular + <productname>PostgreSQL</productname> client application. In order + to connect to a database you need to know the name of your target + database, the host name and port number of the server and what user + name you want to connect as. <application>psql</application> can be + told about those parameters via command line options, namely + <option>-d</option>, <option>-h</option>, <option>-p</option>, and + <option>-U</option> respectively. If an argument is found that does + not belong to any option it will be interpreted as the database name + (or the user name, if the database name is also given). Not all + these options are required, defaults do apply. If you omit the host + name psql will connect via a Unix domain socket to a server on the + local host. The default port number is compile-time determined. + Since the database server uses the same default, you will not have + to specify the port in most cases. The default user name is your + Unix user name, as is the default database name. Note that you can't + just connect to any database under any user name. Your database + administrator should have informed you about your access rights. To + save you some typing you can also set the environment variables + <envar>PGDATABASE</envar>, <envar>PGHOST</envar>, + <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate + values. + </para> - <para> - Descriptions for objects can be generated with the - <command>COMMENT ON</command> <acronym>SQL</acronym> command. - </para> + <para> + If the connection could not be made for any reason (e.g., insufficient + privileges, postmaster is not running on the server, etc.), + <application>psql</application> will return an error and terminate. + </para> + </refsect2> - <note> - <para> - <productname>PostgreSQL</productname> stores the object - descriptions in the pg_description system table. - </para> - </note> + <refsect2 id="R2-APP-PSQL-4"> + <title>Entering Queries</title> - </listitem> - </varlistentry> + <para> + In normal operation, <application>psql</application> provides a + prompt with the name of the database to which + <application>psql</application> is currently connected, followed by + the string <literal>=></literal>. For example, +<programlisting> +$ <userinput>psql testdb</userinput> +Welcome to psql, the PostgreSQL interactive terminal. +Type: \copyright for distribution terms + \h for help with SQL commands + \? for help on internal slash commands + \g or terminate with semicolon to execute query + \q to quit - <varlistentry> - <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> - <listitem> - <para> - Lists all available domains (derived types). If <replaceable - class="parameter">pattern</replaceable> (a regular expression) - is specified, only matching domains are shown. - </para> - </listitem> - </varlistentry> +testdb=> +</programlisting> + </para> + <para> + At the prompt, the user may type in <acronym>SQL</acronym> queries. + Ordinarily, input lines are sent to the backend when a + query-terminating semicolon is reached. An end of line does not + terminate a query! Thus queries can be spread over several lines for + clarity. If the query was sent and without error, the query results + are displayed on the screen. + </para> - <varlistentry> - <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> + <para> + Whenever a query is executed, <application>psql</application> also polls + for asynchronous notification events generated by + <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and + <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">. + </para> + </refsect2> - <listitem> - <para> - Lists available functions, together with their argument and - return types. If <replaceable - class="parameter">pattern</replaceable> (a regular expression) - is specified, only matching functions are shown. If the form - <literal>\df+</literal> is used, additional information about - each function, including language and description, is shown. - </para> - </listitem> - </varlistentry> + <refsect2> + <title>Meta-Commands</title> + <para> + Anything you enter in <application>psql</application> that begins + with an unquoted backslash is a <application>psql</application> + meta-command that is processed by <application>psql</application> + itself. These commands are what makes + <application>psql</application> interesting for administration or + scripting. Meta-commands are more commonly called slash or backslash + commands. + </para> - <varlistentry> - <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> + <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 + whitespace characters. + </para> - <listitem> - <para> - This is not the actual command name: The letters i, s, t, v, S - stand for index, sequence, table, view, and system table, - respectively. You can specify any or all of them in any order to - obtain a listing of them, together with who the owner is. - </para> + <para> + To include whitespace into an argument you must quote it with a + single quote. To include a single quote into such an argument, + precede it by a backslash. Anything contained in single quotes is + furthermore subject to C-like substitutions for + <literal>\n</literal> (new line), <literal>\t</literal> (tab), + <literal>\</literal><replaceable>digits</replaceable>, + <literal>\0</literal><replaceable>digits</replaceable>, and + <literal>\0x</literal><replaceable>digits</replaceable> (the + character with the given decimal, octal, or hexadecimal code). + </para> - <para> - If <replaceable class="parameter">pattern</replaceable> is - specified, it is a regular expression that restricts the listing - to those objects whose name matches. If one appends a - <quote>+</quote> to the command name, each object is listed with - its associated description, if any. - </para> - </listitem> - </varlistentry> + <para> + If an unquoted argument begins with a colon (<literal>:</literal>), + it is taken as a variable and the value of the variable is taken as + the argument instead. + </para> + + <para> + Arguments that are quoted in <quote>backticks</quote> + (<literal>`</literal>) are taken as a command line that is passed to + the shell. The output of the command (with a trailing newline + removed) is taken as the argument value. The above escape sequences + also apply in backticks. + </para> + <para> + Some commands take the name of an <acronym>SQL</acronym> identifier + (such as a table name) as argument. These arguments follow the + syntax rules of <acronym>SQL</acronym> regarding double quotes: an + identifier without double quotes is coerced to lower-case. For all + other commands double quotes are not special and will become part of + the argument. + </para> - <varlistentry> - <term><literal>\dl</literal></term> - <listitem> - <para> - This is an alias for <command>\lo_list</command>, which shows a - list of large objects. - </para> - </listitem> - </varlistentry> + <para> + Parsing for arguments stops when another unquoted backslash occurs. + This is taken as the beginning of a new meta-command. The special + sequence <literal>\\</literal> (two backslashes) marks the end of + arguments and continues parsing <acronym>SQL</acronym> queries, if + any. That way <acronym>SQL</acronym> and + <application>psql</application> commands can be freely mixed on a + line. But in any case, the arguments of a meta-command cannot + continue beyond the end of the line. + </para> + <para> + The following meta-commands are defined: + <variablelist> <varlistentry> - <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term> + <term><literal>\a</literal></term> <listitem> <para> - Lists available operators with their operand and return types. - If <replaceable class="parameter">name</replaceable> is - specified, only operators with that name will be shown. + If the current table output format is unaligned, switch to aligned. + If it is not unaligned, set it to unaligned. This command is + kept for backwards compatibility. See <command>\pset</command> for a + general solution. </para> </listitem> </varlistentry> - - <varlistentry> - <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> - <listitem> - <para> - This is an alias for <command>\z</command> which was included - for its greater mnemonic value (<quote>display - permissions</quote>). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> - <listitem> + <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term> + <listitem> <para> - Lists all data types or only those that match <replaceable - class="parameter">pattern</replaceable>. The command form - <literal>\dT+</literal> shows extra information. + Change the current working directory to + <replaceable>directory</replaceable>. Without argument, change + to the current user's home directory. </para> - </listitem> - </varlistentry> + <tip> + <para> + To print your current working directory, use <literal>\!pwd</literal>. + </para> + </tip> + </listitem> + </varlistentry> <varlistentry> - <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> + <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term> <listitem> <para> - Lists all configured users or only those that match <replaceable - class="parameter">pattern</replaceable>. + Set the title of any tables being printed as the result of a + query or unset any such title. This command is equivalent to + <literal>\pset title <replaceable + class="parameter">title</replaceable></literal>. (The name of + this command derives from <quote>caption</quote>, as it was + previously only used to set the caption in an + <acronym>HTML</acronym> table.) </para> </listitem> </varlistentry> - <varlistentry> - <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term> - + <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term> <listitem> <para> - If <replaceable class="parameter">filename</replaceable> is - specified, the file is edited; after the editor exits, its - content is copied back to the query buffer. If no argument is - given, the current query buffer is copied to a temporary file - which is then edited in the same fashion. - </para> - - <para> - The new query buffer is then re-parsed according to the normal - rules of <application>psql</application>, where the whole buffer - is treated as a single line. (Thus you cannot make scripts this - way. Use <command>\i</command> for that.) This means also that - if the query ends with (or rather contains) a semicolon, it is - immediately executed. In other cases it will merely wait in the - query buffer. - </para> - - <tip> - <para> - <application>psql</application> searches the environment - variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and - <envar>VISUAL</envar> (in that order) for an editor to use. If - all of them are unset, <filename>/bin/vi</filename> is run. - </para> - </tip> - </listitem> - </varlistentry> + Establishes a connection to a new database and/or under a user + name. The previous connection is closed. If <replaceable + class="parameter">dbname</replaceable> is <literal>-</literal> + the current database name is assumed. + </para> + <para> + If <replaceable class="parameter">username</replaceable> is + omitted the current user name is assumed. </para> - <varlistentry> - <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term> - <listitem> <para> - Prints the arguments to the standard output, separated by one - space and followed by a newline. This can be useful to - intersperse information in the output of scripts. For example: -<programlisting> -=> <userinput>\echo `date`</userinput> -Tue Oct 26 21:40:57 CEST 1999 -</programlisting> - If the first argument is an unquoted <literal>-n</literal> the the trailing - newline is not written. + As a special rule, <command>\connect</command> without any + arguments will connect to the default database as the default + user (as you would have gotten by starting + <application>psql</application> without any arguments). </para> - <tip> <para> - If you use the <command>\o</command> command to redirect your - query output you may wish to use <command>\qecho</command> - instead of this command. + If the connection attempt failed (wrong user name, access + denied, etc.), the previous connection will be kept if and only + if <application>psql</application> is in interactive mode. When + executing a non-interactive script, processing will immediately + stop with an error. This distinction was chosen as a user + convenience against typos on the one hand, and a safety + mechanism that scripts are not accidentally acting on the wrong + database on the other hand. </para> - </tip> - </listitem> + </listitem> </varlistentry> - <varlistentry> - <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term> + <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable> + { <literal>from</literal> | <literal>to</literal> } + <replaceable class="parameter">filename</replaceable> | stdin | stdout + [ <literal>with</literal> ] + [ <literal>oids</literal> ] + [ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ] + [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ] + </term> <listitem> <para> - Sets the client encoding, if you are using multibyte encodings. - Without an argument, this command shows the current encoding. - </para> - </listitem> - </varlistentry> + Performs a frontend (client) copy. This is an operation that + runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY" + endterm="SQL-COPY-title"> command, but instead of the backend's + reading or writing the specified file, and consequently + requiring backend access and special user privilege, as well as + being bound to the file system accessible by the backend, + <application>psql</application> reads or writes the file and + routes the data between the backend and the local file system. + </para> + <para> + The syntax of the command is similar to that of the + <acronym>SQL</acronym> <command>COPY</command> command (see its + description for the details). Note that, because of this, + special parsing rules apply to the <command>\copy</command> + command. In particular, the variable substitution rules and + backslash escapes do not apply. + </para> - <varlistentry> - <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term> + <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 the other technique may be preferable. + </para> + </tip> - <listitem> + <note> <para> - Sets the field separator for unaligned query output. The default - is pipe (<literal>|</literal>). See also - <command>\pset</command> for a generic way of setting output - options. + Note the difference in interpretation of + <literal>stdin</literal> and <literal>stdout</literal> between + frontend and backend copies: in a frontend copy these always + refer to <application>psql</application>'s input and output + stream. On a backend copy <literal>stdin</literal> comes from + wherever the <command>COPY</command> itself came from (for + example, a script run with the <option>-f</option> option), and + <literal>stdout</literal> refers to the query output stream (see + <command>\o</command> meta-command below). </para> + </note> </listitem> </varlistentry> - <varlistentry> - <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term> - + <term><literal>\copyright</literal></term> <listitem> <para> - Sends the current query input buffer to the backend and - optionally saves the output in <replaceable - class="parameter">filename</replaceable> or pipes the output - into a separate Unix shell to execute <replaceable - class="parameter">command</replaceable>. A bare - <literal>\g</literal> is virtually equivalent to a semicolon. A - <literal>\g</literal> with argument is a <quote>one-shot</quote> - alternative to the <command>\o</command> command. + Shows the copyright and distribution terms of + <application>PostgreSQL</application>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term> + <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term> + <listitem> <para> - Give syntax help on the specified <acronym>SQL</acronym> - command. 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 syntax help on all - <acronym>SQL</acronym> commands is shown. - </para> + Shows all columns of <replaceable + class="parameter">relation</replaceable> (which could be a + table, view, index, or sequence), their types, and any special + attributes such as <literal>NOT NULL</literal> or defaults, if + any. If the relation is, in fact, a table, any defined indices, + primary keys, unique constraints and check constraints are also + listed. If the relation is a view, the view definition is also + shown. + </para> + + <para> + The command form <literal>\d+</literal> is identical, but any + comments associated with the table columns are shown as well. + </para> <note> <para> - To simplify typing, commands that consists of several words do - not have to be quoted. Thus it is fine to type <userinput>\help - alter table</userinput>. + If <command>\d</command> is called without any arguments, it is + equivalent to <command>\dtvs</command> which will show a list of + all tables, views, and sequences. This is purely a convenience + measure. </para> - </note> - </listitem> + </note> + </listitem> </varlistentry> - <varlistentry> - <term><literal>\H</literal></term> + <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> + <listitem> <para> - Turns on <acronym>HTML</acronym> query output format. If the - <acronym>HTML</acronym> format is already on, it is switched - back to the default aligned text format. This command is for - compatibility and convenience, but see <command>\pset</command> - about setting other output options. + Lists all available aggregate functions, together with the data + type they operate on. If <replaceable + class="parameter">pattern</replaceable> (a regular expression) + is specified, only matching aggregates are shown. </para> </listitem> </varlistentry> - <varlistentry> - <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term> + <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term> <listitem> <para> - Reads input from the file <replaceable - class="parameter">filename</replaceable> and executes it as - though it had been typed on the keyboard. + Shows the descriptions of <replaceable + class="parameter">object</replaceable> (which can be a regular + expression), or of all objects if no argument is given. + (<quote>Object</quote> covers aggregates, functions, operators, + types, relations (tables, views, indexes, sequences, large + objects), rules, and triggers.) For example: +<programlisting> +=> <userinput>\dd version</userinput> + Object descriptions + Name | What | Description +---------+----------+--------------------------- + version | function | PostgreSQL version string +(1 row) +</programlisting> </para> - <note> - <para> - If you want to see the lines on the screen as they are read you - must set the variable <envar>ECHO</envar> to - <literal>all</literal>. + + <para> + Descriptions for objects can be generated with the + <command>COMMENT ON</command> <acronym>SQL</acronym> command. </para> - </note> + + <note> + <para> + <productname>PostgreSQL</productname> stores the object + descriptions in the pg_description system table. + </para> + </note> + </listitem> </varlistentry> <varlistentry> - <term><literal>\l</literal> (or <literal>\list</literal>)</term> + <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> <listitem> <para> - List all the databases in the server as well as their owners. - Append a <quote>+</quote> to the command name to see any - descriptions for the databases as well. If your - <productname>PostgreSQL</productname> installation was compiled - with multibyte encoding support, the encoding scheme of each - database is shown as well. + Lists all available domains (derived types). If <replaceable + class="parameter">pattern</replaceable> (a regular expression) + is specified, only matching domains are shown. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term> + <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> - <listitem> - <para> - Reads the large object with <acronym>OID</acronym> <replaceable - class="parameter">loid</replaceable> from the database and - writes it to <replaceable - class="parameter">filename</replaceable>. Note that this is - subtly different from the server function - <function>lo_export</function>, which acts with the permissions - of the user that the database server runs as and on the server's - file system. - </para> - <tip> - <para> - Use <command>\lo_list</command> to find out the large object's - <acronym>OID</acronym>. - </para> - </tip> - <note> - <para> - See the description of the <envar>LO_TRANSACTION</envar> - variable for important information concerning all large object - operations. - </para> - </note> - </listitem> + <listitem> + <para> + Lists available functions, together with their argument and + return types. If <replaceable + class="parameter">pattern</replaceable> (a regular expression) + is specified, only matching functions are shown. If the form + <literal>\df+</literal> is used, additional information about + each function, including language and description, is shown. + </para> + </listitem> </varlistentry> <varlistentry> - <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term> - - <listitem> - <para> - Stores the file into a <productname>PostgreSQL</productname> - <quote>large object</quote>. Optionally, it associates the given - comment with the object. Example: -<programlisting> -foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput> -lo_import 152801 -</programlisting> - The response indicates that the large object received object id - 152801 which one ought to remember if one wants to access the - object ever again. For that reason it is recommended to always - associate a human-readable comment with every object. Those can - then be seen with the <command>\lo_list</command> command. - </para> + <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> + <listitem> <para> - Note that this command is subtly different from the server-side - <function>lo_import</function> because it acts as the local user - on the local file system, rather than the server's user and file - system. + This is not the actual command name: The letters i, s, t, v, S + stand for index, sequence, table, view, and system table, + respectively. You can specify any or all of them in any order to + obtain a listing of them, together with who the owner is. </para> - <note> <para> - See the description of the <envar>LO_TRANSACTION</envar> - variable for important information concerning all large object - operations. + If <replaceable class="parameter">pattern</replaceable> is + specified, it is a regular expression that restricts the listing + to those objects whose name matches. If one appends a + <quote>+</quote> to the command name, each object is listed with + its associated description, if any. </para> - </note> </listitem> </varlistentry> + <varlistentry> - <term><literal>\lo_list</literal></term> + <term><literal>\dl</literal></term> <listitem> <para> - Shows a list of all <productname>PostgreSQL</productname> - <quote>large objects</quote> currently stored in the database, - along with any comments provided for them. + This is an alias for <command>\lo_list</command>, which shows a + list of large objects. </para> </listitem> </varlistentry> + <varlistentry> - <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term> + <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term> + <listitem> + <para> + Lists available operators with their operand and return types. + If <replaceable class="parameter">name</replaceable> is + specified, only operators with that name will be shown. + </para> + </listitem> + </varlistentry> - <listitem> - <para> - Deletes the large object with <acronym>OID</acronym> - <replaceable class="parameter">loid</replaceable> from the - database. - </para> - <tip> - <para> - Use <command>\lo_list</command> to find out the large object's - <acronym>OID</acronym>. - </para> - </tip> - <note> + <varlistentry> + <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> + <listitem> <para> - See the description of the <envar>LO_TRANSACTION</envar> - variable for important information concerning all large object - operations. + This is an alias for <command>\z</command> which was included + for its greater mnemonic value (<quote>display + permissions</quote>). </para> - </note> </listitem> </varlistentry> <varlistentry> - <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term> - + <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> <listitem> <para> - Saves future query results to the file <replaceable - class="parameter">filename</replaceable> or pipes future results - into a separate Unix shell to execute <replaceable - class="parameter">command</replaceable>. If no arguments are - specified, the query output will be reset to - <filename>stdout</filename>. + Lists all data types or only those that match <replaceable + class="parameter">pattern</replaceable>. The command form + <literal>\dT+</literal> shows extra information. </para> - - <para> - <quote>Query results</quote> includes all tables, command - responses, and notices obtained from the database server, as - well as output of various backslash commands that query the - database (such as <command>\d</command>), but not error - messages. - </para> - - <tip> - <para> - To intersperse text output in between query results, use - <command>\qecho</command>. - </para> - </tip> </listitem> </varlistentry> <varlistentry> - <term><literal>\p</literal></term> + <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> <listitem> <para> - Print the current query buffer to the standard output. + Lists all configured users or only those that match <replaceable + class="parameter">pattern</replaceable>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term> - - <listitem> - <para> - This command sets options affecting the output of query result - tables. <replaceable class="parameter">parameter</replaceable> - describes which option is to be set. The semantics of - <replaceable class="parameter">value</replaceable> depend - thereon. - </para> - - <para> - Adjustable printing options are: - <variablelist> - <varlistentry> - <term><literal>format</literal></term> - <listitem> - <para> - Sets the output format to one of <literal>unaligned</literal>, - <literal>aligned</literal>, <literal>html</literal>, or - <literal>latex</literal>. Unique abbreviations are allowed. - (That would mean one letter is enough.) - </para> - - <para> - <quote>Unaligned</quote> writes all fields of a tuple on a - line, separated by the currently active field separator. This - is intended to create output that might be intended to be read - in by other programs (tab-separated, comma-separated). - <quote>Aligned</quote> mode is the standard, human-readable, - nicely formatted text output that is default. The - <quote><acronym>HTML</acronym></quote> and - <quote>LaTeX</quote> modes put out tables that are intended to - be included in documents using the respective mark-up - language. They are not complete documents! (This might not be - so dramatic in <acronym>HTML</acronym>, but in LaTeX you must - have a complete document wrapper.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>border</literal></term> - <listitem> - <para> - The second argument must be a number. In general, the higher - the number the more borders and lines the tables will have, - but this depends on the particular format. In - <acronym>HTML</acronym> mode, this will translate directly - into the <literal>border=...</literal> attribute, in the - others only values 0 (no border), 1 (internal dividing lines), - and 2 (table frame) make sense. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>expanded</literal> (or <literal>x</literal>)</term> - <listitem> - <para> - Toggles between regular and expanded format. When expanded - format is enabled, all output has two columns with the field - name on the left and the data on the right. This mode is - useful if the data wouldn't fit on the screen in the normal - <quote>horizontal</quote> mode. - </para> - - <para> - Expanded mode is supported by all four output modes. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>null</literal></term> - <listitem> - <para> - The second argument is a string that should be printed - whenever a field is null. The default is not to print - anything, which can easily be mistaken for, say, an empty - string. Thus, one might choose to write <literal>\pset null - '(null)'</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>fieldsep</literal></term> - <listitem> - <para> - Specifies the field separator to be used in unaligned output - mode. That way one can create, for example, tab- or - comma-separated output, which other programs might prefer. To - set a tab as field separator, type <literal>\pset fieldsep - '\t'</literal>. The default field separator is - <literal>'|'</literal> (a <quote>pipe</quote> symbol). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>footer</literal></term> - <listitem> - <para> - Toggles the display of the default footer <literal>(x - rows)</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>recordsep</literal></term> - <listitem> - <para> - Specifies the record (line) separator to use in unaligned - output mode. The default is a newline character. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>tuples_only</literal> (or <literal>t</literal>)</term> - <listitem> - <para> - Toggles between tuples only and full display. Full display may - show extra information such as column headers, titles, and - various footers. In tuples only mode, only actual table data - is shown. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term> - <listitem> - <para> - Sets the table title for any subsequently printed tables. This - can be used to give your output descriptive tags. If no - argument is given, the title is unset. - </para> - - <note> - <para> - This formerly only affected <acronym>HTML</acronym> mode. You - can now set titles in any output format. - </para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term> - <listitem> - <para> - Allows you to specify any attributes to be placed inside the - <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This - could for example be <literal>cellpadding</literal> or - <literal>bgcolor</literal>. Note that you probably don't want - to specify <literal>border</literal> here, as that is already - taken care of by <literal>\pset border</literal>. - </para> - </listitem> - </varlistentry> + <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term> + <listitem> + <para> + If <replaceable class="parameter">filename</replaceable> is + specified, the file is edited; after the editor exits, its + content is copied back to the query buffer. If no argument is + given, the current query buffer is copied to a temporary file + which is then edited in the same fashion. + </para> - <varlistentry> - <term><literal>pager</literal></term> - <listitem> - <para> - Toggles the use of a pager for query and psql help output. If the - environment variable <envar>PAGER</envar> is set, the output - is piped to the specified program. Otherwise - <filename>more</filename> is used. - </para> + <para> + The new query buffer is then re-parsed according to the normal + rules of <application>psql</application>, where the whole buffer + is treated as a single line. (Thus you cannot make scripts this + way. Use <command>\i</command> for that.) This means also that + if the query ends with (or rather contains) a semicolon, it is + immediately executed. In other cases it will merely wait in the + query buffer. + </para> - <para> - In any case, <application>psql</application> only uses the - pager if it seems appropriate. That means among other things - that the output is to a terminal and that the table would - normally not fit on the screen. Because of the modular nature - of the printing routines it is not always possible to predict - the number of lines that will actually be printed. For that - reason <application>psql</application> might not appear very - discriminating about when to use the pager. - </para> - </listitem> - </varlistentry> - </variablelist> - Illustrations on how these different formats look can be seen in - the <xref linkend="APP-PSQL-examples" - endterm="APP-PSQL-examples-title"> section. + <tip> + <para> + <application>psql</application> searches the environment + variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and + <envar>VISUAL</envar> (in that order) for an editor to use. If + all of them are unset, <filename>/bin/vi</filename> is run. + </para> + </tip> + </listitem> + </varlistentry> + + + <varlistentry> + <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term> + <listitem> + <para> + Prints the arguments to the standard output, separated by one + space and followed by a newline. This can be useful to + intersperse information in the output of scripts. For example: +<programlisting> +=> <userinput>\echo `date`</userinput> +Tue Oct 26 21:40:57 CEST 1999 +</programlisting> + If the first argument is an unquoted <literal>-n</literal> the the trailing + newline is not written. </para> <tip> <para> - There are various shortcut commands for <command>\pset</command>. See - <command>\a</command>, <command>\C</command>, <command>\H</command>, - <command>\t</command>, <command>\T</command>, and <command>\x</command>. + If you use the <command>\o</command> command to redirect your + query output you may wish to use <command>\qecho</command> + instead of this command. </para> </tip> + </listitem> + </varlistentry> - <note> - <para> - It is an error to call <command>\pset</command> without - arguments. In the future this call might show the current status - of all printing options. - </para> - </note> - </listitem> + <varlistentry> + <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term> + + <listitem> + <para> + Sets the client encoding, if you are using multibyte encodings. + Without an argument, this command shows the current encoding. + </para> + </listitem> </varlistentry> <varlistentry> - <term><literal>\q</literal></term> + <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term> + <listitem> <para> - Quit the <application>psql</application> program. + Sets the field separator for unaligned query output. The default + is pipe (<literal>|</literal>). See also + <command>\pset</command> for a generic way of setting output + options. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term> + <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term> + <listitem> <para> - This command is identical to <command>\echo</command> except - that all output will be written to the query output channel, as - set by <command>\o</command>. + Sends the current query input buffer to the backend and + optionally saves the output in <replaceable + class="parameter">filename</replaceable> or pipes the output + into a separate Unix shell to execute <replaceable + class="parameter">command</replaceable>. A bare + <literal>\g</literal> is virtually equivalent to a semicolon. A + <literal>\g</literal> with argument is a <quote>one-shot</quote> + alternative to the <command>\o</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term> + <listitem> + <para> + Give syntax help on the specified <acronym>SQL</acronym> + command. 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 syntax help on all + <acronym>SQL</acronym> commands is shown. </para> + + <note> + <para> + To simplify typing, commands that consists of several words do + not have to be quoted. Thus it is fine to type <userinput>\help + alter table</userinput>. + </para> + </note> </listitem> </varlistentry> <varlistentry> - <term><literal>\r</literal></term> + <term><literal>\H</literal></term> <listitem> <para> - Resets (clears) the query buffer. + Turns on <acronym>HTML</acronym> query output format. If the + <acronym>HTML</acronym> format is already on, it is switched + back to the default aligned text format. This command is for + compatibility and convenience, but see <command>\pset</command> + about setting other output options. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term> + <term><literal>\i</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, the history - is written to the standard output. This option is only available - if <application>psql</application> is configured to use the - <acronym>GNU</acronym> history library. + Reads input from the file <replaceable + class="parameter">filename</replaceable> and executes it as + though it had been typed on the keyboard. + </para> + <note> + <para> + If you want to see the lines on the screen as they are read you + must set the variable <envar>ECHO</envar> to + <literal>all</literal>. + </para> + </note> + </listitem> + </varlistentry> + + + <varlistentry> + <term><literal>\l</literal> (or <literal>\list</literal>)</term> + <listitem> + <para> + List all the databases in the server as well as their owners. + Append a <quote>+</quote> to the command name to see any + descriptions for the databases as well. If your + <productname>PostgreSQL</productname> installation was compiled + with multibyte encoding support, the encoding scheme of each + database is shown as well. </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term> + + <listitem> + <para> + Reads the large object with <acronym>OID</acronym> <replaceable + class="parameter">loid</replaceable> from the database and + writes it to <replaceable + class="parameter">filename</replaceable>. Note that this is + subtly different from the server function + <function>lo_export</function>, which acts with the permissions + of the user that the database server runs as and on the server's + file system. + </para> + <tip> + <para> + Use <command>\lo_list</command> to find out the large object's + <acronym>OID</acronym>. + </para> + </tip> + <note> + <para> + See the description of the <envar>LO_TRANSACTION</envar> + variable for important information concerning all large object + operations. + </para> + </note> + </listitem> + </varlistentry> + + + <varlistentry> + <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term> + + <listitem> + <para> + Stores the file into a <productname>PostgreSQL</productname> + <quote>large object</quote>. Optionally, it associates the given + comment with the object. Example: +<programlisting> +foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput> +lo_import 152801 +</programlisting> + The response indicates that the large object received object id + 152801 which one ought to remember if one wants to access the + object ever again. For that reason it is recommended to always + associate a human-readable comment with every object. Those can + then be seen with the <command>\lo_list</command> command. + </para> + + <para> + Note that this command is subtly different from the server-side + <function>lo_import</function> because it acts as the local user + on the local file system, rather than the server's user and file + system. + </para> <note> <para> - In the current version, it is no longer necessary to save the - command history, since that will be done automatically on - program termination. The history is also loaded automatically - every time <application>psql</application> starts up. + See the description of the <envar>LO_TRANSACTION</envar> + variable for important information concerning all large object + operations. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>\lo_list</literal></term> + <listitem> + <para> + Shows a list of all <productname>PostgreSQL</productname> + <quote>large objects</quote> currently stored in the database, + along with any comments provided for them. </para> - </note> - </listitem> + </listitem> </varlistentry> - <varlistentry> - <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term> + <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term> <listitem> <para> - Sets the internal variable <replaceable - class="parameter">name</replaceable> to <replaceable - class="parameter">value</replaceable> or, if more than one value - is given, to the concatenation of all of them. If no second - argument is given, the variable is just set with no value. To - unset a variable, use the <command>\unset</command> command. - </para> - - <para> - Valid variable names can contain characters, digits, and - underscores. See the section about - <application>psql</application> variables for details. + Deletes the large object with <acronym>OID</acronym> + <replaceable class="parameter">loid</replaceable> from the + database. </para> + <tip> <para> - Although you are welcome to set any variable to anything you - want, <application>psql</application> treats several variables - as special. They are documented in the section about variables. + Use <command>\lo_list</command> to find out the large object's + <acronym>OID</acronym>. </para> - + </tip> <note> <para> - This command is totally separate from the <acronym>SQL</acronym> - command <xref linkend="SQL-SET" endterm="SQL-SET-title">. + See the description of the <envar>LO_TRANSACTION</envar> + variable for important information concerning all large object + operations. </para> </note> </listitem> @@ -1172,582 +1200,500 @@ lo_import 152801 <varlistentry> - <term><literal>\t</literal></term> - <listitem> - <para> - Toggles the display of output column name headings and row count - footer. This command is equivalent to <literal>\pset - tuples_only</literal> and is provided for convenience. - </para> - </listitem> - </varlistentry> - + <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term> - <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 in <acronym>HTML</acronym> tabular - output mode. This command is equivalent to <literal>\pset - tableattr <replaceable - class="parameter">table_options</replaceable></literal>. + Saves future query results to the file <replaceable + class="parameter">filename</replaceable> or pipes future results + into a separate Unix shell to execute <replaceable + class="parameter">command</replaceable>. If no arguments are + specified, the query output will be reset to + <filename>stdout</filename>. </para> - </listitem> - </varlistentry> + <para> + <quote>Query results</quote> includes all tables, command + responses, and notices obtained from the database server, as + well as output of various backslash commands that query the + database (such as <command>\d</command>), but not error + messages. + </para> - <varlistentry> - <term><literal>\timing</literal></term> - <listitem> - <para> - Toggles a display of how long each query takes in seconds. - </para> - </listitem> + <tip> + <para> + To intersperse text output in between query results, use + <command>\qecho</command>. + </para> + </tip> + </listitem> </varlistentry> <varlistentry> - <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term> + <term><literal>\p</literal></term> <listitem> <para> - Outputs the current query buffer to the file <replaceable - class="parameter">filename</replaceable> or pipes it to the Unix - command <replaceable class="parameter">command</replaceable>. + Print the current query buffer to the standard output. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\x</literal></term> - <listitem> - <para> - Toggles extended row format mode. As such it is equivalent to - <literal>\pset expanded</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> - <listitem> - <para> - Produces a list of all tables in the database with their - appropriate access permissions listed. If an argument is given - it is taken as a regular expression which limits the listing to - those tables which match it. - </para> + <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term> + <listitem> <para> -<programlisting> -test=> <userinput>\z</userinput> -Access permissions for database "test" - Relation | Access permissions -----------+------------------------------------- - my_table | {"=r","joe=arwR", "group staff=ar"} -(1 row ) -</programlisting> - Read this as follows: - - <itemizedlist> - <listitem> - <para> - <literal>"=r"</literal>: <literal>PUBLIC</literal> has read - (<command>SELECT</command>) permission on the table. - </para> - </listitem> + This command sets options affecting the output of query result + tables. <replaceable class="parameter">parameter</replaceable> + describes which option is to be set. The semantics of + <replaceable class="parameter">value</replaceable> depend + thereon. + </para> + <para> + Adjustable printing options are: + <variablelist> + <varlistentry> + <term><literal>format</literal></term> <listitem> <para> - <literal>"joe=arwR"</literal>: User <literal>joe</literal> has - read, write (<command>UPDATE</command>, - <command>DELETE</command>), <quote>append</quote> - (<command>INSERT</command>) permissions, and permission to - create rules on the table. + Sets the output format to one of <literal>unaligned</literal>, + <literal>aligned</literal>, <literal>html</literal>, or + <literal>latex</literal>. Unique abbreviations are allowed. + (That would mean one letter is enough.) </para> - </listitem> - <listitem> <para> - <literal>"group staff=ar"</literal>: Group - <literal>staff</literal> has <command>SELECT</command> and - <command>INSERT</command> permission. + <quote>Unaligned</quote> writes all fields of a tuple on a + line, separated by the currently active field separator. This + is intended to create output that might be intended to be read + in by other programs (tab-separated, comma-separated). + <quote>Aligned</quote> mode is the standard, human-readable, + nicely formatted text output that is default. The + <quote><acronym>HTML</acronym></quote> and + <quote>LaTeX</quote> modes put out tables that are intended to + be included in documents using the respective mark-up + language. They are not complete documents! (This might not be + so dramatic in <acronym>HTML</acronym>, but in LaTeX you must + have a complete document wrapper.) </para> - </listitem> - </itemizedlist> - </para> - - <para> - The commands <xref linkend="SQL-GRANT"> and - <xref linkend="SQL-REVOKE"> - are used to set access permissions. - </para> - - </listitem> - </varlistentry> - - - <varlistentry> - <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term> - <listitem> - <para> - Escapes to a separate Unix shell or executes the Unix command - <replaceable class="parameter">command</replaceable>. The - arguments are not further interpreted, the shell will see them - as is. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term><literal>\?</literal></term> - <listitem> - <para> - Get help information about the backslash (<quote>\</quote>) - commands. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> -</refsect1> - - - -<refsect1 id="R1-APP-PSQL-3"> - <refsect1info> - <date>1998-09-26</date> - </refsect1info> - - <title>Command-line Options</title> - - <para> - If so configured, <application>psql</application> understands both - standard Unix short options, and <acronym>GNU</acronym>-style long - options. The latter are not available on all systems. - </para> - - <para> - <variablelist> - <varlistentry> - <term>-a, --echo-all</term> - <listitem> - <para> - Print all the lines to the screen as they are read. This is more - useful for script processing rather than interactive mode. This is - equivalent to setting the variable <envar>ECHO</envar> to - <literal>all</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-A, --no-align</term> - <listitem> - <para> - Switches to unaligned output mode. (The default output mode is - otherwise aligned.) - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-c, --command <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 in shell scripts. - </para> - <para> - <replaceable class="parameter">query</replaceable> must be either - a query string that is completely parseable by the backend (i.e., - it contains no <application>psql</application> specific features), - or it is a single backslash command. Thus you cannot mix - <acronym>SQL</acronym> and <application>psql</application> - meta-commands. To achieve that, you could pipe the string into - <application>psql</application>, like this: <literal>echo "\x \\ - select * from foo;" | psql</literal>. - </para> - </listitem> - </varlistentry> - + </listitem> + </varlistentry> - <varlistentry> - <term>-d, --dbname <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 first non-option - argument on the command line. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>border</literal></term> + <listitem> + <para> + The second argument must be a number. In general, the higher + the number the more borders and lines the tables will have, + but this depends on the particular format. In + <acronym>HTML</acronym> mode, this will translate directly + into the <literal>border=...</literal> attribute, in the + others only values 0 (no border), 1 (internal dividing lines), + and 2 (table frame) make sense. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>expanded</literal> (or <literal>x</literal>)</term> + <listitem> + <para> + Toggles between regular and expanded format. When expanded + format is enabled, all output has two columns with the field + name on the left and the data on the right. This mode is + useful if the data wouldn't fit on the screen in the normal + <quote>horizontal</quote> mode. + </para> - <varlistentry> - <term>-e, --echo-queries</term> - <listitem> - <para> - Show all queries that are sent to the backend. This is equivalent - to setting the variable <envar>ECHO</envar> to - <literal>queries</literal>. - </para> - </listitem> - </varlistentry> + <para> + Expanded mode is supported by all four output modes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>null</literal></term> + <listitem> + <para> + The second argument is a string that should be printed + whenever a field is null. The default is not to print + anything, which can easily be mistaken for, say, an empty + string. Thus, one might choose to write <literal>\pset null + '(null)'</literal>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-E, --echo-hidden</term> - <listitem> - <para> - Echoes the actual queries generated by \d and other backslash - commands. You can use this if you wish to include similar - functionality into your own programs. This is equivalent to - setting the variable <envar>ECHO_HIDDEN</envar> from within - <application>psql</application>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>fieldsep</literal></term> + <listitem> + <para> + Specifies the field separator to be used in unaligned output + mode. That way one can create, for example, tab- or + comma-separated output, which other programs might prefer. To + set a tab as field separator, type <literal>\pset fieldsep + '\t'</literal>. The default field separator is + <literal>'|'</literal> (a <quote>pipe</quote> symbol). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>footer</literal></term> + <listitem> + <para> + Toggles the display of the default footer <literal>(x + rows)</literal>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-f, --file <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. - After the file is processed, <application>psql</application> - terminates. This is in many ways equivalent to the internal - command <command>\i</command>. - </para> + <varlistentry> + <term><literal>recordsep</literal></term> + <listitem> + <para> + Specifies the record (line) separator to use in unaligned + output mode. The default is a newline character. + </para> + </listitem> + </varlistentry> - <para> - If <replaceable>filename</replaceable> is <literal>-</literal> - (hyphen), then standard input is read. - </para> + <varlistentry> + <term><literal>tuples_only</literal> (or <literal>t</literal>)</term> + <listitem> + <para> + Toggles between tuples only and full display. Full display may + show extra information such as column headers, titles, and + various footers. In tuples only mode, only actual table data + is shown. + </para> + </listitem> + </varlistentry> - <para> - Using this option is subtly different from writing <literal>psql - < <replaceable - class="parameter">filename</replaceable></literal>. In general, - both will do what you expect, but using <literal>-f</literal> - enables some nice features such as error messages with line - numbers. There is also a slight chance that using this option will - reduce the start-up overhead. On the other hand, the variant using - the shell's input redirection is (in theory) guaranteed to yield - exactly the same output that you would have gotten had you entered - everything by hand. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term> + <listitem> + <para> + Sets the table title for any subsequently printed tables. This + can be used to give your output descriptive tags. If no + argument is given, the title is unset. + </para> + <note> + <para> + This formerly only affected <acronym>HTML</acronym> mode. You + can now set titles in any output format. + </para> + </note> + </listitem> + </varlistentry> - <varlistentry> - <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term> - <listitem> - <para> - Use <replaceable class="parameter">separator</replaceable> as the - field separator. This is equivalent to <command>\pset - fieldsep</command> or <command>\f</command>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term> + <listitem> + <para> + Allows you to specify any attributes to be placed inside the + <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This + could for example be <literal>cellpadding</literal> or + <literal>bgcolor</literal>. Note that you probably don't want + to specify <literal>border</literal> here, as that is already + taken care of by <literal>\pset border</literal>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-h, --host <replaceable class="parameter">hostname</replaceable></term> - <listitem> - <para> - Specifies the host name of the machine on which the - <application>postmaster</application> is running. If host begins - with a slash, it is used as the directory for the unix domain - socket. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>pager</literal></term> + <listitem> + <para> + Toggles the use of a pager for query and psql help output. If the + environment variable <envar>PAGER</envar> is set, the output + is piped to the specified program. Otherwise a platform-dependent default (such as + <filename>more</filename>) is used. + </para> + <para> + In any case, <application>psql</application> only uses the + pager if it seems appropriate. That means among other things + that the output is to a terminal and that the table would + normally not fit on the screen. Because of the modular nature + of the printing routines it is not always possible to predict + the number of lines that will actually be printed. For that + reason <application>psql</application> might not appear very + discriminating about when to use the pager. + </para> + </listitem> + </varlistentry> + </variablelist> + Illustrations on how these different formats look can be seen in + the <xref linkend="APP-PSQL-examples" + endterm="APP-PSQL-examples-title"> section. + </para> - <varlistentry> - <term>-H, --html</term> - <listitem> - <para> - Turns on <acronym>HTML</acronym> tabular output. This is - equivalent to <literal>\pset format html</literal> or the - <command>\H</command> command. - </para> - </listitem> - </varlistentry> + <tip> + <para> + There are various shortcut commands for <command>\pset</command>. See + <command>\a</command>, <command>\C</command>, <command>\H</command>, + <command>\t</command>, <command>\T</command>, and <command>\x</command>. + </para> + </tip> - - <varlistentry> - <term>-l, --list</term> - <listitem> - <para> - Lists all available databases, then exits. Other non-connection - options are ignored. This is similar to the internal command - <command>\list</command>. - </para> - </listitem> - </varlistentry> + <note> + <para> + It is an error to call <command>\pset</command> without + arguments. In the future this call might show the current status + of all printing options. + </para> + </note> + </listitem> + </varlistentry> - <varlistentry> - <term>-o, --output <replaceable class="parameter">filename</replaceable></term> - <listitem> - <para> - Put all query output into file <replaceable - class="parameter">filename</replaceable>. This is equivalent to - the command <command>\o</command>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\q</literal></term> + <listitem> + <para> + Quit the <application>psql</application> program. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-p, --port <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 or, if not set, to the port specified at - compile time, usually 5432. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term> + <listitem> + <para> + This command is identical to <command>\echo</command> except + that all output will be written to the query output channel, as + set by <command>\o</command>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term> - <listitem> - <para> - Allows you to specify printing options in the style of - <command>\pset</command> on the command line. Note that here you - have to separate name and value with an equal sign instead of a - space. Thus to set the output format to LaTeX, you could write - <literal>-P format=latex</literal>. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\r</literal></term> + <listitem> + <para> + Resets (clears) the query buffer. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-q</term> - <listitem> - <para> - Specifies that <application>psql</application> should do its work - quietly. By default, it prints welcome messages and various - informational output. If this option is used, none of this - happens. This is useful with the <option>-c</option> option. - Within <application>psql</application> you can also set the - <envar>QUIET</envar> variable to achieve the same effect. - </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, the history + is written to the standard output. This option is only available + if <application>psql</application> is configured to use the + <acronym>GNU</acronym> history library. + </para> - <varlistentry> - <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term> - <listitem> - <para> - Use <replaceable class="parameter">separator</replaceable> as the - record separator. This is equivalent to the <command>\pset - recordsep</command> command. - </para> - </listitem> - </varlistentry> + <note> + <para> + In the current version, it is no longer necessary to save the + command history, since that will be done automatically on + program termination. The history is also loaded automatically + every time <application>psql</application> starts up. + </para> + </note> + </listitem> + </varlistentry> - - <varlistentry> - <term>-s, --single-step</term> - <listitem> - <para> - Run in single-step mode. That means the user is prompted before - each query is sent to the backend, with the option to cancel - execution as well. Use this to debug scripts. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term> - <varlistentry> - <term>-S, --single-line</term> - <listitem> - <para> - Runs in single-line mode where a newline terminates a query, as a - semicolon does. - </para> + <listitem> + <para> + Sets the internal variable <replaceable + class="parameter">name</replaceable> to <replaceable + class="parameter">value</replaceable> or, if more than one value + is given, to the concatenation of all of them. If no second + argument is given, the variable is just set with no value. To + unset a variable, use the <command>\unset</command> command. + </para> - <note> - <para> - This mode is provided for those who insist on it, but you are not - necessarily encouraged to use it. In particular, if you mix - <acronym>SQL</acronym> and meta-commands on a line the order of - execution might not always be clear to the inexperienced user. - </para> - </note> - </listitem> - </varlistentry> + <para> + Valid variable names can contain characters, digits, and + underscores. See the section about + <application>psql</application> variables for details. + </para> + <para> + Although you are welcome to set any variable to anything you + want, <application>psql</application> treats several variables + as special. They are documented in the section about variables. + </para> - <varlistentry> - <term>-t, --tuples-only</term> - <listitem> - <para> - Turn off printing of column names and result row count footers, - etc. It is completely equivalent to the <command>\t</command> - meta-command. - </para> - </listitem> - </varlistentry> + <note> + <para> + This command is totally separate from the <acronym>SQL</acronym> + command <xref linkend="SQL-SET" endterm="SQL-SET-title">. + </para> + </note> + </listitem> + </varlistentry> - <varlistentry> - <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term> - <listitem> - <para> - Allows you to specify options to be placed within the - <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See - <command>\pset</command> for details. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\t</literal></term> + <listitem> + <para> + Toggles the display of output column name headings and row count + footer. This command is equivalent to <literal>\pset + tuples_only</literal> and is provided for convenience. + </para> + </listitem> + </varlistentry> - - <varlistentry> - <term>-u</term> - <listitem> - <para> - Makes <application>psql</application> prompt for the user name and - password before connecting to the database. - </para> - <para> - This option is deprecated, as it is conceptually flawed. - (Prompting for a non-default user name and prompting for a - password because the backend requires it are really two different - things.) You are encouraged to look at the <option>-U</option> and - <option>-W</option> options instead. - </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 in <acronym>HTML</acronym> tabular + output mode. This command is equivalent to <literal>\pset + tableattr <replaceable + class="parameter">table_options</replaceable></literal>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-U, --username <replaceable class="parameter">username</replaceable></term> - <listitem> - <para> - Connects to the database as the user <replaceable - class="parameter">username</replaceable> instead of the default. - (You must have permission to do so, of course.) - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\timing</literal></term> + <listitem> + <para> + Toggles a display of how long each query takes in seconds. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term> - <listitem> - <para> - Performs a variable assignment, like the <command>\set</command> - internal command. Note that you must separate name and value, if - any, by an equal sign on the command line. To unset a variable, - leave off the equal sign. To just set a variable without a value, - use the equal sign but leave off the value. These assignments are - done during a very early stage of start-up, so variables reserved - for internal purposes might get overwritten later. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term> + <listitem> + <para> + Outputs the current query buffer to the file <replaceable + class="parameter">filename</replaceable> or pipes it to the Unix + command <replaceable class="parameter">command</replaceable>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-V, --version</term> - <listitem> - <para> - Shows the <application>psql</application> version. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>\x</literal></term> + <listitem> + <para> + Toggles extended row format mode. As such it is equivalent to + <literal>\pset expanded</literal>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-W, --password</term> - <listitem> - <para> - Requests that <application>psql</application> should prompt for a - password before connecting to a database. This will remain set for - the entire session, even if you change the database connection - with the meta-command <command>\connect</command>. - </para> + <varlistentry> + <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> + <listitem> + <para> + Produces a list of all tables in the database with their + appropriate access permissions listed. If an argument is given + it is taken as a regular expression which limits the listing to + those tables which match it. + </para> - <para> - In the current version, <application>psql</application> - automatically issues a password prompt whenever the backend - requests password authentication. Because this is currently based - on a hack, the automatic recognition might mysteriously fail, - hence this option to force a prompt. If no password prompt is - issued and the backend requires password authentication the - connection attempt will fail. - </para> - </listitem> - </varlistentry> + <para> +<programlisting> +test=> <userinput>\z</userinput> +Access permissions for database "test" + Relation | Access permissions +----------+------------------------------------- + my_table | {"=r","joe=arwR", "group staff=ar"} +(1 row ) +</programlisting> + Read this as follows: + <itemizedlist> + <listitem> + <para> + <literal>"=r"</literal>: <literal>PUBLIC</literal> has read + (<command>SELECT</command>) permission on the table. + </para> + </listitem> - <varlistentry> - <term>-x, --expanded</term> - <listitem> - <para> - Turns on extended row format mode. This is equivalent to the - command <command>\x</command>. - </para> - </listitem> - </varlistentry> + <listitem> + <para> + <literal>"joe=arwR"</literal>: User <literal>joe</literal> has + read, write (<command>UPDATE</command>, + <command>DELETE</command>), <quote>append</quote> + (<command>INSERT</command>) permissions, and permission to + create rules on the table. + </para> + </listitem> + <listitem> + <para> + <literal>"group staff=ar"</literal>: Group + <literal>staff</literal> has <command>SELECT</command> and + <command>INSERT</command> permission. + </para> + </listitem> + </itemizedlist> + </para> - <varlistentry> - <term>-X, --no-psqlrc</term> - <listitem> - <para> - Do not read the start-up file <filename>~/.psqlrc</filename>. - </para> - </listitem> - </varlistentry> + <para> + The commands <xref linkend="SQL-GRANT"> and + <xref linkend="SQL-REVOKE"> + are used to set access permissions. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>-?, --help</term> - <listitem> - <para> - Shows help about <application>psql</application> command line - arguments. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <varlistentry> + <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term> + <listitem> + <para> + Escapes to a separate Unix shell or executes the Unix command + <replaceable class="parameter">command</replaceable>. The + arguments are not further interpreted, the shell will see them + as is. + </para> + </listitem> + </varlistentry> -</refsect1> + <varlistentry> + <term><literal>\?</literal></term> + <listitem> + <para> + Get help information about the backslash (<quote>\</quote>) + commands. + </para> + </listitem> + </varlistentry> -<refsect1 id="R1-APP-PSQL-4"> - <refsect1info> - <date>1998-09-27</date> - </refsect1info> + </variablelist> + </para> + </refsect2> - <title>Advanced features</title> + <refsect2> + <title>Advanced features</title> - <refsect2 id="APP-PSQL-variables"> + <refsect3 id="APP-PSQL-variables"> <title id="APP-PSQL-variables-title">Variables</title> <para> @@ -2063,11 +2009,10 @@ bar </para> - </refsect2> - + </refsect3> - <refsect2 id="APP-PSQL-sql-interpol"> - <title id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title> + <refsect3> + <title><acronym>SQL</acronym> Interpolation</title> <para> An additional useful feature of <application>psql</application> @@ -2131,10 +2076,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' conflict.) </para> - </refsect2> - + </refsect3> - <refsect2 id="APP-PSQL-prompting"> + <refsect3 id="APP-PSQL-prompting"> <title id="APP-PSQL-prompting-title">Prompting</title> <para> @@ -2282,31 +2226,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' </para> </note> - </refsect2> - - <refsect2 id="APP-PSQL-MISC"> - <title id="APP-PSQL-MISC-title">Miscellaneous</title> - - <para> - <application>psql</application> returns 0 to the shell if it - finished normally, 1 if a fatal error of its own (out of memory, - file not found) occurs, 2 if the connection to the backend went bad - and the session is not interactive, and 3 if an error occurred in a - script and the variable <envar>ON_ERROR_STOP</envar> was set. - </para> - - <para> - Before starting up, <application>psql</application> attempts to read - and execute commands from the file - <filename>$HOME/.psqlrc</filename>. It could be used to set up the - client or the server to taste (using the <command>\set </command> - and <command>SET</command> commands). - </para> - - </refsect2> + </refsect3> - <refsect2> - <title><acronym>GNU</acronym> readline</title> + <refsect3> + <title>Readline</title> <para> <application>psql</application> supports the readline and history @@ -2356,14 +2279,167 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ... <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>. </para> + </refsect3> </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>HOME</envar></term> + + <listitem> + <para> + Directory for initialization file (<filename>.psqlrc</filename>) + and command history file (<filename>.psql_history</filename>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PAGER</envar></term> + + <listitem> + <para> + If the query results do not fit on the screen, they are piped + through this command. Typical values are + <literal>more</literal> or <literal>less</literal>. The default + is platform-dependent. The use of the pager can be disabled by + using the <command>\pset</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATABASE</envar></term> + + <listitem> + <para> + Default database to connect to + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PSQL_EDITOR</envar></term> + <term><envar>EDITOR</envar></term> + <term><envar>VISUAL</envar></term> + + <listitem> + <para> + Editor used by the <command>\e</command> command. The variables + are examined in the order listed; the first that is set is used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>SHELL</envar></term> + + <listitem> + <para> + Command executed by the <command>\!</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>TMPDIR</envar></term> + + <listitem> + <para> + Directory for storing temporary files. The default is + <filename>/tmp</filename>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Files</title> + + <itemizedlist> + <listitem> + <para> + Before starting up, <application>psql</application> attempts to + read and execute commands from the file + <filename>$HOME/.psqlrc</filename>. It could be used to set up + the client or the server to taste (using the <command>\set + </command> and <command>SET</command> commands). + </para> + </listitem> + + <listitem> + <para> + The command-line history is stored in the file + <filename>$HOME/.psql_history</filename>. + </para> + </listitem> + </itemizedlist> + </refsect1> + + + <refsect1> + <title>Notes</title> + + <itemizedlist> + <listitem> + <para> + In some earlier life <application>psql</application> allowed the + first argument to start directly after the (single-letter) + command. For compatibility this is still supported to some extent + but I am not going to explain the details here as this use is + discouraged. But if you get strange messages, keep this in mind. + For example +<programlisting> +testdb=> <userinput>\foo</userinput> +Field separator is "oo", +</programlisting> + which is perhaps not what one would expect. + </para> + </listitem> + <listitem> + <para> + <application>psql</application> only works smoothly with servers + of the same version. That does not mean other combinations will + fail outright, but subtle and not-so-subtle problems might come + up. + </para> + </listitem> + <listitem> + <para> + Pressing Control-C during a <quote>copy in</quote> (data sent to + the server) doesn't show the most ideal of behaviors. If you get a + message such as <quote>COPY state must be terminated + first</quote>, simply reset the connection by entering <literal>\c + - -</literal>. + </para> + </listitem> -</refsect1> + </itemizedlist> + </refsect1> -<refsect1 id="APP-PSQL-examples"> + <refsect1 id="APP-PSQL-examples"> <title id="APP-PSQL-examples-title">Examples</title> <note> @@ -2478,60 +2554,7 @@ second | four </programlisting> </para> -</refsect1> - - -<refsect1> - <refsect1info> - <date>1999-10-27</date> - </refsect1info> - - <title>Appendix</title> - - <refsect2> - <title>Bugs and Issues</title> - - <itemizedlist> - <listitem> - <para> - In some earlier life <application>psql</application> allowed the - first argument to start directly after the (single-letter) - command. For compatibility this is still supported to some extent - but I am not going to explain the details here as this use is - discouraged. But if you get strange messages, keep this in mind. - For example -<programlisting> -testdb=> <userinput>\foo</userinput> -Field separator is "oo", -</programlisting> - which is perhaps not what one would expect. - </para> - </listitem> - - <listitem> - <para> - <application>psql</application> only works smoothly with servers - of the same version. That does not mean other combinations will - fail outright, but subtle and not-so-subtle problems might come - up. - </para> - </listitem> - - <listitem> - <para> - Pressing Control-C during a <quote>copy in</quote> (data sent to - the server) doesn't show the most ideal of behaviors. If you get a - message such as <quote>COPY state must be terminated - first</quote>, simply reset the connection by entering <literal>\c - - -</literal>. - </para> - </listitem> - - </itemizedlist> - - </refsect2> - -</refsect1> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index b1c3cab01a..37debc1b84 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -1,13 +1,9 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.21 2002/02/18 05:48:43 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.22 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> <refentry id="APP-VACUUMDB"> - <docinfo> - <date>2000-11-11</date> - </docinfo> - <refmeta> <refentrytitle id="APP-VACUUMDB-TITLE"><application>vacuumdb</application></refentrytitle> <manvolnum>1</manvolnum> @@ -38,11 +34,37 @@ PostgreSQL documentation <group><arg>--verbose</arg><arg>-v</arg></group> <group><arg>--analyze</arg><arg>-z</arg></group> </cmdsynopsis> + </refsynopsisdiv> + + + <refsect1> + <title>Description</title> + + <para> + <application>vacuumdb</application> is a utility for cleaning a + <productname>PostgreSQL</productname> database. + <application>vacuumdb</application> will also generate internal statistics + used by the <productname>PostgreSQL</productname> query optimizer. + </para> + + <para> + <application>vacuumdb</application> is a shell script wrapper around the + backend command + <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. There is no effective + difference between vacuuming databases via this or other methods. + <application>psql</application> must be found by the script and + a database server must be running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-VACUUMDB-1"> - <title> - Inputs - </title> <para> <application>vacuumdb</application> accepts the following command line arguments: @@ -190,12 +212,12 @@ PostgreSQL documentation </varlistentry> </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-VACUUMDB-2"> - <title> - Outputs - </title> <para> <variablelist> <varlistentry> @@ -221,42 +243,30 @@ PostgreSQL documentation </variablelist> </para> + </refsect1> - <para> - </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-VACUUMDB-1"> - <title> - Description - </title> + <refsect1> + <title>Environment</title> - <para> - <application>vacuumdb</application> is a utility for cleaning a - <productname>PostgreSQL</productname> database. - <application>vacuumdb</application> will also generate internal statistics - used by the <productname>PostgreSQL</productname> query optimizer. - </para> - - <para> - <application>vacuumdb</application> is a shell script wrapper around the - backend command - <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. There is no effective - difference between vacuuming databases via this or other methods. - <application>psql</application> must be found by the script and - a database server must be running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-APP-VACUUMDB-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -290,6 +300,15 @@ PostgreSQL documentation </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file -- 2.24.1