Structure reference pages consistently. Document that structure.

Add information about environment variables.

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 7df4995cfb858624ce23747eab1bf4c0c5306359..10c0463844fff7c66b4c78b5a256ad6b562094ad 100644 (file)
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Documentation
@@ -1254,6 +1254,196 @@ End:
 
  
 
+
+ 
+  Style Guide
+
+  
+   Reference Pages
+
+   
+    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
+    PostgreSQL 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.
+   
+
+   
+    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
+    Usage section.
+
+    
+     
+      Name
+      
+       
+        This section is generated automatically.  It contains the
+        command name and a half-sentence summary of its functionality.
+       
+      
+     
+
+     
+      Synopsis
+      
+       
+        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.
+       
+      
+     
+     
+     
+      Description
+      
+       
+        Several paragraphs explaining what the command does.
+       
+      
+     
+     
+     
+      Options
+      
+       
+        A list describing each command-line option.  If there are a
+        lot of options, subsections may be used.
+       
+      
+     
+     
+     
+      Exit Status
+      
+       
+        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.
+       
+      
+     
+     
+     
+      Usage
+      
+       
+        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.
+       
+      
+     
+     
+     
+      Environment
+      
+       
+        List all environment variables that the program might use.
+        Try to be complete; even seemingly trivial variables like
+        SHELL might be of interest to the user.
+       
+      
+     
+     
+     
+      Files
+      
+       
+        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.
+       
+      
+     
+     
+     
+      Diagnostics
+      
+       
+        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.
+       
+      
+     
+     
+     
+      Notes
+      
+       
+        Anything that doesn't fit elsewhere, but in particular bugs,
+        implementation flaws, security considerations, compatibility
+        issues.
+       
+      
+     
+     
+     
+      Examples
+      
+       
+        Examples
+       
+      
+     
+     
+     
+      History
+      
+       
+        If there were some major milestones in the history of the
+        program, they might be listed here.  Usually, this section can
+        be omitted.
+       
+      
+     
+     
+     
+      See Also
+      
+       
+        Cross-references, listed in the following order: other
+        PostgreSQL command reference pages,
+        PostgreSQL SQL command reference
+        pages, citation of PostgreSQL
+        manuals, other reference pages (e.g., operating system, other
+        packages), other documentation.  Items in the same group are
+        listed alphabetically.
+       
+      
+     
+
+    
+   
+
+   
+    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.
+   
+  
+
+ 
 
 
 
 
@@ -22,12 +22,42 @@ PostgreSQL documentation
    dbname
    description
   
+ 
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
-   
+
+ 
+  </div>
<div class="diff add">+   Description</div>
<div class="diff add">+  
+  
+   createdb creates a new PostgreSQL
+   database.
+  
+
+  
+   Normally, the database user who executes this command becomes the owner of
+   the new database.
+   However a different owner can be specified via the -O
+   option, if the executing user has appropriate privileges.
+  
+
+  
+   createdb is a shell script wrapper around the
+   SQL command
+    via
+   the PostgreSQL interactive terminal
+   . Thus, there is nothing
+   special about creating databases via this or other methods. This means
+   that the psql 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 psql
+   and the libpq front-end library will apply.
+  
+ 
+
+
+ 
+  Options
 
     
      
@@ -149,6 +179,7 @@ PostgreSQL documentation
 
     
 
+   
     The options -h, -p, -U,
     -W, and -e are passed on literally to
     .
@@ -160,13 +191,12 @@ PostgreSQL documentation
     endterm="SQL-CREATEDATABASE-title">; see there for more information
     about them.
    
-  
+ 
+
+
+ 
+  Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
-   
     
      
       CREATE DATABASE
@@ -195,45 +225,37 @@ PostgreSQL documentation
      
     
 
+   
     If there is an error condition, the backend error message will be displayed.
     See 
     and  for possibilities.
    
-  
- 
+ 
 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-  
-   createdb creates a new PostgreSQL
-   database.
-  
 
-  
-   Normally, the database user who executes this command becomes the owner of
-   the new database.
-   However a different owner can be specified via the -O
-   option, if the executing user has appropriate privileges.
-  
+ 
+  Environment
 
-  
-   createdb is a shell script wrapper around the
-   SQL command
-    via
-   the PostgreSQL interactive terminal
-   . Thus, there is nothing
-   special about creating databases via this or other methods. This means
-   that the psql 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 psql
-   and the libpq front-end library will apply.
-  
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters.  PGUSER also
+      determines the name of the database to create, if it is not
+      specified in the command line.
+     
+    
+   
+  
  
 
+
  
-  <span class="marked">Usage</span>
+  <span class="marked">Examples</span>
 
   
    
@@ -262,6 +284,17 @@ PostgreSQL documentation
    
   
  
+
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -11,7 +11,7 @@ PostgreSQL documentation
  
 
  
-   id="createlang">createlang
+  createlang
   define a new PostgreSQL procedural language
  
 
@@ -27,11 +27,33 @@ PostgreSQL documentation
    --list-l
    dbname
   
+ 
+
+ 
+ 
+  Description
+
+  
+   createlang is a utility for adding a new 
+   programming language to a PostgreSQL database.
+   createlang can handle all the languages
+   supplied in the default PostgreSQL distribution, but
+   not languages provided by other parties.
+  
+  
+   Although backend programming languages can be added directly using
+   several SQL commands, it is recommended to use
+   createlang because it performs a number
+   of checks and is much easier to use. See
+   
+   for more.
+  
+ 
+
+
+ 
+  Options
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
    
     createlang accepts the following command line arguments:
     
@@ -138,12 +160,31 @@ PostgreSQL documentation
 
     
    
-  
+ 
+
+
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
+ 
+
+
+ 
+  Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
    
     Most error messages are self-explanatory. If not, run
     createlang with the --echo
@@ -151,35 +192,12 @@ PostgreSQL documentation
     for details. Check also under 
     for more possibilities.
    
-  
- 
- 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-
-  
-   createlang is a utility for adding a new 
-   programming language to a PostgreSQL database.
-   createlang can handle all the languages
-   supplied in the default PostgreSQL distribution, but
-   not languages provided by other parties.
-  
-  
-   Although backend programming languages can be added directly using
-   several SQL commands, it is recommended to use
-   createlang because it performs a number
-   of checks and is much easier to use. See
-   
-   for more.
-  
  
 
- 
-  >
-   Notes
-  
+
+ >
+  Notes
+
   
    Use  to remove a language.
   
@@ -192,8 +210,9 @@ PostgreSQL documentation
   
  
  
- 
-  Usage
+
+ 
+  Examples
 
   
    
@@ -205,6 +224,16 @@ PostgreSQL documentation
    
   
  
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -21,12 +21,46 @@ PostgreSQL documentation
    options
    username
   
+ 
+  
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
-   
+ 
+  Description
+  
+   createuser creates a 
+   new PostgreSQL user.  
+   Only superusers (users with usesuper set in
+   the pg_shadow table) can create 
+   new PostgreSQL users,
+   so createuser must be
+   invoked by someone who is a PostgreSQL
+   superuser.
+  
+
+  
+   Being a superuser also implies the ability to bypass access permission
+   checks within the database, so superuser-dom should not be granted lightly.
+  
+
+  
+   createuser is a shell script wrapper around the
+   SQL command
+    via
+   the PostgreSQL interactive terminal
+   . Thus, there is nothing
+   special about creating users via this or other methods. This means
+   that the psql 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 psql
+   and the libpq front-end library will apply.
+  
+
+ 
+
+
+ 
+  Options
 
     
      
@@ -162,6 +196,7 @@ PostgreSQL documentation
        
     
 
+   
     You will be prompted for a name and other missing information if it is not
     specified on the command line.
     
@@ -172,13 +207,31 @@ PostgreSQL documentation
     psql options -U and -W
     are available as well, but their use can be confusing in this context.
    
-  
+ 
+
+
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters
+     
+    
+   
+  
+ 
+
+
+ 
+  Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
-   
     
      
       CREATE USER
@@ -200,52 +253,16 @@ PostgreSQL documentation
 
     
 
+   
     If there is an error condition, the backend error message will be displayed.
     See 
     and  for possibilities.
    
-  
- 
-  
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-  
-   createuser creates a 
-   new PostgreSQL user.  
-   Only superusers (users with usesuper set in
-   the pg_shadow table) can create 
-   new PostgreSQL users,
-   so createuser must be
-   invoked by someone who is a PostgreSQL
-   superuser.
-  
-
-  
-   Being a superuser also implies the ability to bypass access permission
-   checks within the database, so superuser-dom should not be granted lightly.
-  
-
-  
-   createuser is a shell script wrapper around the
-   SQL command
-    via
-   the PostgreSQL interactive terminal
-   . Thus, there is nothing
-   special about creating users via this or other methods. This means
-   that the psql 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 psql
-   and the libpq front-end library will apply.
-  
-
  
 
 
-  id="R1-APP-CREATEUSER-2">
-  <span class="marked">Usage</span>
+ 
+  <span class="marked">Examples</span>
 
   
    
@@ -274,6 +291,16 @@ PostgreSQL documentation
   
  
 
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -21,12 +21,36 @@ PostgreSQL documentation
    options
    dbname
   
+ 
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
-   
+
+ 
+  Description
+
+  
+   dropdb destroys an existing
+   PostgreSQL database.
+   The user who executes this command must be a database
+   superuser or the owner of the database.
+  
+
+  
+   dropdb is a shell script wrapper around the
+   SQL command
+    via
+   the PostgreSQL interactive terminal
+   . Thus, there is nothing
+   special about dropping databases via this or other methods. This means
+   that the psql 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 psql
+   and the libpq front-end library do apply.
+  
+ 
+
+
+ 
+   Options
 
     
      
@@ -110,18 +134,16 @@ PostgreSQL documentation
      
     
 
+   
     The options -h, -p, -U,
     -W, and -e are passed on literally to
     .
    
-  >
+ >
 
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
-   
+ 
+   Diagnostics
 
     
      
@@ -139,41 +161,35 @@ PostgreSQL documentation
      
     
 
+   
     If there is an error condition, the backend error message will be displayed.
     See 
     and  for possibilities.
    
-  
- 
+ 
 
 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-  
