From dff689aa6518cd0100e296573e16f9175dd4c07e Mon Sep 17 00:00:00 2001 From: Catalin Iacob Date: Wed, 25 Nov 2015 08:04:43 +0100 Subject: [PATCH] Update docs for repeated -c --- doc/src/sgml/ref/psql-ref.sgml | 106 ++++++++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 44 deletions(-) diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 5899bb4..2928c92 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -38,9 +38,10 @@ PostgreSQL documentation 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. + Alternatively, input can be from a file or from command line + arguments. 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. @@ -89,38 +90,45 @@ PostgreSQL documentation - Specifies that psql is to execute one - command string, command, - and then exit. This is useful in shell scripts. Start-up files - (psqlrc and ~/.psqlrc) are - ignored with this option. + Specifies that psql is to execute the given + command string, command. + This option can be repeated and combined in any order with + the option. - command must be either - a command string that is completely parsable by the server (i.e., - it contains no psql-specific features), - or a single backslash command. Thus you cannot mix - SQL and psql - meta-commands with this option. To achieve that, you could - pipe the string into psql, for example: - echo '\x \\ SELECT * FROM foo;' | psql. + command must be either a + command string that is completely parsable by the server (i.e., it + contains no psql-specific features), or a + single backslash command. Thus you cannot mix + SQL and psql meta-commands + with this option. To achieve that, you could use + repeated options or pipe the string + into psql, for example: + psql -c '\x' -c 'SELECT * FROM foo;' or + echo '\x \\ SELECT * FROM foo;' | psql (\\ is the separator meta-command.) - If the command string contains multiple SQL commands, they are - processed in a single transaction, unless there are explicit - BEGIN/COMMIT commands included in the - string to divide it into multiple transactions. This is - different from the behavior when the same string is fed to - psql's standard input. Also, only - the result of the last SQL command is returned. + Each command string passed to is sent to the server + as a single query. Because of this, the server executes it as a single + transaction, even if a command string contains + multiple SQL commands, unless there are + explicit BEGIN/COMMIT commands included in the + string to divide it into multiple transactions. Also, the server only + returns the result of the last SQL command to the + client. This is different from the behavior when the same string with + multiple SQL commands is fed + to psql's standard input because + then psql sends each SQL + command separately. - Because of these legacy behaviors, putting more than one command in - the string often has unexpected results. It's - better to feed multiple commands to psql's - standard input, either using echo as - illustrated above, or via a shell here-document, for example: + Because of the execution as a single query, putting more than one + command in the string often has unexpected results. + It's better to use repeated commands or feed + multiple commands to psql's standard input, + either using echo as illustrated above, or + via a shell here-document, for example: psql <<EOF \x @@ -183,11 +191,13 @@ EOF - Use the file filename - as the source of commands instead of reading commands interactively. - After the file is processed, psql - terminates. This is in many ways equivalent to the meta-command - \i. + Use the file filename as + the source of commands instead of reading commands interactively. This + option can be repeated and combined in any order with + the option. After the commands in + every command string and file + are processed, psql terminates. This option + is in many ways equivalent to the meta-command \i. @@ -539,20 +549,21 @@ EOF - When psql executes a script, adding - this option wraps BEGIN/COMMIT around the - script to execute it as a single transaction. This ensures that - either all the commands complete successfully, or no changes are - applied. + When psql executes commands from a script + and/or a option, adding this option + wraps BEGIN/COMMIT around all of those + commands as a whole to execute them as a single transaction. This + ensures that either all the commands complete successfully, or no + changes are applied. - If the script itself uses BEGIN, COMMIT, + If the commands themselves + contain BEGIN, COMMIT, or ROLLBACK, this option will not have the desired - effects. - Also, if the script contains any command that cannot be executed - inside a transaction block, specifying this option will cause that - command (and hence the whole transaction) to fail. + effects. Also, if an individual command cannot be executed inside a + transaction block, specifying this option will cause the whole + transaction to fail. @@ -3725,7 +3736,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' psqlrc and ~/.psqlrc - Unless it is passed an or option, + Unless it is passed an option, psql attempts to read and execute commands from the system-wide startup file (psqlrc) and then the user's personal startup file (~/.psqlrc), after @@ -3819,6 +3830,13 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' + + + Before PostgreSQL 9.6, + used to imply and therefore it wouldn't + read psqlrc files, that is no longer the case. + + -- 2.6.2