Home Explore Blog CI



postgresql

14th chunk of `doc/src/sgml/ref/psql-ref.sgml`
98b2465ff6619581a688357b47adb75e90711fd1d7222cb50000000100000fa6
   <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

Title: psql Meta-Command: \connect (\c)
Summary
The \connect (or \c) meta-command in psql establishes a new connection to a PostgreSQL server. It allows specifying connection parameters either positionally (database name, user, host, port) or via a connection string. It can reuse parameters from the previous connection, with options to enable or disable this behavior. If the connection fails in interactive mode, the previous connection is kept; in non-interactive mode, the old connection is closed and an error is reported.