-   dropdb destroys an existing
-   PostgreSQL database.
-   The user who executes this command must be a database
-   superuser or the owner of the database.
-  
+ 
+  Environment
 
-  
-   dropdb is a shell script wrapper around the
-   SQL command
-    via
-   the PostgreSQL interactive terminal
-   . Thus, there is nothing
-   special about dropping databases via this or other methods. This means
-   that the psql 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 psql
-   and the libpq front-end library do apply.
-  
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters
+     
+    
+   
+  
  
 
+
  
-  <span class="marked">Usage</span>
+  <span class="marked">Examples</span>
 
   
    
@@ -201,6 +217,17 @@ DROP DATABASE
    
   
  
+
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -11,7 +11,7 @@ PostgreSQL documentation
  
 
  
-   id="droplang">droplang
+  droplang
   remove a PostgreSQL procedural language
  
 
@@ -27,11 +27,34 @@ PostgreSQL documentation
    --list-l
    dbname
   
+ 
+ 
+ 
+  </div>
<div class="diff add">+   Description</div>
<div class="diff add">+  
+
+  
+   droplang is a utility for removing an 
+   existing programming language from a
+   PostgreSQL database.
+   droplang can drop any procedural language,
+   even those not supplied by the PostgreSQL distribution.
+  
+  
+   Although backend programming languages can be removed directly using
+   several SQL commands, it is recommended to use
+   droplang because it performs a number
+   of checks and is much easier to use. See
+   
+   for more.
+  
+ 
+
+
+ 
+  Options
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
    
     droplang accepts the following command line arguments:
     
@@ -126,12 +149,31 @@ PostgreSQL documentation
 
     
    
-  
+ 
+
+
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
+ 
+
+
+ 
+   Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
    
     Most error messages are self-explanatory. If not, run
     droplang with the --echo
@@ -139,43 +181,20 @@ PostgreSQL documentation
     for details. Check also under 
     for more possibilities.
    
-  
- 
- 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-
-  
-   droplang is a utility for removing an 
-   existing programming language from a
-   PostgreSQL database.
-   droplang can drop any procedural language,
-   even those not supplied by the PostgreSQL distribution.
-  
-  
-   Although backend programming languages can be removed directly using
-   several SQL commands, it is recommended to use
-   droplang because it performs a number
-   of checks and is much easier to use. See
-   
-   for more.
-  
  
 
- 
-  </div>
<div class="diff rem">-   Notes</div>
<div class="diff rem">-  
+
+ 
+  Notes
 
   
    Use  to add a language.
   
  
  
- 
-  Usage
+
+ 
+  Examples
 
   
    
@@ -186,6 +205,16 @@ PostgreSQL documentation
    
   
  
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -21,12 +21,38 @@ PostgreSQL documentation
    options
    username
   
+ 
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
-   
+
+ 
+  Description
+
+  
+   dropuser removes an existing
+   PostgreSQL user
+   and the databases which that user owned.
+   Only users with usesuper set in
+   the pg_shadow table can destroy 
+   PostgreSQL users.
+  
+
+  
+   dropuser is a shell script wrapper around the
+   SQL command
+    via
+   the PostgreSQL interactive terminal
+   . Thus, there is nothing
+   special about removing users via this or other methods. This means
+   that the psql 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 psql
+   and the libpq front-end library do apply.
+  
+ 
+
+
+ 
+  Options
 
     
      
@@ -91,7 +117,6 @@ PostgreSQL documentation
       
      
     
-    
 
     
     The options -h, -p, and -e,
@@ -99,14 +124,31 @@ PostgreSQL documentation
     psql options -U and -W
     are available as well, but they can be confusing in this context.
    
-  >
+ >
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
 
-   
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters
+     
+    
+   
+  
+ 
+
+
+ 
+   Diagnostics
+
     
      
       DROP USER
@@ -128,43 +170,16 @@ PostgreSQL documentation
 
     
 
+   
     If there is an error condition, the backend error message will be displayed.
     See 
     and  for possibilities.
    
-  
- 
-
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
-  
-   dropuser removes an existing
-   PostgreSQL user
-   and the databases which that user owned.
-   Only users with usesuper set in
-   the pg_shadow table can destroy 
-   PostgreSQL users.
-  
-
-  
-   dropuser is a shell script wrapper around the
-   SQL command
-    via
-   the PostgreSQL interactive terminal
-   . Thus, there is nothing
-   special about removing users via this or other methods. This means
-   that the psql 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 psql
-   and the libpq front-end library do apply.
-  
-
  
 
- 
-  Usage
+
+ 
+  Examples
 
   
    
@@ -193,6 +208,16 @@ DROP USER
   
  
 
+
+ 
+  See Also
+
+  
+   
+   
+  
+ 
+
 
 
 
 
@@ -9,6 +9,7 @@ PostgreSQL documentation
   1
   Application
  
+
  
   
    ecpg
@@ -17,6 +18,7 @@ PostgreSQL documentation
    embedded SQL C preprocessor
   
  
+
  
   
    1999-07-20
@@ -29,14 +31,33 @@ PostgreSQL documentation
    -o outfile
    file
   
+ 
+
+ 
+  Description
+
+  
+   ecpg
+   is an embedded SQL preprocessor for the C language and the
+   PostgreSQL. It
+   enables development of C programs with embedded SQL code.
+  
+
+  
+   Linus Tolke ([email protected]) was the
+   original author of ecpg (up to version 0.2).
+   Michael Meskes ([email protected])
+   is the current author and maintainer of ecpg.
+   Thomas Good ([email protected])
+   is the author of the last revision of the ecpg man page, on which
+   this document is based.
+  
+ 
+
+
+ 
+  Options
 
-  
-   
-    1999-07-20
-   
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
    
     ecpg accepts the following command
     line arguments:
@@ -104,58 +125,23 @@ PostgreSQL documentation
      
     
    
-  
-
-  
-   
-    1998-11-05
-   
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
-   
-    ecpg will create a file or
-    write to stdout.
+ 
 
-    
-     
-      Return value
-      
-       
-   ecpg returns 0 to the shell on successful completion, non-zero
-   for errors.
-       
-      
-     
-    
-   
-  
- 
 
- 
-  Description
-  
-   ecpg
-   is an embedded SQL preprocessor for the C language and the
-   PostgreSQL. It
-   enables development of C programs with embedded SQL code.
-  
+ 
+  Exit Status
 
   
-   Linus Tolke ([email protected]) was the
-   original author of ecpg (up to version 0.2).
-   Michael Meskes ([email protected])
-   is the current author and maintainer of ecpg.
-   Thomas Good ([email protected])
-   is the author of the last revision of the ecpg man page, on which
-   this document is based.
+   ecpg returns 0 to the shell on
+   successful completion, non-zero for errors.
   
  
 
- 
+
+ 
   Usage
 
-  R2-APP-ECPG-preprocessing">
+  
    Preprocessing for Compilation
 
    
@@ -175,7 +161,7 @@ ecpg [ -d ] [ -o file ] file
    
   
 
-  R2-APP-ECPG-compiling">
+  
    Compiling and Linking
 
    
@@ -190,10 +176,10 @@ gcc -g -I /usr/local/pgsql/include [ -o file ] 
   
  
 
- R1-APP-ECPG-grammar">
+ 
   Grammar
 
-  R2-APP-ECPG-library">
+  
    Libraries
 
    
@@ -206,7 +192,7 @@ gcc -g -I /usr/local/pgsql/include [ -o file ] 
    
   
 
-  R2-APP-declaration">
+  APP-ecpg-declaration">
    Variable Declaration
 
    
@@ -237,7 +223,7 @@ char  foo[16], bar[16];
    
   
 
-  R2-APP-ECPG-errors">
+  
    Error Handling
 
    
@@ -292,7 +278,7 @@ EXEC SQL WHENEVER not found sqlprint;
     
   
 
-  R2-APP-ECPG-connecting">
+  
    Connecting to the Database Server
 
    
@@ -322,7 +308,7 @@ EXEC SQL CONNECT TO dbname;
    
   
 
-  R2-APP-ECPG-queries">
+  
    Queries
 
    
@@ -393,7 +379,7 @@ EXEC SQL COMMIT;
   
  
 
- R1-APP-ECPG-notes">
+ 
   Notes
   
    The complete structure definition MUST be listed
@@ -406,6 +392,17 @@ EXEC SQL COMMIT;
   
 
  
+
+
+ 
+  See Also
+
+  
+   PostgreSQL Programmer's Guide for a more
+   detailed description of the embedded SQL interface.
+  
+ 
+
 
 
 
 
@@ -39,7 +39,7 @@ PostgreSQL documentation
  
 
  
-  <span class="marked">Usage</span>
+  <span class="marked">Examples</span>
 
   
    
@@ -68,6 +68,15 @@ PostgreSQL documentation
    
   
  
+
+ 
+  See Also
+
+  
+   PostgreSQL Administrator's Guide
+  
+ 
+
 
 
 
 
@@ -225,9 +225,32 @@ PostgreSQL documentation
     
    
   
+ 
+
+
+ 
+  Environment
 
-  
-   Files
+  
+   
+    PGDATA
+
+    
+     
+      Default data direction location
+     
+    
+   
+  
+
+  
+   For others, see .
+  
+ 
+
+
+ 
+  Files
 
    
     If the file postmaster.opts.default exists in
@@ -235,8 +258,17 @@ PostgreSQL documentation
     options to the postmaster, unless
     overridden by the -o option.
    
-  
+ 
+
 
+ 
+  Notes
+
+  
+   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.
+  
  
 
 
@@ -330,15 +362,6 @@ Command line was:
   
  
 
- 
-  Bugs
-
-  
-   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.
-  
- 
 
  
   See Also

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d2ab719fe341d225a73cc169f5741b8951135e1c..7969489f11c3e54c487b695c168148e73618c8ac 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
 
 
@@ -582,6 +582,34 @@ PostgreSQL documentation
 
  
 
+ 
+  Environment
+
+  
+   
+    PGDATABASE
+
+    
+     
+      Database to dump, unless overridden on the command line.
+     
+    
+   
+
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters
+     
+    
+   
+  
+ 
+
  
   Diagnostics
 

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 44e38f28bc6c87ee48f628b7436e8afc78ad7b1f..9e5f4452d0dd86c3812e543bcd34d96b329737a1 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -1,5 +1,5 @@
 
 
@@ -152,6 +152,26 @@ PostgreSQL documentation
   
  
 
