From 06ad580f75dd54db254d9b1a9665975b9a47570c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 28 Jul 2002 15:22:21 +0000 Subject: [PATCH] Structure reference pages consistently. Document that structure. Add information about environment variables. --- doc/src/sgml/docguide.sgml | 192 +- doc/src/sgml/ref/createdb.sgml | 115 +- doc/src/sgml/ref/createlang.sgml | 109 +- doc/src/sgml/ref/createuser.sgml | 129 +- doc/src/sgml/ref/dropdb.sgml | 101 +- doc/src/sgml/ref/droplang.sgml | 109 +- doc/src/sgml/ref/dropuser.sgml | 113 +- doc/src/sgml/ref/ecpg-ref.sgml | 115 +- doc/src/sgml/ref/initlocation.sgml | 13 +- doc/src/sgml/ref/pg_ctl-ref.sgml | 49 +- doc/src/sgml/ref/pg_dump.sgml | 30 +- doc/src/sgml/ref/pg_dumpall.sgml | 22 +- doc/src/sgml/ref/pg_restore.sgml | 21 +- doc/src/sgml/ref/postgres-ref.sgml | 24 +- doc/src/sgml/ref/postmaster.sgml | 87 +- doc/src/sgml/ref/psql-ref.sgml | 2971 ++++++++++++++-------------- doc/src/sgml/ref/vacuumdb.sgml | 107 +- 17 files changed, 2449 insertions(+), 1858 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 7df4995cfb..10c0463844 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ - + 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 + - - - Inputs - - + + + + Description + + + 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 + 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 , , , , and are passed on literally to . @@ -160,13 +191,12 @@ PostgreSQL documentation endterm="SQL-CREATEDATABASE-title">; see there for more information about them. - + + + + + Diagnostics - - - Outputs - - 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. - - + - - - Description - - - 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 - 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. + + + + + - Usage + Examples @@ -262,6 +284,17 @@ PostgreSQL documentation + + + + See Also + + + + + + + @@ -11,7 +11,7 @@ PostgreSQL documentation - 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 - - - Inputs - createlang accepts the following command line arguments: @@ -138,12 +160,31 @@ PostgreSQL documentation - + + + + + Environment + + + + PGHOST + PGPORT + PGUSER + + + + Default connection parameters. + + + + + + + + + Diagnostics - - - Outputs - Most error messages are self-explanatory. If not, run createlang with the @@ -151,35 +192,12 @@ PostgreSQL documentation for details. Check also under for more possibilities. - - - - - - 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. - - - - 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 + + - - - Inputs - - + + 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 - - - Outputs - - 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. - - - - - - 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. - - - - Usage + + Examples @@ -274,6 +291,16 @@ PostgreSQL documentation + + + See Also + + + + + + + @@ -21,12 +21,36 @@ PostgreSQL documentation options dbname + - - - Inputs - - + + + 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 . - + - - - Outputs - - + + Diagnostics @@ -139,41 +161,35 @@ PostgreSQL documentation + If there is an error condition, the backend error message will be displayed. See and for possibilities. - - + - - - Description - - - 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 + + + + + - Usage + Examples @@ -201,6 +217,17 @@ DROP DATABASE + + + + See Also + + + + + + + @@ -11,7 +11,7 @@ PostgreSQL documentation - droplang + droplang remove a PostgreSQL procedural language @@ -27,11 +27,34 @@ PostgreSQL documentation --list-l dbname + + + + + Description + + + + 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 - - - Inputs - droplang accepts the following command line arguments: @@ -126,12 +149,31 @@ PostgreSQL documentation - + + + + + Environment + + + + PGHOST + PGPORT + PGUSER + + + + Default connection parameters. + + + + + + + + + Diagnostics - - - Outputs - Most error messages are self-explanatory. If not, run droplang with the @@ -139,43 +181,20 @@ PostgreSQL documentation for details. Check also under for more possibilities. - - - - - - Description - - - - 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. - - - - Notes - + + + Notes Use to add a language. - - Usage + + + Examples @@ -186,6 +205,16 @@ PostgreSQL documentation + + + See Also + + + + + + + @@ -21,12 +21,38 @@ PostgreSQL documentation options username + - - - Inputs - - + + + 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. - + - - - Outputs - - + + 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. - - - - - - 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. - - - - 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 (linus@epact.se) was the + original author of ecpg (up to version 0.2). + Michael Meskes (meskes@debian.org) + is the current author and maintainer of ecpg. + Thomas Good (tomg@q8.nrnet.org) + is the author of the last revision of the ecpg man page, on which + this document is based. + + + + + + Options - - - 1999-07-20 - - - Inputs - ecpg accepts the following command line arguments: @@ -104,58 +125,23 @@ PostgreSQL documentation - - - - - 1998-11-05 - - - Outputs - - - 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 (linus@epact.se) was the - original author of ecpg (up to version 0.2). - Michael Meskes (meskes@debian.org) - is the current author and maintainer of ecpg. - Thomas Good (tomg@q8.nrnet.org) - 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 - + Preprocessing for Compilation @@ -175,7 +161,7 @@ ecpg [ -d ] [ -o file ] file - + Compiling and Linking @@ -190,10 +176,10 @@ gcc -g -I /usr/local/pgsql/include [ -o file ] - + Grammar - + Libraries @@ -206,7 +192,7 @@ gcc -g -I /usr/local/pgsql/include [ -o file ] - + Variable Declaration @@ -237,7 +223,7 @@ char foo[16], bar[16]; - + Error Handling @@ -292,7 +278,7 @@ EXEC SQL WHENEVER not found sqlprint; - + Connecting to the Database Server @@ -322,7 +308,7 @@ EXEC SQL CONNECT TO dbname; - + Queries @@ -393,7 +379,7 @@ EXEC SQL COMMIT; - + 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 - Usage + Examples @@ -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 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 d2ab719fe3..7969489f11 100644 --- 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 44e38f28bc..9e5f4452d0 100644 --- 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 0d951621d1..e89d76bbc1 100644 --- 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 f78c053320..a242dcc863 100644 --- 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 0d2a7e93dd..f052e5af6e 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,5 +1,5 @@ @@ -338,10 +338,82 @@ PostgreSQL documentation - - - Outputs - + + + + 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 + + Examples 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 923a874111..b9f8554abf 100644 --- 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 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 - , , , and - 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 + < 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 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 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 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 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 and + 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 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 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 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 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 - - - Lists all available aggregate functions, together with the data - type they operate on. If pattern (a regular expression) - is specified, only matching aggregates are shown. - - - + + Connecting To A Database - - \dd [ object ] - - - Shows the descriptions of 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 + , , , and + 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 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 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 ] - + \cd directory + - Lists all data types or only those that match 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 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 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 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 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. + + - + - 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 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 filename or pipes the output - into a separate Unix shell to execute 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 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 pattern (a regular expression) + is specified, only matching aggregates are shown. - - \i filename + \dd [ object ] - Reads input from the file filename and executes it as - though it had been typed on the keyboard. + Shows the descriptions of 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 pattern (a regular expression) + is specified, only matching domains are shown. - \lo_export loid filename + \df [ pattern ] - - - Reads the large object with OID loid from the database and - writes it to 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 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 filename or pipes future results - into a separate Unix shell to execute command. If no arguments are - specified, the query output will be reset to - stdout. + Lists all data types or only those that match 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 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 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 filename or pipes the output + into a separate Unix shell to execute 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 filename. If 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 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 loid from the database and + writes it to 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 name to 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 table_options. + Saves future query results to the file filename or pipes future results + into a separate Unix shell to execute 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 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 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 - < 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 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 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 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 filename. If 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 name to 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 and - 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 table_options. + + + - - -U, --username username - - - Connects to the database as the user 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 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 - + Variables @@ -2063,11 +2009,10 @@ bar - - + - - <acronym>SQL</acronym> 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.) - - + - + 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). - - - + - - <acronym>GNU</acronym> readline + + Readline 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 b1c3cab01a..37debc1b84 100644 --- 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 - - - Inputs - vacuumdb accepts the following command line arguments: @@ -190,12 +212,12 @@ PostgreSQL documentation - + + + + + Diagnostics - - - Outputs - @@ -221,42 +243,30 @@ PostgreSQL documentation + - - - - - - - - Description - + + 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 + + + + + +