<application>psql</application> operation, which uses the simple
query protocol. So this command can be useful to test the extended
query protocol from <application>psql</application>.
</para>
</listitem>
</varlistentry>
<varlistentry id="app-psql-meta-command-c-lc">
<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</productname>
server. The connection parameters to use can be specified either
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>
Specifying any
of <replaceable class="parameter">dbname</replaceable>,
<replaceable class="parameter">username</replaceable>,
<replaceable class="parameter">host</replaceable> or
<replaceable class="parameter">port</replaceable>
as <literal>-</literal> is equivalent to omitting that parameter.
</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.
Also, any password used for the existing connection will be re-used
only if the user, host, and port settings are not changed.
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 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, the old connection is closed
and an error is reported. That may or may not terminate the
script; if it does not, all database-accessing commands will fail
until another <literal>\connect</literal> command is successfully
executed. This distinction was chosen as
a user convenience against typos on the one hand, and a safety
mechanism that scripts are not accidentally acting on the
wrong database on the other hand.
Note that whenever a <literal>\connect</literal> command attempts
to re-use parameters, the values re-used are those of the last
successful connection, not of any failed attempts