+
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
+ 
+
+
  
   Examples
   

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 0d951621d16e66bc51af67d49facdc8ac52a17e2..e89d76bbc1b8e1bf2c1c80ba2e19289662cb13ca 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  
@@ -496,6 +496,25 @@
  
 
 
+ 
+  Environment
+
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
+ 
+
+
  
   Diagnostics
 

diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index f78c053320102a5766d1d91ca105174e492c98a7..a242dcc863d5f2389ff06be967d95c3b7acfee86 100644 (file)
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
 
 
@@ -349,6 +349,28 @@ PostgreSQL documentation
   
  
 
+ 
+  Environment
+
+  
+   
+    PGDATA
+
+    
+     
+      Default data direction location
+     
+    
+   
+
+  
+
+  
+   For others, which have little influence during single-user mode,
+   see .
+  
+ 
+
  
   Usage
 

diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 0d2a7e93dd269f7ca5957a27c5cb93f690e855fd..f052e5af6eeeea3069f21365e59edb31ed44a3fd 100644 (file)
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
 
 
@@ -338,10 +338,82 @@ PostgreSQL documentation
    
   
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
+ 
+
+ 
+  Environment
+
+  
+   
+    PGCLIENTENCODING
+
+    
+     
+      Default character encoding used by clients.  (The clients may
+      override this invidiually.)  This value can also be set in the
+      configuration file.
+     
+    
+   
+
+   
+    PGDATA
+
+    
+     
+      Default data direction location
+     
+    
+   
+
+   
+    PGDATASTYLE
+
+    
+     
+      Default value of the datestyle run-time
+      parameter.  (The use of this environment variable is deprecated.)
+     
+    
+   
+
+   
+    PGPORT
+
+    
+     
+      Default port (preferrably set in the configuration file)
+     
+    
+   
+
+   
+    TZ
+
+    
+     
+      Server time zone
+     
+    
+   
+
+   
+    others
+
+    
+     
+      Other environment variables may be used to designate alternative
+      data storage locations.  See the Administrator's
+      Guide for more information.
+     
+    
+   
+
+  
+ 
+
+ 
+   Diagnostics
    
 
     
@@ -417,7 +489,6 @@ StreamServerPort: cannot bind to port
      
     
    
-  
  
 
  
@@ -457,8 +528,8 @@ StreamServerPort: cannot bind to port
 
  
 
- usage">
-  <span class="marked">Usage</span>
+ examples">
+  <span class="marked">Examples</span>
   
    To start postmaster 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 923a87411127d79dca7715dcb49c0c35948860fc..b9f8554abfb6a7d6fd14267a6f2a67ba448ea516 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,13 +1,9 @@
 
 
 
- 
-  2000-12-25
- 
-
   
     psql
     1
@@ -21,19 +17,17 @@ PostgreSQL documentation
     
   
 
-  
-    
-      1999-10-26
-    
-
-    psql [ options ] [ dbname [ user ] ]
+ 
+  
+   psql
+   options
+   dbname
+     user
+  
+ 
 
-  
-    
-      1998-09-26
-    
-
-    Summary
+ 
+  Description
 
     
      psql 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.
     
+ 
 
-  
+ 
+  Options
 
-
+  
+   If so configured, psql understands both
+   standard Unix short options, and GNU-style long
+   options. The latter are not available on all systems.
+  
 
-
-  
-    1998-10-26
-  
+  
+    
+      -a, --echo-all
+      
+      
+      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 ECHO to
+      all.
+      
+      
+    
 
-  Description
+    
+      -A, --no-align
+      
+      
+      Switches to unaligned output mode. (The default output mode is
+      otherwise aligned.)
+      
+      
+    
+   
+    
+      -c, --command query
+      
+      
+      Specifies that psql is to execute one
+      query string, query,
+      and then exit. This is useful in shell scripts.
+      
+      
+      query must be either
+      a query string that is completely parseable by the backend (i.e.,
+      it contains no psql specific features),
+      or it is a single backslash command. Thus you cannot mix
+      SQL and psql
+      meta-commands. To achieve that, you could pipe the string into
+      psql, like this: echo "\x \\
+      select * from foo;" | psql.
+      
+      
+    
 
-  
-    
-      2000-01-14
-    
-   
-    Connecting To A Database
+    
+      -d, --dbname dbname
+      
+      
+      Specifies the name of the database to connect to. This is
+      equivalent to specifying 
+      class="parameter">dbname as the first non-option
+      argument on the command line.
+      
+      
+    
 
-    
-    psql is a regular
-    PostgreSQL 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. psql can be
-    told about those parameters via command line options, namely
-    -d, -h, -p, and
-    -U 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
-    PGDATABASE, PGHOST,
-    PGPORT and PGUSER to appropriate
-    values.
-    
+    
+      -e, --echo-queries
+      
+      
+      Show all queries that are sent to the backend. This is equivalent
+      to setting the variable ECHO to
+      queries.
+      
+      
+    
 
-    
-    If the connection could not be made for any reason (e.g., insufficient
-    privileges, postmaster is not running on the server, etc.),
-    psql will return an error and terminate.
-    
-  
+    
+      -E, --echo-hidden
+      
+      
+      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 ECHO_HIDDEN from within
+      psql.
+      
+      
+    
 
-  
-    
-      1998-09-26
-    
+    
+      -f, --file filename
+      
+      
+      Use the file filename
+      as the source of queries instead of reading queries interactively.
+      After the file is processed, psql
+      terminates. This is in many ways equivalent to the internal
+      command \i.
+      
 
-    Entering Queries
+      
+       If filename is -
+       (hyphen), then standard input is read.
+      
 
-    
-    In normal operation, psql provides a
-    prompt with the name of the database to which
-    psql is currently connected, followed by
-    the string =>. For example,
-
-$ psql testdb
-Welcome to psql, the PostgreSQL interactive terminal.
+      
+      Using this option is subtly different from writing psql
+      < 
+      class="parameter">filename. In general,
+      both will do what you expect, but using -f
+      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.
+      
+      
+    
 
-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
+    
+      -F, --field-separator separator
+      
+      
+      Use separator as the
+      field separator. This is equivalent to \pset
+      fieldsep or \f.
+      
+      
+    
 
-testdb=>
-
-    
+    
+      -h, --host hostname
+      
+      
+      Specifies the host name of the machine on which the
+      postmaster is running. If host begins
+      with a slash, it is used as the directory for the unix domain
+      socket.
+      
+      
+    
 
-    
-    At the prompt, the user may type in SQL 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.
-    
+    
+      -H, --html
+      
+      
+      Turns on HTML tabular output. This is
+      equivalent to \pset format html or the
+      \H command.
+      
+      
+    
+ 
+    
+      -l, --list
+      
+      
+      Lists all available databases, then exits. Other non-connection
+      options are ignored. This is similar to the internal command
+      \list.
+      
+      
+    
 
-    
-    Whenever a query is executed, psql also polls
-    for asynchronous notification events generated by
-     and
-    .
-    
-  
-
+    
+      -o, --output filename
+      
+      
+      Put all query output into file 
+      class="parameter">filename. This is equivalent to
+      the command \o.
+      
+      
+    
 
-
-    
-      1998-09-26
-    
+    
+      -p, --port port
+      
+      
+      Specifies the TCP/IP port or, by omission, the local Unix domain
+      socket file extension on which the
+      postmaster is listening for
+      connections. Defaults to the value of the PGPORT
+      environment variable or, if not set, to the port specified at
+      compile time, usually 5432.
+      
+      
+    
 
-    <application>psql</application> Meta-Commands
+    
+      -P, --pset assignment
+      
+      
+      Allows you to specify printing options in the style of
+      \pset 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
+      -P format=latex.
+      
+      
+    
 
