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. - - - - 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. - + + + Environment + + + + 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. - - - - 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. - + + + Environment + + + + 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 + - - Files + + + Environment + + + + 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,23 +38,412 @@ 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. + + + + + + -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. + + + + + + -e, --echo-queries + + + Show all queries that are sent to the backend. This is equivalent + to setting the variable ECHO to + queries. + + + + + + -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. + + + + + + -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. + + + + If filename is - + (hyphen), then standard input is read. + + + + 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. + + + + + + -F, --field-separator separator + + + Use separator as the + field separator. This is equivalent to \pset + fieldsep or \f. + + + + + + -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. + + + + + + -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. + + + + + + -o, --output filename + + + Put all query output into file filename. This is equivalent to + the command \o. + + + + + + -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. + + + + + + -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. + + + + + + -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. + + + + + + -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. + + + + + + -S, --single-line + + + Runs in single-line mode where a newline terminates a query, as a + semicolon does. + + + + + 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. + + + + + + + -t, --tuples-only + + + Turn off printing of column names and result row count footers, + etc. It is completely equivalent to the \t + meta-command. + + + + + + -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. + + + + 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. + + + + + + -U, --username username + + + Connects to the database as the user username instead of the default. + (You must have permission to do so, of course.) + + + + + + -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. + + + + + + -V, --version + + + Shows the psql version. + + + + + + -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. + + + + 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. + + + + + + -x, --expanded + + + Turns on extended row format mode. This is equivalent to the + command \x. + + + + + + -X, --no-psqlrc + + + Do not read the start-up file ~/.psqlrc. + + + + + + -?, --help + + + Shows help about psql command line + arguments. + + + + + + + + + Exit Status + + + 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. + + + + + + Usage - - 2000-01-14 - - Connecting To A Database @@ -96,10 +479,6 @@ PostgreSQL documentation - - 1998-09-26 - - Entering Queries @@ -137,14 +516,9 @@ testdb=> . - - - - 1998-09-26 - - - <application>psql</application> Meta-Commands + + Meta-Commands Anything you enter in psql that begins @@ -1038,8 +1412,8 @@ lo_import 152801 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. + is piped to the specified program. Otherwise a platform-dependent default (such as + more) is used. @@ -1314,440 +1688,12 @@ Access permissions for database "test" - + + + Advanced features - - - - 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. - - - - - - - -e, --echo-queries - - - Show all queries that are sent to the backend. This is equivalent - to setting the variable ECHO to - queries. - - - - - - - -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. - - - - - - - -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. - - - - If filename is - - (hyphen), then standard input is read. - - - - 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. - - - - - - - -F, --field-separator separator - - - Use separator as the - field separator. This is equivalent to \pset - fieldsep or \f. - - - - - - - -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. - - - - - - - -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. - - - - - - - -o, --output filename - - - Put all query output into file filename. This is equivalent to - the command \o. - - - - - - - -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. - - - - - - - -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. - - - - - - - -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. - - - - - - - -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. - - - - - - - -S, --single-line - - - Runs in single-line mode where a newline terminates a query, as a - semicolon does. - - - - - 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. - - - - - - - - -t, --tuples-only - - - Turn off printing of column names and result row count footers, - etc. It is completely equivalent to the \t - meta-command. - - - - - - - -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. - - - - 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. - - - - - - - -U, --username username - - - Connects to the database as the user username instead of the default. - (You must have permission to do so, of course.) - - - - - - - -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. - - - - - - - -V, --version - - - Shows the psql version. - - - - - - - -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. - - - - 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. - - - - - - - -x, --expanded - - - Turns on extended row format mode. This is equivalent to the - command \x. - - - - - - - -X, --no-psqlrc - - - Do not read the start-up file ~/.psqlrc. - - - - - - - -?, --help - - - Shows help about psql command line - arguments. - - - - - - - - - - - - - 1998-09-27 - - - 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 - - - - 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. - - - - Usage + + + Environment + + + + PGHOST + PGPORT + PGUSER + + + + Default connection parameters. + + + + + + + + + Examples @@ -290,6 +300,15 @@ PostgreSQL documentation + + + See Also + + + + + +