Wiki / psql Commands / Connections and sessions

\connect

Establishes a new connection to a PostgreSQL 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 conninfo connection string as detailed in Sectio…

Reading PostgreSQL 18.6.

Description

Client: psql 18.6
Case-sensitive spelling: \connect

Usage

\c or \connect [ -reuse-previous= on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ]

Spellings in this manual definition

Command	Documented suffix modifiers
\c	None listed in this signature
\connect	None listed in this signature

Manual definition

\c or \connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ]

Establishes a new connection to a PostgreSQL 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 conninfo connection string as detailed in Section 32.1.1. If no arguments are given, a new connection is made using the same parameters as before.

Specifying any of dbname, username, host or port as - is equivalent to omitting that parameter.

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 sslmode. By default, parameters are re-used in the positional syntax, but not when a conninfo string is given. Passing a first argument of -reuse-previous=on or -reuse-previous=off overrides that default. If parameters are re-used, then any parameter not explicitly specified as a positional parameter or in the conninfo string is taken from the existing connection's parameters. An exception is that if the host setting is changed from its previous value using the positional syntax, any hostaddr 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 libpq default is used.

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 psql 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 \connect 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 \connect command attempts to re-use parameters, the values re-used are those of the last successful connection, not of any failed attempts made subsequently. However, in the case of a non-interactive \connect failure, no parameters are allowed to be re-used later, since the script would likely be expecting the values from the failed \connect to be re-used.

Examples:

=> \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

Related entries

Documentation and source

18.6 English manual · app-psql.html

Source build

Version: 18.6
Build: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
Source fingerprint: ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

Compare versions

PostgreSQL 16 → 17: changed.

--- PostgreSQL 16
+++ PostgreSQL 17
@@ -1,5 +1,5 @@
 {
-  "definition": "Establishes a new connection to a PostgreSQL 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 conninfo connection string as detailed in Section 34.1.1 . If no arguments are given, a new connection is made using the same parameters as before. Specifying any of dbname , username , host or port as - is equivalent to omitting that parameter. 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 sslmode . By default, parameters are re-used in the positional syntax, but not when a conninfo string is given. Passing a first argument of -reuse-previous=on or -reuse-previous=off overrides that default. If parameters are re-used, then any parameter not explicitly specified as a positional parameter or in the conninfo string is taken from the existing connection's parameters. An exception is that if the host setting is changed from its previous value using the positional syntax, any hostaddr 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 libpq default is used. 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 psql 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 \\connect 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 \\connect command attempts to re-use parameters, the values re-used are those of the last successful connection, not of any failed attempts made subsequently. However, in the case of a non-interactive \\connect failure, no parameters are allowed to be re-used later, since the script would likely be expecting the values from the failed \\connect to be re-used. Examples: => \\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",
+  "definition": "Establishes a new connection to a PostgreSQL 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 conninfo connection string as detailed in Section 32.1.1 . If no arguments are given, a new connection is made using the same parameters as before. Specifying any of dbname , username , host or port as - is equivalent to omitting that parameter. 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 sslmode . By default, parameters are re-used in the positional syntax, but not when a conninfo string is given. Passing a first argument of -reuse-previous=on or -reuse-previous=off overrides that default. If parameters are re-used, then any parameter not explicitly specified as a positional parameter or in the conninfo string is taken from the existing connection's parameters. An exception is that if the host setting is changed from its previous value using the positional syntax, any hostaddr 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 libpq default is used. 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 psql 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 \\connect 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 \\connect command attempts to re-use parameters, the values re-used are those of the last successful connection, not of any failed attempts made subsequently. However, in the case of a non-interactive \\connect failure, no parameters are allowed to be re-used later, since the script would likely be expecting the values from the failed \\connect to be re-used. Examples: => \\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",
   "modifiers": [],
   "signature": "\\c or \\connect [ -reuse-previous= on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ]",
   "spellings": [

Compares recorded interfaces and attributes. Source fingerprints and build metadata are excluded; an absent sample is not proof of the introduction or removal release.

Related entries

Export JSON · Back to psql Commands · Recorded in PostgreSQL 10 through 20; the first sample is not necessarily its introduction.