-    
-    Anything you enter in psql that begins
-    with an unquoted backslash is a psql
-    meta-command that is processed by psql
-    itself. These commands are what makes
-    psql interesting for administration or
-    scripting. Meta-commands are more commonly called slash or backslash
-    commands.
-    
-
-    
-    The format of a psql 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.
-    
-
-    
-    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
-    \n (new line), \t (tab),
-    \digits,
-    \0digits, and
-    \0xdigits (the
-    character with the given decimal, octal, or hexadecimal code).
-    
-
-    
-    If an unquoted argument begins with a colon (:),
-    it is taken as a variable and the value of the variable is taken as
-    the argument instead.
-    
-
-    
-    Arguments that are quoted in backticks
-    (`) 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.
-    
-
-    
-    Some commands take the name of an SQL identifier
-    (such as a table name) as argument. These arguments follow the
-    syntax rules of SQL 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.
-    
-
-    
-    Parsing for arguments stops when another unquoted backslash occurs.
-    This is taken as the beginning of a new meta-command. The special
-    sequence \\ (two backslashes) marks the end of
-    arguments and continues parsing SQL queries, if
-    any. That way SQL and
-    psql 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.
-    
-
-    
-    The following meta-commands are defined:
+    
+      -q
+      
+      
+      Specifies that psql 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 -c option.
+      Within psql you can also set the
+      QUIET variable to achieve the same effect.
+      
+      
+    
 
-    
-      
-        \a
-        
-        
-   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 \pset for a
-   general solution.
-        
-        
-      
+    
+      -R, --record-separator separator
+      
+      
+      Use separator as the
+      record separator. This is equivalent to the \pset
+      recordsep command.
+      
+      
+    
+ 
+    
+      -s, --single-step
+      
+      
+      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.
+      
+      
+    
 
-      
-       \cd directory
-       
-        
-    Change the current working directory to
-    directory. Without argument, change
-    to the current user's home directory.
-        
+    
+      -S, --single-line
+      
+      
+      Runs in single-line mode where a newline terminates a query, as a
+      semicolon does.
+      
 
-   
-    
-     To print your current working directory, use \!pwd.
-    
-   
-       
-      
+      
+      
+      This mode is provided for those who insist on it, but you are not
+      necessarily encouraged to use it. In particular, if you mix
+      SQL and meta-commands on a line the order of
+      execution might not always be clear to the inexperienced user.
+      
+      
+      
+    
 
-      
-        \C [ title ]
-        
-        
-        Set the title of any tables being printed as the result of a
-        query or unset any such title. This command is equivalent to
-        \pset title 
-        class="parameter">title. (The name of
-        this command derives from caption, as it was
-        previously only used to set the caption in an
-        HTML table.)
-        
-        
-      
+    
+      -t, --tuples-only
+      
+      
+      Turn off printing of column names and result row count footers,
+      etc. It is completely equivalent to the \t
+      meta-command.
+      
+      
+    
 
-      
-        \connect (or \c) [ dbname [ username ] ]
-        
-        
-   Establishes a connection to a new database and/or under a user
-   name. The previous connection is closed. If 
-   class="parameter">dbname is -
-   the current database name is assumed.
-   
+    
+      -T, --table-attr table_options
+      
+      
+      Allows you to specify options to be placed within the
+      HTML table tag. See
+      \pset for details.
+      
+      
+    
+ 
+    
+      -u
+      
+      
+      Makes psql prompt for the user name and
+      password before connecting to the database.
+      
 
-   
-   If username is
-   omitted the current user name is assumed. 
+      
+      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 -U and
+      -W options instead.
+      
+      
+    
 
-   
-   As a special rule, \connect without any
-   arguments will connect to the default database as the default
-   user (as you would have gotten by starting
-   psql without any arguments).
-   
+    
+      -U, --username username
+      
+      
+      Connects to the database as the user 
+      class="parameter">username instead of the default.
+      (You must have permission to do so, of course.)
+       
+      
+    
 
-   
-   If the connection attempt failed (wrong user name, access
-   denied, etc.), the previous connection will be kept if and only
-   if psql 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.
-   
-        
-      
+    
+      -v, --variable, --set assignment
+      
+      
+      Performs a variable assignment, like the \set
+      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.
+      
+      
+    
 
-      
-        \copy table
-        { from | to }
-   filename | stdin | stdout
-        [ with ] 
-            [ oids ] 
-            [ delimiter [as]  'character' ]
-            [ null [as]  'string' ]
-        
+    
+      -V, --version
+      
+      
+      Shows the psql version.
+      
+      
+    
 
-        
-        
-        Performs a frontend (client) copy. This is an operation that
-        runs an SQL 
-        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,
-        psql reads or writes the file and
-        routes the data between the backend and the local file system.
-   
+    
+      -W, --password
+      
+      
+      Requests that psql 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 \connect.
+      
 
-   
-   The syntax of the command is similar to that of the
-   SQL COPY command (see its
-   description for the details). Note that, because of this,
-   special parsing rules apply to the \copy
-   command. In particular, the variable substitution rules and
-   backslash escapes do not apply.
-   
+      
+      In the current version, psql
+      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.
+      
+      
+    
 
-        
-        
-   This operation is not as efficient as the SQL
-   COPY 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.
-        
-        
+    
+      -x, --expanded
+      
+      
+      Turns on extended row format mode. This is equivalent to the
+      command \x.
+      
+      
+    
 
-        
-        
-        Note the difference in interpretation of
-        stdin and stdout between
-        frontend and backend copies: in a frontend copy these always
-        refer to psql's input and output
-        stream. On a backend copy stdin comes from
-        wherever the COPY itself came from (for
-        example, a script run with the -f option), and
-        stdout refers to the query output stream (see
-        \o meta-command below).
-        
-        
-        
-      
+    
+      -X, --no-psqlrc
+      
+      
+      Do not read the start-up file ~/.psqlrc.
+      
+      
+    
 
-      
-        \copyright
-        
-        
-        Shows the copyright and distribution terms of
-        PostgreSQL.
-        
-        
-      
+    
+      -?, --help
+      
+      
+      Shows help about psql command line
+      arguments.
+      
+      
+    
+  
+ 
 
-      
-        \d relation 
 
-        
-        
-   Shows all columns of 
-   class="parameter">relation (which could be a
-   table, view, index, or sequence), their types, and any special
-   attributes such as NOT NULL 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.
-   
+ 
+  Exit Status
 
-   
-   The command form \d+ is identical, but any
-   comments associated with the table columns are shown as well.
-   
+  
+   psql 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 ON_ERROR_STOP was set.
+  
+ 
 
-   
-   
-   If \d is called without any arguments, it is
-   equivalent to \dtvs which will show a list of
-   all tables, views, and sequences. This is purely a convenience
-   measure.
-   
-   
-   
-      
 
-      >
-        \da [ pattern ]>
+ >
+  Usage</title</span>></div>
<div class="diff ctx"> </div>
<div class="diff rem">-        <listitem></div>
<div class="diff rem">-        <para></div>
<div class="diff rem">-        Lists all available aggregate functions, together with the data</div>
<div class="diff rem">-        type they operate on. If <replaceable</div>
<div class="diff rem">-        class="parameter">pattern</replaceable> (a regular expression)</div>
<div class="diff rem">-        is specified, only matching aggregates are shown.</div>
<div class="diff rem">-        </para></div>
<div class="diff rem">-        </listitem></div>
<div class="diff rem">-      </varlistentry></div>
<div class="diff add">+  <refsect2 id="R2-APP-PSQL-connecting"></div>
<div class="diff add">+    <title>Connecting To A Database
 
-      
-        \dd [ object ]
-        
-        
-        Shows the descriptions of 
-        class="parameter">object (which can be a regular
-        expression), or of all objects if no argument is given.
-        (Object covers aggregates, functions, operators,
-        types, relations (tables, views, indexes, sequences, large
-        objects), rules, and triggers.) For example:
-
-=> \dd version
-              Object descriptions
-  Name   |   What   |        Description
----------+----------+---------------------------
- version | function | PostgreSQL version string
-(1 row)
-
-        
+    
+    psql is a regular
+    PostgreSQL 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. psql can be
+    told about those parameters via command line options, namely
+    -d, -h, -p, and
+    -U 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
+    PGDATABASE, PGHOST,
+    PGPORT and PGUSER to appropriate
+    values.
+    
 
-        
-        Descriptions for objects can be generated with the
-        COMMENT ON SQL command.
-   
+    
+    If the connection could not be made for any reason (e.g., insufficient
+    privileges, postmaster is not running on the server, etc.),
+    psql will return an error and terminate.
+    
+  
 
-        
-        
-        PostgreSQL stores the object
-        descriptions in the pg_description system table.
-        
-        
+  
+    Entering Queries
 
-        
-      
+    
+    In normal operation, psql provides a
+    prompt with the name of the database to which
+    psql is currently connected, followed by
+    the string =>. For example,
+
+$ psql testdb
+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
 
-      
-        \dD [ pattern ]
-        
-        
-        Lists all available domains (derived types). If 
-        class="parameter">pattern (a regular expression)
-        is specified, only matching domains are shown.
-        
-        
-      
+testdb=>
+
+    
 
+    
+    At the prompt, the user may type in SQL 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.
+    
 
-      
-        \df [ pattern ]
+    
+    Whenever a query is executed, psql also polls
+    for asynchronous notification events generated by
+     and
+    .
+    
+  
 
-        
-        
-        Lists available functions, together with their argument and
-        return types. If 
-        class="parameter">pattern (a regular expression)
-        is specified, only matching functions are shown. If the form
-        \df+ is used, additional information about
-        each function, including language and description, is shown.
-        
-        
-      
+  
+    Meta-Commands
 
+    
+    Anything you enter in psql that begins
+    with an unquoted backslash is a psql
+    meta-command that is processed by psql
+    itself. These commands are what makes
+    psql interesting for administration or
+    scripting. Meta-commands are more commonly called slash or backslash
+    commands.
+    
 
-      
-        \distvS [ pattern ]
+    
+    The format of a psql 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.
+    
 
-   
-   
-   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.
-   
+    
+    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
+    \n (new line), \t (tab),
+    \digits,
+    \0digits, and
+    \0xdigits (the
+    character with the given decimal, octal, or hexadecimal code).
+    
 
-   
-   If pattern is
-   specified, it is a regular expression that restricts the listing
-   to those objects whose name matches. If one appends a
-   + to the command name, each object is listed with
-   its associated description, if any.
-   
-   
-      
+    
+    If an unquoted argument begins with a colon (:),
+    it is taken as a variable and the value of the variable is taken as
+    the argument instead.
+    
+
+    
+    Arguments that are quoted in backticks
+    (`) 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.
+    
 
+    
+    Some commands take the name of an SQL identifier
+    (such as a table name) as argument. These arguments follow the
+    syntax rules of SQL 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.
+    
 
-      
-        \dl
-   
-   
-   This is an alias for \lo_list, which shows a
-   list of large objects.
-   
-   
-      
+    
+    Parsing for arguments stops when another unquoted backslash occurs.
+    This is taken as the beginning of a new meta-command. The special
+    sequence \\ (two backslashes) marks the end of
+    arguments and continues parsing SQL queries, if
+    any. That way SQL and
+    psql 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.
+    
 
+    
+    The following meta-commands are defined:
 
+    
       
-        \do [ name ]
+        \a
         
         
-        Lists available operators with their operand and return types.
-        If name 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 \pset for a
+   general solution.
         
         
       
 
-
-      
-        \dp [ pattern ]
-   
-   
-   This is an alias for \z which was included
-   for its greater mnemonic value (display
-   permissions).
-   
-   
-      
-
-
       
-        \dT [ pattern ]al>
-        
+       \cd directoryal>
+       
         
-        Lists all data types or only those that match 
-        class="parameter">pattern. The command form
-        \dT+ shows extra information.
+    Change the current working directory to
+    directory. Without argument, change
+    to the current user's home directory.
         
-        
-      
 
+   
+    
+     To print your current working directory, use \!pwd.
+    
+   
+       
+      
 
       
-        \du [ pattern ]
+        \C [ title ]
         
         
-        Lists all configured users or only those that match 
-        class="parameter">pattern.
+        Set the title of any tables being printed as the result of a
+        query or unset any such title. This command is equivalent to
+        \pset title 
+        class="parameter">title. (The name of
+        this command derives from caption, as it was
+        previously only used to set the caption in an
+        HTML table.)
         
         
       
 
-
       
