From 7c9390caa14ea2d5d99d69d2a34eee4d45d43b9c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 14 Jan 2000 22:18:03 +0000 Subject: Fixed psql variables vs array syntax, as well as minor psql enhancements --- doc/src/sgml/ref/psql-ref.sgml | 546 +++++++++++++++++++++++------------------ 1 file changed, 312 insertions(+), 234 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 5c92e5fbd1b..88a15fe631e 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -32,27 +32,20 @@ Postgres documentation 1998-09-26 - Input - - psql accepts many command-line arguments, - a rich set of meta-commands, and the full SQL language - supported by PostgreSQL. - - + Summary - - - 1998-10-26 - - - Output - psql returns 0 to the shell on successful - completion of all queries, 1 for fatal errors, 2 for abrupt disconnection - from the backend, and 3 if a non-interactive script stopped because an SQL - command or psql meta-command resulted in an error. + psql is a terminal-based front-end to + PostgreSQL. It enables you to type in queries + interactively, issue them to PostgreSQL, and see + the query results. Alternatively, input can be from a file. + In addition, it provides a number of meta-commands and + various shell-like features to facilitate writing scripts and automating a wide + variety of tasks. + + @@ -62,58 +55,31 @@ Postgres documentation Description - - psql is a character-based front-end to - PostgreSQL. It enables you to type in queries - interactively, issue them to PostgreSQL, and see - the query results. In addition, it provides a number of meta-commands and - various shell-like features to facilitate writing scripts and automating a wide - variety of tasks. - - - - psql is a regular - PostgreSQL client application. Hence, a - postmaster process must be running on the database - server host before psql is executed. In addition, - the correct parameters to identify the database server, such as the - postmaster host name, may need to be specified as - described below. - - - - When psql starts, it reads SQL and psql commands - from /etc/psqlrc and then from - $HOME/.psqlrc - This allows commands like \set or the SQL command - , which can be used to set a variety of options, - to be run at the start of every session. - - - - psql can be used in a pipe sequence, and - automatically detects when it is not used interactively. - - - + - 1998-09-26 + 2000-01-14 Connecting To A Database - psql attempts to make a connection to the - database name at the hostname and port number, and with the user name - specified on the command line. If any of these are omitted, the - libpq client library, upon which - psql is built, will choose defaults. - (This will usually mean the environment variables PGDATABASE, + psql is a regular PostgreSQL + client application. In order to connect to a database you need to determine + name of you target database, the hostname 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 database name as well. Not all these options are required, defaults do apply. + If you omit the host name psql will connect via domain sockets to a server on the + local host. The default port number is compile-time determined. Since the database + server uses the same default, chances are you don't have to specify the port in most + settings. The default user name is your Unix username, the same with the database. + Note that you can't just connect to any database under any username. 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, PGUSER, - respectively, if they are set. Otherwise the default host is the local host - via Unix domain sockets, the default port is decided at compile time, - the default user is the system user name, and the default database is - the one with the same name as the user.) + respectively to appropriate values. @@ -151,8 +117,9 @@ 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. If the database server reports success, the query - results are displayed on the screen. + semicolon is reached. An end of line does not terminate a query! Thus queries + can be spread over serveral lines for clarity. If the query was sent and without + error the query results are displayed on the screen. @@ -173,12 +140,11 @@ testdb=> Anything you enter in psql that begins with an - unquoted backslash is a psql meta-command. - Anything else is SQL and simply goes into the current - query buffer (and once you have at least one complete query, it gets - automatically submitted to the backend). For this reason, - psql meta-commands are more commonly called - slash or backslash commands. + unquoted backslash is a psql meta-command that is + processes by psql itself. + These commands are what makes + psql interesting for administration or scripting. + Meta-commands are more commonly called slash or backslash commands. @@ -268,11 +234,8 @@ testdb=> - If username is omitted or - - the current user name is assumed. If - username is ? - psql will prompt for the new user name - interactively. + If username is omitted + the current user name is assumed. @@ -293,10 +256,11 @@ testdb=> - \copy [ binary ] table + \copy table [ with oids ] { from | to } - filename [ with delimiters - 'character' ] + filename | stdin | stdout + [ with delimiters 'characters' ] + [ with null as 'string' ] @@ -326,6 +290,18 @@ testdb=> technique may be preferable. + + + + 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 whereever the COPY + itself came from (for example, a script ran with the ) option, + and stdout refers to the query output stream (see + \o meta-command below). + + @@ -666,7 +642,7 @@ Tue Oct 26 21:40:57 CEST 1999 - See the description of the lo_transaction variable for + See the description of the LO_TRANSACTION variable for important information concerning all large object operations. @@ -689,7 +665,7 @@ lo_import 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. + \lo_list command. @@ -700,7 +676,7 @@ lo_import 152801 - See the description of the lo_transaction variable for + See the description of the LO_TRANSACTION variable for important information concerning all large object operations. @@ -733,7 +709,7 @@ lo_import 152801 - See the description of the lo_transaction variable for + See the description of the LO_TRANSACTION variable for important information concerning all large object operations. @@ -755,9 +731,11 @@ lo_import 152801 - Query results includes all tables and notices obtained + 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). + commands that query the database (such as \d), + but not error messages. @@ -922,7 +900,7 @@ lo_import 152801 Toggles the list of a pager to do table output. If the environment variable PAGER is set, the output is piped to the specified program. - Otherwise /bin/more is assumed. + Otherwise more is used. @@ -1024,10 +1002,8 @@ lo_import 152801 Sets the internal variable name to value. If no second argument - is given, the variable is unset (which is different from setting it to, - for example, an empty string: \set foo ''). If no - arguments are given, all currently defined variables are listed with their - values. + is given, the variable is just set with not value. To unset a variable, use + the \unset command. @@ -1192,14 +1168,7 @@ Access permissions for database "test" If so configured, psql understands both standard Unix short options, and GNU-style long options. The latter - are not available on all systems, so you are advised to consider carefully - whether to use them. - - - - Many command line options are equivalent to an internal slash command or to - setting some variable. Those will not be explained in detail here. Instead, - you are asked to look them up in the respective section. + are not available on all systems. @@ -1221,8 +1190,7 @@ Access permissions for database "test" Specifies that psql is to execute one query string, query, - and then exit. This is useful for shell scripts, typically in - conjunction with the option. + and then exit. This is useful for shell scripts. query must be either a query string @@ -1254,20 +1222,20 @@ Access permissions for database "test" In non-interactive mode, all lines are printed to the screen as they are read. - This is equivalent to setting the variable echo. + This is equivalent to setting the variable ECHO to full. - -E, --echo-all + -E, --echo-hidden Echos 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_secret from within psql. + ECHO_HIDDEN from within psql. @@ -1337,7 +1305,7 @@ Access permissions for database "test" -n, --no-readline - Do not use the readline library for input line editing and command history. + Do not use readline for line editing and do not use the history. @@ -1389,7 +1357,7 @@ Access permissions for database "test" 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. + also set the QUIET variable to achieve the same effect. @@ -1411,7 +1379,7 @@ Access permissions for database "test" -S, --single-line - Runs in single-line mode where a newline sends a query, in addition to a semicolon. + Runs in single-line mode where a newline terminates a query, like a semicolon would do. @@ -1419,8 +1387,7 @@ Access permissions for database "test" 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 unexperienced user. Moral: Unless you exclusively type short queries, - avoid using this mode. + the unexperienced user. @@ -1472,9 +1439,7 @@ Access permissions for database "test" Connects to the database as the user username - instead of the default. (You must have permission to do so, of course.) If - username is ?, psql - issues an interactive prompt for the user name. + instead of the default. (You must have permission to do so, of course.) @@ -1486,7 +1451,9 @@ Access permissions for database "test" 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. + line. To unset a variable, leave off the equal sign. These assignments are done + during a very early state of startup, so variables reserved for internal purposes + might get overwritten again. @@ -1503,7 +1470,7 @@ Access permissions for database "test" - -W + -W, --password Requests that psql should prompt for a password @@ -1518,26 +1485,28 @@ Access permissions for database "test" 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 content of the environment variable PGPASSWORD is - taken. If this is not set, the connection attempt will fail. + the connection attempt will fail. + + + - + + -x, --expanded + - If you are considering setting the variable PGPASSWORD to do - authentication, you have a problem. + Turns on extended row format mode. This is equivalent to the command + \x. - - -x + -?, --help - Turns on extended row format mode. This is equivalent to the command - \x. + Shows help about psql command line arguments. @@ -1545,12 +1514,6 @@ Access permissions for database "test" - - You may set environment variables to avoid typing some of the above - options. See the section Connection To A Database above - and in particular the documentation of the libpq - client library. - @@ -1585,7 +1548,7 @@ bar testdb=> \echo "foo is now ${foo}." foo is now bar. - (The curly braces are required. This is not Perl.) No variable substitution + (The curly braces are required.) No variable substitution will be performed in single-quoted strings or in any of the backslash commands that have special parsing rules (e.g., \copy). @@ -1605,52 +1568,70 @@ foo is now bar. - psql's internal variable names can consist of - letters, numbers, and underscores in any order and any number of them. - It is recommended, however, that you stick to lower-case letters and do not - begin with a digit. The partial rationale for this follows. - - - - If you attempt to refer to a variable that is not set, - psql first checks if it is the name of one of - several defined magic variables. Those variables are - maintained internally and always have a value (at least when their semantics - permit it). By convention they all start with an upper-case letter. You can - set those variables manually, but that will shadow their - special meaning, until you unset your personal copy. Finally, if no match is - found that way, the value of the respective environment variable is - substituted. - - - - Currently, the following magic variables are defined: - Version which contains a string with the version of - psql; Database, Host, - Port, User are the currently active - connection options. LastOid contains the oid that was the - result of the last INSERT or \lo_import - command. If the last command was not one of those two, the value - is undefined. + If you call \set without an argument, the variable is simply + set, but has no value. To unset (or delete) a variable, use the command + \unset. + psql's internal variable names can consist of + letters, numbers, and underscores in any order and any number of them. A number of regular variables are treated specially by psql. They indicate certain option settings that can be changed at runtime - by altering the value of the variable. Although you can use these + by altering the value of the variable or represent some state of the application. + Although you can use these variables for any other purpose, this is not recommended, as the - program behavior might grow really strange really quickly. Note that the - majority variables are boolean variables, that is, they - only care whether or not are they set, not what to. A list of all specially - treated variables follows. + program behavior might grow really strange really quickly. + By convention, all specially treated variables consist of all upper-case letters + (and possibly numbers and underscores). To ensure maximum compatibility in the + future, avoid such variables. + A list of all specially treated variables follows. - die_on_error + DBNAME + + + The name of the database you are currently connected to. This is set everytime + you connect to a database (including program startup), but can be unset. + + + + + + ECHO + + + If set to full, all lines entered or from a script + are written to the standard output before they + are parsed or executed. To specify this on program startup, in conjunction with the + option perhaps, use the switch . + If set to brief, psql + merely prints all queries as they are sent to the backend. + + + + + + ECHO_HIDDEN + + + When this variable is set and a backslash command queries the database, the query + is first shown. This way you can study the PostgreSQL + internals and provide similar functionality in your own programs. If you set the + variable to the value noexec, the queries are just shown but are + not actually sent to the backend and executed. + + + + + + EXIT_ON_ERROR By default, if non-interactive scripts encounter an error, such as a malformed SQL query or internal meta-command, - processing continues. This is often less than desirable. If this variable + processing continues. This is has been the traditional behaviour of + psqlbut is often less than desirable. If this variable is set, script processing will immediately terminate. If the script was called from another script it will terminate in the same fashion. If the outermost script was not called from an interactive psql @@ -1662,31 +1643,80 @@ foo is now bar. - echo + HISTCONTROL - If set, all lines from a script are written to the standard output before they - are executed. To specify this on program startup, in conjunction with the - option perhaps, use the switch . + If this variable is set to ignorespace, lines which begin with a + space are not entered into the history list. If set to a value of + ignoredups, lines matching the previous history line are not + entered. A value of ignoreboth combines the two + options. If unset, or if set to any other value than those above, all lines read + in interactive mode are saved on the history list. + + + This feature was shamelessly plagiarized from bash. + + - echo_secret + HISTSIZE - When this variable is set and a backslash command queries the database, the query - is first shown. This way you can study the PostgreSQL - internals and provide similar functionality in your own programs. If you set the - variable to the value noexec, the queries are just shown but are - not actually sent to the backend and executed. + The number of commands to store in the command history. + The default value is 500. + + + + This feature was shamelessly plagiarized from bash. + + + + + + + HOST + + + The database server host you are currently connected to. This is set everytime + you connect to a database (including program startup), but can be unset. + + + + + + IGNOREEOF + + + If unset, sending an EOF character (usually Control-D) to an interactive session of + psql will terminate the application. + If set to a numeric value, that many EOF characters are ignored before the application + terminates. If the variable is set but has no numeric value, the default is 10. + + + + This feature was shamelessly plagiarized from bash. + + + + + + + LASTOID + + + The value of the last affected oid, as returned from an INSERT + or lo_insert commmand. This variable is only guaranteed to be + valid until after the result of the next SQL command has been + displayed. - lo_transaction + LO_TRANSACTION If you use the PostgreSQL large object @@ -1702,7 +1732,7 @@ foo is now bar. all. In the latter case you must provide you own BEGIN TRANSACTION/COMMIT block or the results will be unpredictable (usually resulting in the desired - action not being performed anyway). + action not being performed in any case). @@ -1717,7 +1747,17 @@ foo is now bar. - prompt1, prompt2, prompt3 + PORT + + + The database server port you are currently connected to. This is set everytime + you connect to a database (including program startup), but can be unset. + + + + + + PROMPT1, PROMPT2, PROMPT3 These specify what the prompt psql issues is @@ -1729,7 +1769,7 @@ foo is now bar. - quiet + QUIET This variable is equivalent to the command line option . @@ -1739,7 +1779,7 @@ foo is now bar. - singleline + SINGLELINE This variable is set be the command line options . You @@ -1749,13 +1789,24 @@ foo is now bar. - singlestep + SINGLESTEP This variable is equivalent to the command line option . + + + USER + + + The database user you are currently connected as. This is set everytime + you connect to a database (including program startup), but can be unset. + + + + @@ -1814,6 +1865,15 @@ testdb=> \set content `sed -e "s/'/\\\\\\'/g" < my_file.txt` + + Since colons may legally appear in queries, the following rule applies: If the variable + is not set, the character sequence colon-name is not changed. In any + case you can escape a colon with a backslash to protect it from interpretation. + (The colon syntax for variables is standard SQL for embedded + query languages, such as ecpg. The colon syntax for + array slices and type casts are PostgreSQL extensions.) + + @@ -1822,8 +1882,8 @@ testdb=> \set content `sed -e "s/'/\\\\\\'/g" < my_file.txt` The prompts psql issues can be customized to - your preference. The three variables prompt1, prompt2, - and prompt3 contain strings and special escape sequences + your preference. The three variables PROMPT1, PROMPT2, + and PROMPT3 contain strings and special escape sequences that describe the appearance of the prompt. Prompt 1 is the normal prompt that is issued when psql requests a new query. Prompt 2 is issued when more input is expected during query input because @@ -1924,8 +1984,75 @@ testdb=> \set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`'>> ' for prompt 3. + + + This feature was shamelessly plagiarized from tcsh. + + + + + 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 EXIT_ON_ERROR was + set. + + + + Before starting up in interactive mode, psql attempts + to read and execute the files /etc/psqlrc and + $HOME/.psqlrc. They could be used to set up the client or + the server to taste (using the \set and SET + commands). + + + + + + <acronym>GNU</acronym> readline + + + psql supports the readline and history libraries for + convenienent line editing and retrieval. The command history is stored in a file + named .psqlrc in your home directory and is reloaded when + psql starts up. + Tab-completion is also supported, although + the completion logic makes no claim to be an SQL parser. + When available, psql is automatically built to use these + features. + + + + If you have the readline library installed but psql + does not seem to use it, you must make sure that PostgreSQL's + top-level configure script finds it. configure + needs to find both the library libreadline.a + (or libreadline.so on systems with shared libraries) + and the header files readline.h and + history.h (or readline/readline.h and + readline/history.h) in appropriate directories. If + you have the library and header files installed in an obscure place you + must tell configure about them, for example: + +$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib ... + + Then you have to recompile psql (not necessarily + the entire code tree). + + + + The GNU readline library can be obtained from the GNU + project's FTP server at ftp://ftp.gnu.org. + + + + + @@ -2074,23 +2201,9 @@ Field separator is "oo". - There are about three different parsers in psql, - in addition to the backend SQL parser, all doing their own thing - and attempting to get along with each other. Sometimes they do, sometimes - they don't. An excellent example of this can be seen in section - . - There are vague dreams of using flex in the future, - but it won't happen soon. - - - - - - Several string buffers are assigned fixed sizes at compile time. These - are usually based on certain settings about what the backend can accept - for a particular quantity. If you use psql with - a different backend than the one it was configured for, you might encounter - these limits sooner rather than later. + psql only works smootly 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. @@ -2098,7 +2211,7 @@ Field separator is "oo". The number of options for a backslash command is limited, probably to 16. You can easily change this in the source code, and perhaps I will get around - to fixing this one day (see previous item). Not that there is any command + to fixing this one day. Not that there is any command that actually uses that many options though. @@ -2106,41 +2219,6 @@ Field separator is "oo". - - <acronym>GNU</acronym> readline - - - A great deal of psql's convenience is owed to it - using the GNU readline and history library for accepting - and storing user input. To verify whether your copy of psql - was compiled with readline support, execute psql -V and check the - output for the words readline and history. - - - - If you have the readline library installed but psql - does not seem to use it, you must make sure that PostgreSQL's - top-level configure script finds it. configure - needs to find both the library libreadline.a - (or libreadline.so on systems with shared libraries) - and the header files readline.h and - history.h (or readline/readline.h and - readline/history.h) in appropriate directories. If - you have the library and header files installed in an obscure place you - must tell configure about them, for example: - -$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib ... - - Then you have to recompile psql (not necessarily - the entire code tree). - - - - The GNU readline library can be obtained from the GNU - project's FTP server at ftp://ftp.gnu.org. - - - -- cgit v1.2.3