↑↓ select ↵ open ⌫ change scope Open full search

PG.CENTER connects PostgreSQL documentation, reference, and ecosystem knowledge. Maintained by Pigsty.

Wiki / psql Commands / Connections and sessions

\c

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

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.

Client
psql 18.6
Case-sensitive spelling
\c

Usage

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

Spellings in this manual definition

CommandDocumented suffix modifiers
\cNone listed in this signature
\connectNone 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

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.