diff options
Diffstat (limited to 'doc/src/sgml/ref/psql-ref.sgml')
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 546 |
1 files changed, 312 insertions, 234 deletions
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 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.19 2000/01/12 19:36:34 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.20 2000/01/14 22:18:01 petere Exp $ Postgres documentation --> @@ -32,27 +32,20 @@ Postgres documentation <date>1998-09-26</date> </refsect2info> - <title>Input</title> - <para> - <application>psql</application> accepts many command-line arguments, - a rich set of meta-commands, and the full <acronym>SQL</acronym> language - supported by <productname>PostgreSQL</productname>. - </para> - </refsect2> + <title>Summary</title> - <refsect2 id="R2-APP-PSQL-2"> - <refsect2info> - <date>1998-10-26</date> - </refsect2info> - - <title>Output</title> <para> - <application>psql</application> 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 <acronym>SQL</acronym> - command or psql meta-command resulted in an error. + <application>psql</application> is a terminal-based front-end to + <productname>PostgreSQL</productname>. It enables you to type in queries + interactively, issue them to <productname>PostgreSQL</productname>, 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. </para> + </refsect2> + </refsynopsisdiv> <refsect1 id="R1-APP-PSQL-1"> @@ -62,58 +55,31 @@ Postgres documentation <title>Description</title> - <para> - <application>psql</application> is a character-based front-end to - <productname>PostgreSQL</productname>. It enables you to type in queries - interactively, issue them to <productname>PostgreSQL</productname>, 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. - </para> - - <para> - <application>psql</application> is a regular - <productname>PostgreSQL</productname> client application. Hence, a - <application>postmaster</application> process must be running on the database - server host before <application>psql</application> is executed. In addition, - the correct parameters to identify the database server, such as the - <application>postmaster</application> host name, may need to be specified as - described below. - </para> - - <para> - When <application>psql</application> starts, it reads <acronym>SQL</acronym> and psql commands - from <filename>/etc/psqlrc</filename> and then from - <filename>$<envar>HOME</envar>/.psqlrc</filename> - This allows commands like <command>\set</command> or the <acronym>SQL</acronym> command - <xref linkend="SQL-SET" endterm="SQL-SET-title">, which can be used to set a variety of options, - to be run at the start of every session. - </para> - - <para> - <application>psql</application> can be used in a pipe sequence, and - automatically detects when it is not used interactively. - </para> - - <refsect2 id="R2-APP-PSQL-3"> + <refsect2 id="R2-APP-PSQL-connecting"> <refsect2info> - <date>1998-09-26</date> + <date>2000-01-14</date> </refsect2info> <title>Connecting To A Database</title> <para> - <application>psql</application> 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 - <application>libpq</application> client library, upon which - <application>psql</application> is built, will choose defaults. - (This will usually mean the environment variables <envar>PGDATABASE</envar>, + <application>psql</application> is a regular <productname>PostgreSQL</productname> + 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. <application>psql</application> can be + told about those parameters via command line options, namely <option>-d</option>, + <option>-h</option>, <option>-p</option>, and <option>-U</option> respectively. + If an argument is found that does not belong to any option it will be interpreted + as 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 <envar>PGDATABASE</envar>, <envar>PGHOST</envar>, <envar>PGPORT</envar>, <envar>PGUSER</envar>, - 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. </para> <para> @@ -151,8 +117,9 @@ testdb=> <para> At the prompt, the user may type in <acronym>SQL</acronym> queries. Ordinarily, input lines are sent to the backend when a query-terminating - semicolon is reached. 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. </para> <para> @@ -173,12 +140,11 @@ testdb=> <para> Anything you enter in <application>psql</application> that begins with an - unquoted backslash is a <application>psql</application> meta-command. - Anything else is <acronym>SQL</acronym> 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, - <application>psql</application> meta-commands are more commonly called - slash or backslash commands. + unquoted backslash is a <application>psql</application> meta-command that is + processes by <application>psql</application> itself. + These commands are what makes + <application>psql</application> interesting for administration or scripting. + Meta-commands are more commonly called slash or backslash commands. </para> <para> @@ -268,11 +234,8 @@ testdb=> </para> <para> - If <replaceable class="parameter">username</replaceable> is omitted or - <literal>-</literal> the current user name is assumed. If - <replaceable class="parameter">username</replaceable> is <literal>?</literal> - <application>psql</application> will prompt for the new user name - interactively. + If <replaceable class="parameter">username</replaceable> is omitted + the current user name is assumed. </para> <para> @@ -293,10 +256,11 @@ testdb=> </varlistentry> <varlistentry> - <term><literal>\copy</literal> [ <literal>binary</literal> ] <replaceable class="parameter">table</replaceable> + <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable> [ <literal>with oids</literal> ] { <literal>from</literal> | <literal>to</literal> } - <replaceable class="parameter">filename</replaceable> [ <literal>with delimiters</literal> - '<replaceable class="parameter">character</replaceable>' ] + <replaceable class="parameter">filename</replaceable> | stdin | stdout + [ <literal>with delimiters</literal> '<replaceable class="parameter">characters</replaceable>' ] + [ <literal>with null as</literal> '<replaceable class="parameter">string</replaceable>' ] </term> <listitem> @@ -326,6 +290,18 @@ testdb=> technique may be preferable. </para> </tip> + + <note> + <para> + Note the difference in interpretation of <literal>stdin</literal> and <literal>stdout</literal> + between frontend and backend copies: In a frontend copy these always refer + to <application>psql</application>'s input and output stream. On a backend + copy <literal>stdin</literal> comes from whereever the <command>COPY</command> + itself came from (for example, a script ran with the <option>-f</option>) option, + and <literal>stdout</literal> refers to the query output stream (see + <command>\o</command> meta-command below). + </para> + </note> </listitem> </varlistentry> @@ -666,7 +642,7 @@ Tue Oct 26 21:40:57 CEST 1999 </tip> <note> <para> - See the description of the <envar>lo_transaction</envar> variable for + See the description of the <envar>LO_TRANSACTION</envar> variable for important information concerning all large object operations. </para> </note> @@ -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 - <command>\lo_list?</command> command. + <command>\lo_list</command> command. </para> <para> @@ -700,7 +676,7 @@ lo_import 152801 <note> <para> - See the description of the <envar>lo_transaction</envar> variable for + See the description of the <envar>LO_TRANSACTION</envar> variable for important information concerning all large object operations. </para> </note> @@ -733,7 +709,7 @@ lo_import 152801 </tip> <note> <para> - See the description of the <envar>lo_transaction</envar> variable for + See the description of the <envar>LO_TRANSACTION</envar> variable for important information concerning all large object operations. </para> </note> @@ -755,9 +731,11 @@ lo_import 152801 </para> <para> - <quote>Query results</quote> includes all tables and notices obtained + <quote>Query results</quote> includes all tables, command responses, + and notices obtained from the database server, as well as output of various backslash - commands that query the database (such as <command>\d</command>). + commands that query the database (such as <command>\d</command>), + but not error messages. </para> <tip> @@ -922,7 +900,7 @@ lo_import 152801 <para> Toggles the list of a pager to do table output. If the environment variable <envar>PAGER</envar> is set, the output is piped to the specified program. - Otherwise <filename>/bin/more</filename> is assumed. + Otherwise <filename>more</filename> is used. </para> <para> @@ -1024,10 +1002,8 @@ lo_import 152801 <para> Sets the internal variable <replaceable class="parameter">name</replaceable> to <replaceable class="parameter">value</replaceable>. If no second argument - is given, the variable is unset (which is different from setting it to, - for example, an empty string: <literal>\set foo ''</literal>). 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 <command>\unset</command> command. </para> <para> @@ -1192,14 +1168,7 @@ Access permissions for database "test" <para> If so configured, <application>psql</application> understands both standard Unix short options, and <acronym>GNU</acronym>-style long options. The latter - are not available on all systems, so you are advised to consider carefully - whether to use them. - </para> - - <para> - 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. </para> <para> @@ -1221,8 +1190,7 @@ Access permissions for database "test" <para> Specifies that <application>psql</application> is to execute one query string, <replaceable class="parameter">query</replaceable>, - and then exit. This is useful for shell scripts, typically in - conjunction with the <option>-q</option> option. + and then exit. This is useful for shell scripts. </para> <para> <replaceable class="parameter">query</replaceable> must be either a query string @@ -1254,20 +1222,20 @@ Access permissions for database "test" <listitem> <para> In non-interactive mode, all lines are printed to the screen as they are read. - This is equivalent to setting the variable <envar>echo</envar>. + This is equivalent to setting the variable <envar>ECHO</envar> to <literal>full</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term>-E, --echo-all</term> + <term>-E, --echo-hidden</term> <listitem> <para> 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 - <envar>echo_secret</envar> from within <application>psql</application>. + <envar>ECHO_HIDDEN</envar> from within <application>psql</application>. </para> </listitem> </varlistentry> @@ -1337,7 +1305,7 @@ Access permissions for database "test" <term>-n, --no-readline</term> <listitem> <para> - 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. </para> </listitem> </varlistentry> @@ -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>-c</option> option. Within <application>psql</application> you can - also set the <envar>quiet</envar> variable to achieve the same effect. + also set the <envar>QUIET</envar> variable to achieve the same effect. </para> </listitem> </varlistentry> @@ -1411,7 +1379,7 @@ Access permissions for database "test" <term>-S, --single-line</term> <listitem> <para> - 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. </para> <note> @@ -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 <acronym>SQL</acronym> 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. </para> </note> </listitem> @@ -1472,9 +1439,7 @@ Access permissions for database "test" <listitem> <para> Connects to the database as the user <replaceable class="parameter">username</replaceable> - instead of the default. (You must have permission to do so, of course.) If - <replaceable class="parameter">username</replaceable> is <quote>?</quote>, <application>psql</application> - issues an interactive prompt for the user name. + instead of the default. (You must have permission to do so, of course.) </para> </listitem> </varlistentry> @@ -1486,7 +1451,9 @@ Access permissions for database "test" <para> Performs a variable assignment, like the <command>\set</command> internal command. Note that you must separate name and value, if any, by an equal sign on the command - line. + 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. </para> </listitem> </varlistentry> @@ -1503,7 +1470,7 @@ Access permissions for database "test" <varlistentry> - <term>-W</term> + <term>-W, --password</term> <listitem> <para> Requests that <application>psql</application> should prompt for a password @@ -1518,26 +1485,28 @@ Access permissions for database "test" Because this is currently based on a <quote>hack</quote> 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 <envar>PGPASSWORD</envar> is - taken. If this is not set, the connection attempt will fail. + the connection attempt will fail. </para> + </listitem> + </varlistentry> + - <caution> + <varlistentry> + <term>-x, --expanded</term> + <listitem> <para> - If you are considering setting the variable <envar>PGPASSWORD</envar> to do - authentication, you have a problem. + Turns on extended row format mode. This is equivalent to the command + <command>\x</command>. </para> - </caution> </listitem> </varlistentry> <varlistentry> - <term>-x</term> + <term>-?, --help</term> <listitem> <para> - Turns on extended row format mode. This is equivalent to the command - <command>\x</command>. + Shows help about <application>psql</application> command line arguments. </para> </listitem> </varlistentry> @@ -1545,12 +1514,6 @@ Access permissions for database "test" </variablelist> </para> - <para> - You may set environment variables to avoid typing some of the above - options. See the section <quote>Connection To A Database</quote> above - and in particular the documentation of the <application>libpq</application> - client library. - </para> </refsect1> @@ -1585,7 +1548,7 @@ bar testdb=> <userinput>\echo "foo is now ${foo}."</userinput> foo is now bar. </programlisting> - (The curly braces are required. This is not <productname>Perl</productname>.) 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., <command>\copy</command>). </para> @@ -1605,52 +1568,70 @@ foo is now bar. </note> <para> - <application>psql</application>'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. - </para> - - <para> - If you attempt to refer to a variable that is not set, - <application>psql</application> first checks if it is the name of one of - several defined <quote>magic</quote> 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 <quote>shadow</quote> 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. - </para> - - <para> - Currently, the following <quote>magic</quote> variables are defined: - <envar>Version</envar> which contains a string with the version of - <application>psql</application>; <envar>Database</envar>, <envar>Host</envar>, - <envar>Port</envar>, <envar>User</envar> are the currently active - connection options. <envar>LastOid</envar> contains the oid that was the - result of the last <command>INSERT</command> or <command>\lo_import</command> - command. If the last command was not one of those two, the value - is undefined. + If you call <command>\set</command> without an argument, the variable is simply + set, but has no value. To unset (or delete) a variable, use the command + <command>\unset</command>. </para> <para> + <application>psql</application>'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 <application>psql</application>. 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 <quote>boolean</quote> 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. <variablelist> <varlistentry> - <term><envar>die_on_error</envar></term> + <term><envar>DBNAME</envar></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>ECHO</envar></term> + <listitem> + <para> + If set to <quote><literal>full</literal></quote>, 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>-f</option> option perhaps, use the switch <option>-e</option>. + If set to <quote><literal>brief</literal></quote>, <application>psql</application> + merely prints all queries as they are sent to the backend. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>ECHO_HIDDEN</envar></term> + <listitem> + <para> + When this variable is set and a backslash command queries the database, the query + is first shown. This way you can study the <productname>PostgreSQL</productname> + internals and provide similar functionality in your own programs. If you set the + variable to the value <quote>noexec</quote>, the queries are just shown but are + not actually sent to the backend and executed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>EXIT_ON_ERROR</envar></term> <listitem> <para> By default, if non-interactive scripts encounter an error, such as a malformed <acronym>SQL</acronym> 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 + <application>psql</application>but 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 <application>psql</application> @@ -1662,31 +1643,80 @@ foo is now bar. </varlistentry> <varlistentry> - <term><envar>echo</envar></term> + <term><envar>HISTCONTROL</envar></term> <listitem> <para> - 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>-f</option> option perhaps, use the switch <option>-e</option>. + If this variable is set to <literal>ignorespace</literal>, lines which begin with a + space are not entered into the history list. If set to a value of + <literal>ignoredups</literal>, lines matching the previous history line are not + entered. A value of <literal>ignoreboth</literal> 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. </para> + <note> + <para> + This feature was shamelessly plagiarized from <application>bash</application>. + </para> + </note> </listitem> </varlistentry> <varlistentry> - <term><envar>echo_secret</envar></term> + <term><envar>HISTSIZE</envar></term> <listitem> <para> - When this variable is set and a backslash command queries the database, the query - is first shown. This way you can study the <productname>PostgreSQL</productname> - internals and provide similar functionality in your own programs. If you set the - variable to the value <quote>noexec</quote>, 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. + </para> + <note> + <para> + This feature was shamelessly plagiarized from <application>bash</application>. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>HOST</envar></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>IGNOREEOF</envar></term> + <listitem> + <para> + If unset, sending an EOF character (usually Control-D) to an interactive session of + <application>psql</application> 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. + </para> + <note> + <para> + This feature was shamelessly plagiarized from <application>bash</application>. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>LASTOID</envar></term> + <listitem> + <para> + The value of the last affected oid, as returned from an <command>INSERT</command> + or <command>lo_insert</command> commmand. This variable is only guaranteed to be + valid until after the result of the next <acronym>SQL</acronym> command has been + displayed. </para> </listitem> </varlistentry> <varlistentry> - <term><envar>lo_transaction</envar></term> + <term><envar>LO_TRANSACTION</envar></term> <listitem> <para> If you use the <productname>PostgreSQL</productname> large object @@ -1702,7 +1732,7 @@ foo is now bar. all. In the latter case you must provide you own <command>BEGIN TRANSACTION</command>/<command>COMMIT</command> block or the results will be unpredictable (usually resulting in the desired - action not being performed anyway). + action not being performed in any case). </para> <para> @@ -1717,7 +1747,17 @@ foo is now bar. </varlistentry> <varlistentry> - <term><envar>prompt1</envar>, <envar>prompt2</envar>, <envar>prompt3</envar></term> + <term><envar>PORT</envar></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PROMPT1</envar>, <envar>PROMPT2</envar>, <envar>PROMPT3</envar></term> <listitem> <para> These specify what the prompt <application>psql</application> issues is @@ -1729,7 +1769,7 @@ foo is now bar. </varlistentry> <varlistentry> - <term><envar>quiet</envar></term> + <term><envar>QUIET</envar></term> <listitem> <para> This variable is equivalent to the command line option <option>-q</option>. @@ -1739,7 +1779,7 @@ foo is now bar. </varlistentry> <varlistentry> - <term><envar>singleline</envar></term> + <term><envar>SINGLELINE</envar></term> <listitem> <para> This variable is set be the command line options <option>-S</option>. You @@ -1749,13 +1789,24 @@ foo is now bar. </varlistentry> <varlistentry> - <term><envar>singlestep</envar></term> + <term><envar>SINGLESTEP</envar></term> <listitem> <para> This variable is equivalent to the command line option <option>-s</option>. </para> </listitem> </varlistentry> + + <varlistentry> + <term><envar>USER</envar></term> + <listitem> + <para> + The database user you are currently connected as. This is set everytime + you connect to a database (including program startup), but can be unset. + </para> + </listitem> + </varlistentry> + </variablelist> </para> @@ -1814,6 +1865,15 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp be better off preparing the file externally. </para> + <para> + Since colons may legally appear in queries, the following rule applies: If the variable + is not set, the character sequence <quote>colon-name</quote> 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 <acronym>SQL</acronym> for embedded + query languages, such as <application>ecpg</application>. The colon syntax for + array slices and type casts are <productname>PostgreSQL</productname> extensions.) + </para> + </refsect2> @@ -1822,8 +1882,8 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp <para> The prompts <application>psql</application> issues can be customized to - your preference. The three variables <envar>prompt1</envar>, <envar>prompt2</envar>, - and <envar>prompt3</envar> contain strings and special escape sequences + your preference. The three variables <envar>PROMPT1</envar>, <envar>PROMPT2</envar>, + and <envar>PROMPT3</envar> contain strings and special escape sequences that describe the appearance of the prompt. Prompt 1 is the normal prompt that is issued when <application>psql</application> requests a new query. Prompt 2 is issued when more input is expected during query input because @@ -1924,8 +1984,75 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp and 2, and <literal>'>> '</literal> for prompt 3. </para> + <note> + <para> + This feature was shamelessly plagiarized from <application>tcsh</application>. + </para> + </note> + </refsect2> + <refsect2 id="APP-PSQL-MISC"> + <title id="APP-PSQL-MISC-title">Miscellaneous</title> + + <para> + <application>psql</application> returns 0 to the shell if it finished normally, + 1 if a fatal error of its own (out of memory, file not found) occurs, 2 if the + connection to the backend went bad and the session is not interactive, and 3 if + an error occurred in a script and the variable <envar>EXIT_ON_ERROR</envar> was + set. + </para> + + <para> + Before starting up in interactive mode, <application>psql</application> attempts + to read and execute the files <filename>/etc/psqlrc</filename> and + <filename>$HOME/.psqlrc</filename>. They could be used to set up the client or + the server to taste (using the <command>\set</command> and <command>SET</command> + commands). + </para> + + </refsect2> + + <refsect2> + <title><acronym>GNU</acronym> readline</title> + + <para> + <application>psql</application> supports the readline and history libraries for + convenienent line editing and retrieval. The command history is stored in a file + named <filename>.psqlrc</filename> in your home directory and is reloaded when + <application>psql</application> starts up. + Tab-completion is also supported, although + the completion logic makes no claim to be an <acronym>SQL</acronym> parser. + When available, <application>psql</application> is automatically built to use these + features. + </para> + + <para> + If you have the readline library installed but <application>psql</application> + does not seem to use it, you must make sure that <productname>PostgreSQL</productname>'s + top-level <filename>configure</filename> script finds it. <filename>configure</filename> + needs to find both the library <filename>libreadline.a</filename> + (or <filename>libreadline.so</filename> on systems with shared libraries) + <emphasis>and</emphasis> the header files <filename>readline.h</filename> and + <filename>history.h</filename> (or <filename>readline/readline.h</filename> and + <filename>readline/history.h</filename>) in appropriate directories. If + you have the library and header files installed in an obscure place you + must tell <filename>configure</filename> about them, for example: +<programlisting> +$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib ... +</programlisting> + Then you have to recompile <application>psql</application> (not necessarily + the entire code tree). + </para> + + <para> + The <acronym>GNU</acronym> readline library can be obtained from the <acronym>GNU</acronym> + project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>. + </para> + </refsect2> + + + </refsect1> @@ -2074,23 +2201,9 @@ Field separator is "oo". <listitem> <para> - There are about three different parsers in <application>psql</application>, - in addition to the backend <acronym>SQL</acronym> 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 - <quote><xref linkend="APP-PSQL-sql-interpol" endterm="APP-PSQL-sql-interpol-title"></quote>. - There are vague dreams of using <application>flex</application> in the future, - but it won't happen soon. - </para> - </listitem> - - <listitem> - <para> - 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 <application>psql</application> with - a different backend than the one it was configured for, you might encounter - these limits sooner rather than later. + <application>psql</application> 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. </para> </listitem> @@ -2098,7 +2211,7 @@ Field separator is "oo". <para> 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. </para> </listitem> @@ -2106,41 +2219,6 @@ Field separator is "oo". </refsect2> - <refsect2> - <title><acronym>GNU</acronym> readline</title> - - <para> - A great deal of <application>psql</application>'s convenience is owed to it - using the <acronym>GNU</acronym> readline and history library for accepting - and storing user input. To verify whether your copy of <application>psql</application> - was compiled with readline support, execute <literal>psql -V</literal> and check the - output for the words <quote>readline</quote> and <quote>history</quote>. - </para> - - <para> - If you have the readline library installed but <application>psql</application> - does not seem to use it, you must make sure that <productname>PostgreSQL</productname>'s - top-level <filename>configure</filename> script finds it. <filename>configure</filename> - needs to find both the library <filename>libreadline.a</filename> - (or <filename>libreadline.so</filename> on systems with shared libraries) - <emphasis>and</emphasis> the header files <filename>readline.h</filename> and - <filename>history.h</filename> (or <filename>readline/readline.h</filename> and - <filename>readline/history.h</filename>) in appropriate directories. If - you have the library and header files installed in an obscure place you - must tell <filename>configure</filename> about them, for example: -<programlisting> -$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib ... -</programlisting> - Then you have to recompile <application>psql</application> (not necessarily - the entire code tree). - </para> - - <para> - The <acronym>GNU</acronym> readline library can be obtained from the <acronym>GNU</acronym> - project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>. - </para> - </refsect2> - </refsect1> </refentry> |