-        \edit (or \e) [ filename ]
-
+        \connect (or \c) [ dbname [ username ] ]
         
         
-        If filename 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.
-        
-
-        
-        The new query buffer is then re-parsed according to the normal
-        rules of psql, where the whole buffer
-        is treated as a single line. (Thus you cannot make scripts this
-        way. Use \i 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.
-        
-
-        
-        
-        psql searches the environment
-        variables PSQL_EDITOR, EDITOR, and
-        VISUAL (in that order) for an editor to use. If
-        all of them are unset, /bin/vi is run.
-        
-        
-        
-      
+   Establishes a connection to a new database and/or under a user
+   name. The previous connection is closed. If 
+   class="parameter">dbname is -
+   the current database name is assumed.
+   
 
+   
+   If username is
+   omitted the current user name is assumed. 
 
-      
-        \echo text [ ... ]
-        
    
-        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:
-
-=> \echo `date`
-Tue Oct 26 21:40:57 CEST 1999
-
-        If the first argument is an unquoted -n the the trailing
-        newline is not written.
+   As a special rule, \connect without any
+   arguments will connect to the default database as the default
+   user (as you would have gotten by starting
+   psql without any arguments).
    
 
-   
    
-   If you use the \o command to redirect your
-   query output you may wish to use \qecho
-   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 psql 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.
    
-   
-   
+        
       
 
-
       
-        \encoding [ encoding ]
+        \copy table
+        { from | to }
+   filename | stdin | stdout
+        [ with ] 
+            [ oids ] 
+            [ delimiter [as]  'character' ]
+            [ null [as]  'string' ]
+        
 
         
         
-        Sets the client encoding, if you are using multibyte encodings.
-        Without an argument, this command shows the current encoding.
-        
-        
-      
+        Performs a frontend (client) copy. This is an operation that
+        runs an SQL 
+        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,
+        psql reads or writes the file and
+        routes the data between the backend and the local file system.
+   
 
+   
+   The syntax of the command is similar to that of the
+   SQL COPY command (see its
+   description for the details). Note that, because of this,
+   special parsing rules apply to the \copy
+   command. In particular, the variable substitution rules and
+   backslash escapes do not apply.
+   
 
-      
-        \f [ string ]
+        
+        
+   This operation is not as efficient as the SQL
+   COPY 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.
+        
+        
 
-        <listitem>
+        <note>
         
-        Sets the field separator for unaligned query output. The default
-        is pipe (|). See also
-        \pset for a generic way of setting output
-        options.
+        Note the difference in interpretation of
+        stdin and stdout between
+        frontend and backend copies: in a frontend copy these always
+        refer to psql's input and output
+        stream. On a backend copy stdin comes from
+        wherever the COPY itself came from (for
+        example, a script run with the -f option), and
+        stdout refers to the query output stream (see
+        \o meta-command below).
         
+        
         
       
 
-
       
-        \g [ { filename | |command } ]
-
+        \copyright
         
         
-        Sends the current query input buffer to the backend and
-        optionally saves the output in 
-        class="parameter">filename or pipes the output
-        into a separate Unix shell to execute 
-        class="parameter">command. A bare
-        \g is virtually equivalent to a semicolon. A
-        \g with argument is a one-shot
-        alternative to the \o command.
+        Shows the copyright and distribution terms of
+        PostgreSQL.
         
         
       
 
       
-        \help (or \h) [ command ]
+        \d relation 
+
         
         
-        Give syntax help on the specified SQL
-        command. If command
-        is not specified, then psql will list
-        all the commands for which syntax help is available. If
-        command is an
-        asterisk (*), then syntax help on all
-        SQL commands is shown.
-        
+   Shows all columns of 
+   class="parameter">relation (which could be a
+   table, view, index, or sequence), their types, and any special
+   attributes such as NOT NULL 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.
+   
+
+   
+   The command form \d+ is identical, but any
+   comments associated with the table columns are shown as well.
+   
 
    
    
-   To simplify typing, commands that consists of several words do
-   not have to be quoted. Thus it is fine to type \help
-   alter table.
+   If \d is called without any arguments, it is
+   equivalent to \dtvs which will show a list of
+   all tables, views, and sequences. This is purely a convenience
+   measure.
    
-    
-        
+   
+   
       
 
-
       
-        \H
+        \da [ pattern ]
+
         
         
-   Turns on HTML query output format. If the
-   HTML format is already on, it is switched
-   back to the default aligned text format. This command is for
-   compatibility and convenience, but see \pset
-   about setting other output options.
+        Lists all available aggregate functions, together with the data
+        type they operate on. If 
+        class="parameter">pattern (a regular expression)
+        is specified, only matching aggregates are shown.
         
         
       
 
-
       
-        \i filename
+        \dd [ object ]
         
         
-        Reads input from the file 
-        class="parameter">filename and executes it as
-        though it had been typed on the keyboard.
+        Shows the descriptions of 
+        class="parameter">object (which can be a regular
+        expression), or of all objects if no argument is given.
+        (Object covers aggregates, functions, operators,
+        types, relations (tables, views, indexes, sequences, large
+        objects), rules, and triggers.) For example:
+
+=> \dd version
+              Object descriptions
+  Name   |   What   |        Description
+---------+----------+---------------------------
+ version | function | PostgreSQL version string
+(1 row)
+
         
-   
-   
-   If you want to see the lines on the screen as they are read you
-   must set the variable ECHO to
-   all.
+
+        
+        Descriptions for objects can be generated with the
+        COMMENT ON SQL command.
    
-   
+
+        
+        
+        PostgreSQL stores the object
+        descriptions in the pg_description system table.
+        
+        
+
         
       
 
 
       
-        \l (or \list)
+        \dD [ pattern ]
         
         
-        List all the databases in the server as well as their owners.
-        Append a + to the command name to see any
-        descriptions for the databases as well. If your
-        PostgreSQL installation was compiled
-        with multibyte encoding support, the encoding scheme of each
-        database is shown as well.
+        Lists all available domains (derived types). If 
+        class="parameter">pattern (a regular expression)
+        is specified, only matching domains are shown.
         
         
       
 
 
       
-        \lo_export loid filename>
+        \df [ pattern ]>
 
-   
-   
-   Reads the large object with OID 
-   class="parameter">loid from the database and
-   writes it to 
-   class="parameter">filename. Note that this is
-   subtly different from the server function
-   lo_export, which acts with the permissions
-   of the user that the database server runs as and on the server's
-   file system.
-   
-   
-   
-   Use \lo_list to find out the large object's
-   OID.
-   
-   
-   
-   
-   See the description of the LO_TRANSACTION
-   variable for important information concerning all large object
-   operations.
-   
-   
-   
+        
+        
+        Lists available functions, together with their argument and
+        return types. If 
+        class="parameter">pattern (a regular expression)
+        is specified, only matching functions are shown. If the form
+        \df+ is used, additional information about
+        each function, including language and description, is shown.
+        
+        
       
 
 
       
-        \lo_import filename [ comment ]
-
-   
-   
-   Stores the file into a PostgreSQL
-   large object. Optionally, it associates the given
-   comment with the object. Example:
-
-foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
-lo_import 152801
-
-   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 \lo_list command.
-   
+        \distvS [ pattern ]
 
+   
    
-   Note that this command is subtly different from the server-side
-   lo_import 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.
    
 
-   
    
-   See the description of the LO_TRANSACTION
-   variable for important information concerning all large object
-   operations.
+   If pattern is
+   specified, it is a regular expression that restricts the listing
+   to those objects whose name matches. If one appends a
+   + to the command name, each object is listed with
+   its associated description, if any.
    
-   
    
       
 
+
       
-        \lo_list
+        \dl
    
    
-   Shows a list of all PostgreSQL
-   large objects currently stored in the database,
-   along with any comments provided for them.
+   This is an alias for \lo_list, which shows a
+   list of large objects.
    
    
       
 
+
       
-        \lo_unlink loid
+        \do [ name ]
+        
+        
+        Lists available operators with their operand and return types.
+        If name is
+        specified, only operators with that name will be shown.
+        
+        
+      
 
-   
-   
-   Deletes the large object with OID
-   loid from the
-   database.
-   
 
-   
-   
-   Use \lo_list to find out the large object's
-   OID.
-   
-   
-   
+      
+        \dp [ pattern ]
+   
    
-   See the description of the LO_TRANSACTION
-   variable for important information concerning all large object
-   operations.
+   This is an alias for \z which was included
+   for its greater mnemonic value (display
+   permissions).
    
-   
    
       
 
 
       
-        \o [ {filename | |command} ]
-
+        \dT [ pattern ]
         
         
-        Saves future query results to the file 
-        class="parameter">filename or pipes future results
-        into a separate Unix shell to execute 
-        class="parameter">command. If no arguments are
-        specified, the query output will be reset to
-        stdout.
+        Lists all data types or only those that match 
+        class="parameter">pattern. The command form
+        \dT+ shows extra information.
         
-
-   
-   Query results 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 \d), but not error
-   messages.
-   
-
-   
-   
-   To intersperse text output in between query results, use
-   \qecho.
-   
-   
         
       
 
 
       
-        \p
+        \du [ pattern ]
         
         
-        Print the current query buffer to the standard output.
+        Lists all configured users or only those that match 
+        class="parameter">pattern.
         
         
       
 
 
       
-        \pset parameter [ value ]
-
-   
-   
-   This command sets options affecting the output of query result
-   tables. parameter
-   describes which option is to be set. The semantics of
-   value depend
-   thereon.
-   
-
-   
-   Adjustable printing options are:
-   
-     
-     format
-     
-     
-     Sets the output format to one of unaligned,
-     aligned, html, or
-     latex. Unique abbreviations are allowed.
-     (That would mean one letter is enough.)
-     
-
-     
-     Unaligned 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).
-     Aligned mode is the standard, human-readable,
-     nicely formatted text output that is default. The
-     HTML and
-     LaTeX 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 HTML, but in LaTeX you must
-     have a complete document wrapper.)
-     
-     
-          
-
-     
-     border
-     
-     
-     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
-     HTML mode, this will translate directly
-     into the border=... attribute, in the
-     others only values 0 (no border), 1 (internal dividing lines),
-     and 2 (table frame) make sense.
-     
-     
-     
-
-     
-     expanded (or x)
-     
-     
-     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
-     horizontal mode.
-     
-
-     
-     Expanded mode is supported by all four output modes.
-     
-     
-     
-
-     
-     null
-     
-     
-     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 \pset null
-     '(null)'.
-     
-     
-     
-
-     
-     fieldsep
-     
-     
-     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 \pset fieldsep
-     '\t'. The default field separator is
-     '|' (a pipe symbol).
-     
-     
-     
-
-     
-     footer
-     
-     
-     Toggles the display of the default footer (x
-     rows).
-     
-     
-     
-
-     
-     recordsep
-     
-     
-          Specifies the record (line) separator to use in unaligned
-          output mode. The default is a newline character.
-     
-     
-     
-
-     
-     tuples_only (or t)
-     
-     
-     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.
-     
-     
-     
-
-     
-     title [ text ]
-     
-     
-     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.
-     
-
-     
-     
-     This formerly only affected HTML mode. You
-     can now set titles in any output format.
-     
-     
-     
-     
-
-     
-     tableattr (or T) [ text ]
-     
-     
-     Allows you to specify any attributes to be placed inside the
-     HTML table tag. This
-     could for example be cellpadding or
-     bgcolor. Note that you probably don't want
-     to specify border here, as that is already
-     taken care of by \pset border.
-     
-     
-     
+        \edit (or \e) [ filename ]
 
