diff options
Diffstat (limited to 'doc/src/sgml/ref/psql-ref.sgml')
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 44 |
1 files changed, 30 insertions, 14 deletions
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 2f944b1e975..e66101dbd59 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -837,21 +837,17 @@ testdb=> <term><literal>\c</literal> or <literal>\connect [ -reuse-previous=<replaceable class="parameter">on|off</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">host</replaceable> ] [ <replaceable class="parameter">port</replaceable> ] | <replaceable class="parameter">conninfo</replaceable> ]</literal></term> <listitem> <para> - Establishes a new connection to a <productname>PostgreSQL</> + Establishes a new connection to a <productname>PostgreSQL</productname> server. The connection parameters to use can be specified either - using a positional syntax, or using <replaceable>conninfo</> connection - strings as detailed in <xref linkend="libpq-connstring">. + using a positional syntax (one or more of database name, user, + host, and port), or using a <replaceable>conninfo</replaceable> + connection string as detailed in + <xref linkend="libpq-connstring">. If no arguments are given, a + new connection is made using the same parameters as before. </para> <para> - Where the command omits database name, user, host, or port, the new - connection can reuse values from the previous connection. By default, - values from the previous connection are reused except when processing - a <replaceable>conninfo</> string. Passing a first argument - of <literal>-reuse-previous=on</> - or <literal>-reuse-previous=off</literal> overrides that default. - When the command neither specifies nor reuses a particular parameter, - the <application>libpq</application> default is used. Specifying any + Specifying any of <replaceable class="parameter">dbname</replaceable>, <replaceable class="parameter">username</replaceable>, <replaceable class="parameter">host</replaceable> or @@ -860,11 +856,30 @@ testdb=> </para> <para> + The new connection can re-use connection parameters from the previous + connection; not only database name, user, host, and port, but other + settings such as <replaceable>sslmode</replaceable>. By default, + parameters are re-used in the positional syntax, but not when + a <replaceable>conninfo</replaceable> string is given. Passing a + first argument of <literal>-reuse-previous=on</literal> + or <literal>-reuse-previous=off</literal> overrides that default. If + parameters are re-used, then any parameter not explicitly specified as + a positional parameter or in the <replaceable>conninfo</replaceable> + string is taken from the existing connection's parameters. An + exception is that if the <replaceable>host</replaceable> setting + is changed from its previous value using the positional syntax, + any <replaceable>hostaddr</replaceable> setting present in the + existing connection's parameters is dropped. + When the command neither specifies nor reuses a particular parameter, + the <application>libpq</application> default is used. + </para> + + <para> If the new connection is successfully made, the previous connection is closed. - If the connection attempt failed (wrong user name, access - denied, etc.), the previous connection will only be kept if - <application>psql</application> is in interactive mode. When + If the connection attempt fails (wrong user name, access + denied, etc.), the previous connection will be kept if + <application>psql</application> is in interactive mode. But when executing a non-interactive script, processing will immediately stop with an error. This distinction was chosen as a user convenience against typos on the one hand, and a safety @@ -879,6 +894,7 @@ testdb=> => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" +=> \c -reuse-previous=on sslmode=require -- changes only sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp </programlisting> </listitem> |