+        
+        
+        If filename 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.
+        
 
-     >
-     pager
-     
-     
-     Toggles the use of a pager for query and psql help output. If the
-     environment variable PAGER is set, the output
-     is piped to the specified program. Otherwise
-     more is used.
-     
+        >
+        The new query buffer is then re-parsed according to the normal
+        rules of psql, where the whole buffer
+        is treated as a single line. (Thus you cannot make scripts this
+        way. Use \i 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.
+        
 
-     
-     In any case, psql 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 psql might not appear very
-     discriminating about when to use the pager.
-     
-     
-     
-   
-   Illustrations on how these different formats look can be seen in
-   the 
-   endterm="APP-PSQL-examples-title"> section.
+        
+        
+        psql searches the environment
+        variables PSQL_EDITOR, EDITOR, and
+        VISUAL (in that order) for an editor to use. If
+        all of them are unset, /bin/vi is run.
+        
+        
+        
+      
+
+
+      
+        \echo text [ ... ]
+        
+   
+        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:
+
+=> \echo `date`
+Tue Oct 26 21:40:57 CEST 1999
+
+        If the first argument is an unquoted -n the the trailing
+        newline is not written.
    
 
    
    
-   There are various shortcut commands for \pset. See
-   \a, \C, \H,
-   \t, \T, and \x.
+   If you use the \o command to redirect your
+   query output you may wish to use \qecho
+   instead of this command.
    
    
+   
+      
 
-   
-   
-   It is an error to call \pset without
-   arguments. In the future this call might show the current status
-   of all printing options.
-   
-   
 
-   
+      
+        \encoding [ encoding ]
+
+        
+        
+        Sets the client encoding, if you are using multibyte encodings.
+        Without an argument, this command shows the current encoding.
+        
+        
       
 
 
       
-        \q
+        \f [ string ]
+
         
         
-        Quit the psql program.
+        Sets the field separator for unaligned query output. The default
+        is pipe (|). See also
+        \pset for a generic way of setting output
+        options.
         
         
       
 
 
       
-        \qecho text [ ... ] 
+        \g [ { filename | |command } ]
+
         
         
-   This command is identical to \echo except
-   that all output will be written to the query output channel, as
-   set by \o.
+        Sends the current query input buffer to the backend and
+        optionally saves the output in 
+        class="parameter">filename or pipes the output
+        into a separate Unix shell to execute 
+        class="parameter">command. A bare
+        \g is virtually equivalent to a semicolon. A
+        \g with argument is a one-shot
+        alternative to the \o command.
+        
+        
+      
+
+      
+        \help (or \h) [ command ]
+        
+        
+        Give syntax help on the specified SQL
+        command. If command
+        is not specified, then psql will list
+        all the commands for which syntax help is available. If
+        command is an
+        asterisk (*), then syntax help on all
+        SQL commands is shown.
         
+
+   
+   
+   To simplify typing, commands that consists of several words do
+   not have to be quoted. Thus it is fine to type \help
+   alter table.
+   
+    
         
       
 
 
       
-        \r
+        \H
         
         
-        Resets (clears) the query buffer.
+   Turns on HTML query output format. If the
+   HTML format is already on, it is switched
+   back to the default aligned text format. This command is for
+   compatibility and convenience, but see \pset
+   about setting other output options.
         
         
       
 
 
       
-        \s [ filename ]
+        \i filename
         
         
-        Print or save the command line history to 
-        class="parameter">filename. If 
-        class="parameter">filename is omitted, the history
-        is written to the standard output. This option is only available
-        if psql is configured to use the
-        GNU history library.
+        Reads input from the file 
+        class="parameter">filename and executes it as
+        though it had been typed on the keyboard.
+        
+   
+   
+   If you want to see the lines on the screen as they are read you
+   must set the variable ECHO to
+   all.
+   
+   
+        
+      
+
+
+      
+        \l (or \list)
+        
+        
+        List all the databases in the server as well as their owners.
+        Append a + to the command name to see any
+        descriptions for the databases as well. If your
+        PostgreSQL installation was compiled
+        with multibyte encoding support, the encoding scheme of each
+        database is shown as well.
         
+        
+      
+
+
+      
+        \lo_export loid filename
+
+   
+   
+   Reads the large object with OID 
+   class="parameter">loid from the database and
+   writes it to 
+   class="parameter">filename. Note that this is
+   subtly different from the server function
+   lo_export, which acts with the permissions
+   of the user that the database server runs as and on the server's
+   file system.
+   
+   
+   
+   Use \lo_list to find out the large object's
+   OID.
+   
+   
+   
+   
+   See the description of the LO_TRANSACTION
+   variable for important information concerning all large object
+   operations.
+   
+   
+   
+      
+
+
+      
+        \lo_import filename [ comment ]
+
+   
+   
+   Stores the file into a PostgreSQL
+   large object. Optionally, it associates the given
+   comment with the object. Example:
+
+foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
+lo_import 152801
+
+   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 \lo_list command.
+   
+
+   
+   Note that this command is subtly different from the server-side
+   lo_import because it acts as the local user
+   on the local file system, rather than the server's user and file
+   system.
+   
 
    
    
-   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 psql starts up.
+   See the description of the LO_TRANSACTION
+   variable for important information concerning all large object
+   operations.
+   
+   
+   
+      
+
+      
+        \lo_list
+   
+   
+   Shows a list of all PostgreSQL
+   large objects currently stored in the database,
+   along with any comments provided for them.
    
-   
-        
+   
       
 
-
       
-        \set [ name [ value [ ... ]]]
+        \lo_unlink loid
 
    
    
-   Sets the internal variable 
-   class="parameter">name to 
-   class="parameter">value 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 \unset command.
-   
-
-   
-   Valid variable names can contain characters, digits, and
-   underscores. See the section about
-   psql variables for details.
+   Deletes the large object with OID
+   loid from the
+   database.
    
 
+   
    
-   Although you are welcome to set any variable to anything you
-   want, psql treats several variables
-   as special. They are documented in the section about variables.
+   Use \lo_list to find out the large object's
+   OID.
    
-
+   
    
    
-   This command is totally separate from the SQL
-   command .
+   See the description of the LO_TRANSACTION
+   variable for important information concerning all large object
+   operations.
    
    
    
@@ -1172,582 +1200,500 @@ lo_import 152801
 
 
       
-        \t
-        
-        
-        Toggles the display of output column name headings and row count
-        footer. This command is equivalent to \pset
-        tuples_only and is provided for convenience.
-        
-        
-      
-
+        \o [ {filename | |command} ]
 
-      
-        \T table_options
         
         
-        Allows you to specify options to be placed within the
-        table tag in HTML tabular
-        output mode. This command is equivalent to \pset
-        tableattr 
-        class="parameter">table_options.
+        Saves future query results to the file 
+        class="parameter">filename or pipes future results
+        into a separate Unix shell to execute 
+        class="parameter">command. If no arguments are
+        specified, the query output will be reset to
+        stdout.
         
-        
-      
 
+   
+   Query results 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 \d), but not error
+   messages.
+   
 
-      >
-       \timing>
-        
-        
-         Toggles a display of how long each query takes in seconds.
-        >
-       
+   >
+   >
+   To intersperse text output in between query results, use
+   \qecho.
+   
+   >
+        
       
 
 
       
-        \w {filename | |command}
+        \p
         
         
-        Outputs the current query buffer to the file 
-        class="parameter">filename or pipes it to the Unix
-        command command.
+        Print the current query buffer to the standard output.
         
         
       
 
 
       
-        \x
-        
-        
-        Toggles extended row format mode. As such it is equivalent to
-   \pset expanded.
-       
-       
-      
-
-
-      
-        \z [ pattern ]
-        
-        
-        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.
-        
+        \pset parameter [ value ]
 
+   
    
-
-test=> \z
-Access permissions for database "test"
- Relation |           Access permissions
-----------+-------------------------------------
- my_table | {"=r","joe=arwR", "group staff=ar"}
-(1 row )
-
-        Read this as follows:
-
-   
-          
-          
-          "=r": PUBLIC has read
-          (SELECT) permission on the table.
-     
-     
+   This command sets options affecting the output of query result
+   tables. parameter
+   describes which option is to be set. The semantics of
+   value depend
+   thereon.
+   
 
+   
+   Adjustable printing options are:
+   
+     
+     format
      
      
-     "joe=arwR": User joe has
-     read, write (UPDATE,
-     DELETE), append
-     (INSERT) permissions, and permission to
-     create rules on the table.
+     Sets the output format to one of unaligned,
+     aligned, html, or
+     latex. Unique abbreviations are allowed.
+     (That would mean one letter is enough.)
      
-     
 
-     
      
-     "group staff=ar": Group
-     staff has SELECT and
-     INSERT permission.
+     Unaligned 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).
+     Aligned mode is the standard, human-readable,
+     nicely formatted text output that is default. The
+     HTML and
+     LaTeX 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 HTML, but in LaTeX you must
+     have a complete document wrapper.)
      
-     
-   
-   
-
-   
-   The commands  and
-   
-   are used to set access permissions.
-   
-
-        
-      
-
-
-      
-        \! [ command ]
-        
-        
-        Escapes to a separate Unix shell or executes the Unix command
-        command. The
-        arguments are not further interpreted, the shell will see them
-        as is.
-        
-        
-      
-
-
-      
-        \?
-        
-        
-        Get help information about the backslash (\)
-        commands.
-        
-        
-      
-
-    
-  
-
-
-
-
-
-  
-    1998-09-26
-  
-
-  Command-line Options
-
-  
-  If so configured, psql understands both
-  standard Unix short options, and GNU-style long
-  options. The latter are not available on all systems.
-  
-
-  
-  
-    
-      -a, --echo-all
-      
-      
-      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 ECHO to
-      all.
-      
-      
-    
-
-
-    
-      -A, --no-align
-      
-      
-      Switches to unaligned output mode. (The default output mode is
-      otherwise aligned.)
-      
-      
-    
-
-   
-    
-      -c, --command query
-      
-      
-      Specifies that psql is to execute one
-      query string, query,
-      and then exit. This is useful in shell scripts.
-      
-      
-      query must be either
-      a query string that is completely parseable by the backend (i.e.,
-      it contains no psql specific features),
-      or it is a single backslash command. Thus you cannot mix
-      SQL and psql
-      meta-commands. To achieve that, you could pipe the string into
-      psql, like this: echo "\x \\
-      select * from foo;" | psql.
-      
-      
-    
-
+     
+          
 
-    
-      -d, --dbname dbname
-      
-      
-      Specifies the name of the database to connect to. This is
-      equivalent to specifying 
-      class="parameter">dbname as the first non-option
-      argument on the command line.
-      
-      
-    
+     
+     border
+     
+     
+     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
+     HTML mode, this will translate directly
+     into the border=... attribute, in the
+     others only values 0 (no border), 1 (internal dividing lines),
+     and 2 (table frame) make sense.
+     
+     
+     
 
+     
+     expanded (or x)
+     
+     
+     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
+     horizontal mode.
+     
 
-    
-      -e, --echo-queries
-      
-      
-      Show all queries that are sent to the backend. This is equivalent
-      to setting the variable ECHO to
-      queries.
-      
-      
-    
+     
+     Expanded mode is supported by all four output modes.
+     
+     
+     
 
+     
+     null
+     
+     
+     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 \pset null
+     '(null)'.
+     
+     
+     
 
-    
-      -E, --echo-hidden
-      
-      
-      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 ECHO_HIDDEN from within
-      psql.
-      
-      
-    
+     
+     fieldsep
+     
+     
+     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 \pset fieldsep
+     '\t'. The default field separator is
+     '|' (a pipe symbol).
+     
+     
+     
 
+     
+     footer
+     
+     
+     Toggles the display of the default footer (x
+     rows).
+     
+     
+     
 
-    
-      -f, --file filename
-      
-      
-      Use the file filename
-      as the source of queries instead of reading queries interactively.
-      After the file is processed, psql
-      terminates. This is in many ways equivalent to the internal
-      command \i.
-      
+     
+     recordsep
+     
+     
+          Specifies the record (line) separator to use in unaligned
+          output mode. The default is a newline character.
+     
+     
+     
 
-      
-       If filename is -
-       (hyphen), then standard input is read.
-      
+     
+     tuples_only (or t)
+     
+     
+     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.
+     
+     
+     
 
-      
-      Using this option is subtly different from writing psql
-      < 
-      class="parameter">filename. In general,
-      both will do what you expect, but using -f
-      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.
-      
-      
-    
+     
+     title [ text ]
+     
+     
+     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.
+     
 
+     
+     
+     This formerly only affected HTML mode. You
+     can now set titles in any output format.
+     
+     
+     
+     
 
-    
-      -F, --field-separator separator
-      
-      
-      Use separator as the
-      field separator. This is equivalent to \pset
-      fieldsep or \f.
-      
-      
-    
+     
+     tableattr (or T) [ text ]
+     
+     
+     Allows you to specify any attributes to be placed inside the
+     HTML table tag. This
+     could for example be cellpadding or
+     bgcolor. Note that you probably don't want
+     to specify border here, as that is already
+     taken care of by \pset border.
+     
+     
+     
 
 
-    
-      -h, --host hostname
-      
-      
-      Specifies the host name of the machine on which the
-      postmaster is running. If host begins
-      with a slash, it is used as the directory for the unix domain
-      socket.
-      
-      
-    
+     
+     pager
+     
+     
+     Toggles the use of a pager for query and psql help output. If the
+     environment variable PAGER is set, the output
+     is piped to the specified program. Otherwise a platform-dependent default (such as
+     more) is used.
+     
 
+     
+     In any case, psql 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 psql might not appear very
+     discriminating about when to use the pager.
+     
+     
+     
+   
+   Illustrations on how these different formats look can be seen in
+   the 
+   endterm="APP-PSQL-examples-title"> section.
+   
 
-    
-      -H, --html
-      
-      
-      Turns on HTML tabular output. This is
-      equivalent to \pset format html or the
-      \H command.
-      
-      
-    
+   
+   
+   There are various shortcut commands for \pset. See
+   \a, \C, \H,
+   \t, \T, and \x.
+   
+   
 
- 
-    
-      -l, --list
-      
-      
-      Lists all available databases, then exits. Other non-connection
-      options are ignored. This is similar to the internal command
-      \list.
-      
-      
-    
+   
+   
+   It is an error to call \pset without
+   arguments. In the future this call might show the current status
+   of all printing options.
+   
+   
 
+   
+      
 
-    
-      -o, --output filename
-      
-      
-      Put all query output into file 
-      class="parameter">filename. This is equivalent to
-      the command \o.
-      
-      
-    
 
+      
+        \q
+        
+        
+        Quit the psql program.
+        
+        
+      
 
-    
-      -p, --port port
-      
-      
-      Specifies the TCP/IP port or, by omission, the local Unix domain
-      socket file extension on which the
-      postmaster is listening for
-      connections. Defaults to the value of the PGPORT
-      environment variable or, if not set, to the port specified at
-      compile time, usually 5432.
-      
-      
-    
 
+      
+        \qecho text [ ... ] 
+        
+        
+   This command is identical to \echo except
+   that all output will be written to the query output channel, as
+   set by \o.
+        
+        
+      
 
-    
-      -P, --pset assignment
-      
-      
-      Allows you to specify printing options in the style of
-      \pset 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
-      -P format=latex.
-      
-      
-    
 
+      
+        \r
+        
+        
+        Resets (clears) the query buffer.
+        
+        
+      
 
-    
-      -q
-      
-      
-      Specifies that psql 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 -c option.
-      Within psql you can also set the
-      QUIET variable to achieve the same effect.
-      
-      
-    
 
+      
+        \s [ filename ]
+        
+        
+        Print or save the command line history to 
+        class="parameter">filename. If 
+        class="parameter">filename is omitted, the history
+        is written to the standard output. This option is only available
+        if psql is configured to use the
+        GNU history library.
+        
 
-    >
-      -R, --record-separator separator>
-      
-      
-      Use separator as the
-      record separator. This is equivalent to the \pset
-      recordsep command.
-      >
-      
-    
+   >
+   >
+   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 psql starts up.
+   
+   >
+        
+      
 
- 
-    
-      -s, --single-step
-      
-      
-      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.
-      
-      
-    
 
+      
+        \set [ name [ value [ ... ]]]
 
-    
-      -S, --single-line
-      
-      
-      Runs in single-line mode where a newline terminates a query, as a
-      semicolon does.
-      
+   
+   
+   Sets the internal variable 
+   class="parameter">name to 
+   class="parameter">value 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 \unset command.
+   
 
-      
-      
-      This mode is provided for those who insist on it, but you are not
-      necessarily encouraged to use it. In particular, if you mix
-      SQL and meta-commands on a line the order of
-      execution might not always be clear to the inexperienced user.
-      
-      
-      
-    
+   
+   Valid variable names can contain characters, digits, and
+   underscores. See the section about
+   psql variables for details.
+   
 
+   
+   Although you are welcome to set any variable to anything you
+   want, psql treats several variables
+   as special. They are documented in the section about variables.
+   
 
-    
-      -t, --tuples-only
-      
-      
-      Turn off printing of column names and result row count footers,
-      etc. It is completely equivalent to the \t
-      meta-command.
-      
-      
-    
+   
+   
+   This command is totally separate from the SQL
+   command .
+   
+   
+   
+      
 
 
-    
-      -T, --table-attr table_options>
-      
-      
-      Allows you to specify options to be placed within the
-      HTML table tag. See
-      \pset for details.
-      
-      
-    
+      
+        \t>
+        
+        
+        Toggles the display of output column name headings and row count
+        footer. This command is equivalent to \pset
+        tuples_only and is provided for convenience.
+        
+        
+      
 
- 
-    
-      -u
-      
-      
-      Makes psql prompt for the user name and
-      password before connecting to the database.
-      
 
-      
-      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 -U and
-      -W options instead.
-      
-      
-    
+      
+        \T table_options
+        
+        
+        Allows you to specify options to be placed within the
+        table tag in HTML tabular
+        output mode. This command is equivalent to \pset
+        tableattr 
+        class="parameter">table_options.
+        
+        
+      
 
 
-    
-      -U, --username username
-      
-      
-      Connects to the database as the user 
-      class="parameter">username instead of the default.
-      (You must have permission to do so, of course.)
-       
-      
-    
+      
+       \timing
+        
+        
+         Toggles a display of how long each query takes in seconds.
+        
+       
+      
 
 
-    
-      -v, --variable, --set assignment
-      
-      
-      Performs a variable assignment, like the \set
-      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.
-      
-      
-    
+      
+        \w {filename | |command}
+        
+        
+        Outputs the current query buffer to the file 
+        class="parameter">filename or pipes it to the Unix
+        command command.
+        
+        
+      
 
 
-    
-      -V, --version
-      
-      
-      Shows the psql version.
-      
-      
-    
+      
+        \x
+        
+        
+        Toggles extended row format mode. As such it is equivalent to
+   \pset expanded.
+       
+       
+      
 
 
-    
-      -W, --password
-      
-      
-      Requests that psql 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 \connect.
-      
+      
+        \z [ pattern ]
+        
+        
+        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.
+        
 
-      
-      In the current version, psql
-      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.
-      
-      
-    
+   
+
+test=> \z
+Access permissions for database "test"
+ Relation |           Access permissions
+----------+-------------------------------------
+ my_table | {"=r","joe=arwR", "group staff=ar"}
+(1 row )
+
+        Read this as follows:
 
+   
+          
+          
+          "=r": PUBLIC has read
+          (SELECT) permission on the table.
+     
+     
 
-    >
-      -x, --expanded>
-      
-      
-      Turns on extended row format mode. This is equivalent to the
-      command \x.
-      
-      >
-    >
+     >
+     >
+     "joe=arwR": User joe has
+     read, write (UPDATE,
+     DELETE), append
+     (INSERT) permissions, and permission to
+     create rules on the table.
+     >
+     >
 
+     
+     
+     "group staff=ar": Group
+     staff has SELECT and
+     INSERT permission.
+     
+     
+   
+   
 
-    
-      -X, --no-psqlrc
-      
-      
-      Do not read the start-up file ~/.psqlrc.
-      
-      
-    
+   
+   The commands  and
+   
+   are used to set access permissions.
+   
 
+        
+      
 
-    
-      -?, --help
-      
-      
-      Shows help about psql command line
-      arguments.
-      
-      
-    
 
-  
-  
+      
+        \! [ command ]
+        
+        
+        Escapes to a separate Unix shell or executes the Unix command
+        command. The
+        arguments are not further interpreted, the shell will see them
+        as is.
+        
+        
+      
 
-
 
+      
+        \?
+        
+        
+        Get help information about the backslash (\)
+        commands.
+        
+        
+      
 
-
-    
-      1998-09-27
-    
+    
+  
+ 
 
-    Advanced features
+ 
+  Advanced features
 
-   id="APP-PSQL-variables">
+    id="APP-PSQL-variables">
     Variables
 
     
@@ -2063,11 +2009,10 @@ bar
 
     
 
-  
-
+   
 
-  >
-     id="APP-PSQL-sql-interpol-title">SQL Interpolation
+   >
+    <acronym>SQL</acronym> Interpolation
 
     
     An additional useful feature of psql
@@ -2131,10 +2076,9 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     conflict.)
     
 
-  
-
+   
 
-   id="APP-PSQL-prompting">
+    id="APP-PSQL-prompting">
     Prompting
 
     
@@ -2282,31 +2226,10 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     
     
 
-   
-
-  
-    Miscellaneous
-
-    
-    psql 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 ON_ERROR_STOP was set.
-    
-
-    
-    Before starting up, psql attempts to read
-    and execute commands from the file
-    $HOME/.psqlrc. It could be used to set up the
-    client or the server to taste (using the \set 
-    and SET commands).
-    
-
-  
+   
 
-  >
-    <span class="marked"><acronym>GNU</acronym> r</span>eadline
+   >
+    <span class="marked">R</span>eadline
 
     
     psql supports the readline and history
@@ -2356,14 +2279,167 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
     GNU project's FTP server at
     ftp://ftp.gnu.org.
     
+   
   
+ 
+
+
+ 
+  Environment
+
+  
+   
+    HOME
+
+    
+     
+      Directory for initialization file (.psqlrc)
+      and command history file (.psql_history).
+     
+    
+   
+
+   
+    PAGER
+
+    
+     
+      If the query results do not fit on the screen, they are piped
+      through this command.  Typical values are
+      more or less.  The default
+      is platform-dependent.  The use of the pager can be disabled by
+      using the \pset command.
+     
+    
+   
+
+   
+    PGDATABASE
+
+    
+     
+      Default database to connect to
+     
+    
+   
+
+   
+    PGHOST
+    PGPORT
+    PGUSER
+
+    
+     
+      Default connection parameters
+     
+    
+   
+
+   
+    PSQL_EDITOR
+    EDITOR
+    VISUAL
+
+    
+     
+      Editor used by the \e command.  The variables
+      are examined in the order listed; the first that is set is used.
+     
+    
+   
+
+   
+    SHELL
+
+    
+     
+      Command executed by the \! command.
+     
+    
+   
+
+   
+    TMPDIR
+
+    
+     
+      Directory for storing temporary files.  The default is
+      /tmp.
+     
+    
+   
+  
+ 
+
+
+ 
+  Files
+
+  
+   
+    
+     Before starting up, psql attempts to
+     read and execute commands from the file
+     $HOME/.psqlrc. It could be used to set up
+     the client or the server to taste (using the \set
+      and SET commands).
+    
+   
+
+   
+    
+     The command-line history is stored in the file
+     $HOME/.psql_history.
+    
+   
+  
+ 
+
+
+ 
+  Notes
+
+    
+      
+      
+      In some earlier life psql 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
+
+testdb=> \foo
+Field separator is "oo",
+
+      which is perhaps not what one would expect.
+      
+      
 
+      
+      
+      psql 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.
+      
+      
 
+      
+      
+      Pressing Control-C during a copy in (data sent to
+      the server) doesn't show the most ideal of behaviors. If you get a
+      message such as COPY state must be terminated
+      first, simply reset the connection by entering \c
+      - -.
+      
+      
 
-
+    
+ 
 
 
-
+ 
   Examples
 
   
@@ -2478,60 +2554,7 @@ second | four
 
   
 
-
-
-
-
-  
-    1999-10-27
-  
-
-  Appendix
-
-  
-    Bugs and Issues
-
-    
-      
-      
-      In some earlier life psql 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
-
-testdb=> \foo
-Field separator is "oo",
-
-      which is perhaps not what one would expect.
-      
-      
-
-      
-      
-      psql 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.
-      
-      
-
-      
-      
-      Pressing Control-C during a copy in (data sent to
-      the server) doesn't show the most ideal of behaviors. If you get a
-      message such as COPY state must be terminated
-      first, simply reset the connection by entering \c
-      - -.
-      
-      
-
-    
-
-  
-
-
+ 
 
 
 


diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml

index b1c3cab01a8383b3b74aa84c478c32f8a6a38681..37debc1b84597b80b1ed0f4bb2f754aa58a89584 100644 (file)

--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,13 +1,9 @@
 
 
 
- 
-  2000-11-11
- 
-
  
   vacuumdb
   1
@@ -38,11 +34,37 @@ PostgreSQL documentation
    --verbose-v
    --analyze-z
   
+ 
+ 
+
+ 
+  Description
+
+  
+   vacuumdb is a utility for cleaning a
+   PostgreSQL database.
+   vacuumdb will also generate internal statistics
+   used by the PostgreSQL query optimizer.
+  
+
+  
+   vacuumdb is a shell script wrapper around the
+   backend command
+    via
+   the PostgreSQL interactive terminal
+   . There is no effective
+   difference between vacuuming databases via this or other methods.
+   psql 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 psql
+   and the libpq front-end library do apply.
+  
+ 
+
+
+ 
+  Options
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
    
     vacuumdb accepts the following command line arguments:
     
@@ -190,12 +212,12 @@ PostgreSQL documentation
      
     
    
-  
+ 
+
+
+ 
+  Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
    
     
      
@@ -221,42 +243,30 @@ PostgreSQL documentation
 
     
    
+ 
 
-   
-   
 
-  
- 
- 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
+ 
+  Environment
 
-  
-   vacuumdb is a utility for cleaning a
-   PostgreSQL database.
-   vacuumdb will also generate internal statistics
-   used by the PostgreSQL query optimizer.
-  
-
-  
-   vacuumdb is a shell script wrapper around the
-   backend command
-    via
-   the PostgreSQL interactive terminal
-   . There is no effective
-   difference between vacuuming databases via this or other methods.
-   psql 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 psql
-   and the libpq front-end library do apply.
-  
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
 
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
  
 
- 
-  Usage
+
+ 
+  Examples
 
   
    
@@ -290,6 +300,15 @@ PostgreSQL documentation
   
 
  
+
+ 
+  See Also
+
+  
+   
+  
+ 
+
 
 
 

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index b1c3cab01a8383b3b74aa84c478c32f8a6a38681..37debc1b84597b80b1ed0f4bb2f754aa58a89584 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,13 +1,9 @@
 
 
 
- 
-  2000-11-11
- 
-
  
   vacuumdb
   1
@@ -38,11 +34,37 @@ PostgreSQL documentation
    --verbose-v
    --analyze-z
   
+ 
+ 
+
+ 
+  Description
+
+  
+   vacuumdb is a utility for cleaning a
+   PostgreSQL database.
+   vacuumdb will also generate internal statistics
+   used by the PostgreSQL query optimizer.
+  
+
+  
+   vacuumdb is a shell script wrapper around the
+   backend command
+    via
+   the PostgreSQL interactive terminal
+   . There is no effective
+   difference between vacuuming databases via this or other methods.
+   psql 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 psql
+   and the libpq front-end library do apply.
+  
+ 
+
+
+ 
+  Options
 
-  
-   </div>
<div class="diff rem">-    Inputs</div>
<div class="diff rem">-   
    
     vacuumdb accepts the following command line arguments:
     
@@ -190,12 +212,12 @@ PostgreSQL documentation
      
     
    
-  
+ 
+
+
+ 
+  Diagnostics
 
-  
-   </div>
<div class="diff rem">-    Outputs</div>
<div class="diff rem">-   
    
     
      
@@ -221,42 +243,30 @@ PostgreSQL documentation
 
     
    
+ 
 
-   
-   
 
-  
- 
- 
- 
-  </div>
<div class="diff rem">-   Description</div>
<div class="diff rem">-  
+ 
+  Environment
 
-  
-   vacuumdb is a utility for cleaning a
-   PostgreSQL database.
-   vacuumdb will also generate internal statistics
-   used by the PostgreSQL query optimizer.
-  
-
-  
-   vacuumdb is a shell script wrapper around the
-   backend command
-    via
-   the PostgreSQL interactive terminal
-   . There is no effective
-   difference between vacuuming databases via this or other methods.
-   psql 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 psql
-   and the libpq front-end library do apply.
-  
+  
+   
+    PGHOST
+    PGPORT
+    PGUSER
 
+    
+     
+      Default connection parameters.
+     
+    
+   
+  
  
 
- 
-  Usage
+
+ 
+  Examples
 
   
    
@@ -290,6 +300,15 @@ PostgreSQL documentation
   
 
  
+
+ 
+  See Also
+
+  
+   
+  
+ 
+