Switching databases in psql is \c <database_name>, the shortcut for the meta-command \connect. A psql session is bound to one database at a time — there is no USE <db> SQL command in Postgres the way there is in MySQL — so the only way to move the connection to a different database is to reconnect. The reconnect is the meta-command, and the meta-command is the answer. The interesting part is the flags (-reuse-previous, the user, the host, the port), the gotchas (the connection string in the environment, the \c failure modes), and the way the same pattern works in pgAdmin, in DBeaver, and in a CI script.
The reason “psql switch database” is its own question and not just “postgresql switch database” is that the psql client is the one most developers reach for first, and the psql client is the one with the meta-command syntax. The meta-command is the right answer for an interactive session, and the meta-command is the right answer for a script that needs to run a query against a different database.
Table of contents
- The short version
- The three commands that actually move the connection
- The seven flags that decide who you connect as
- The four places a switch can fail
- The way environment variables change the default target
- The five patterns that cover 80% of real switches
- FAQ
The short version
A psql session opens with a single connection to a single database. The session is bound to that database for the lifetime of the connection. To move the session to a different database, the developer has to reconnect — there is no SQL command that changes the database mid-session. The reconnect is the meta-command \c <database_name> (or its long form \connect <database_name>). The command closes the current connection, opens a new one to the specified database, and updates the prompt. The session continues, but the binding has changed.
The three commands that actually move the connection
The \c meta-command is one command, but the three forms of the command cover the cases a developer is going to hit. The three forms are not interchangeable, and the developer should know which one they want.
\c <database_name>. Switch to a different database, using the same user, host, and port as the current connection. The form is the most common one, and the one the developer reaches for first. The form is also the one that fails most often — because the user does not have permission to connect to the target database.
\c <database_name> <user>. Switch to a different database as a different user. The form is the right answer when the developer is connected as postgres and wants to switch to the application’s database as the application user. The form prompts for the user’s password if the password is not cached.
\c <connstring>. Switch using a full PostgreSQL connection string. The form is postgresql://user:password@host:port/database?options=.... The form is the right answer when the developer is switching between two completely different database servers, or when the developer wants to set client options (sslmode, application_name, etc.) on the new connection.
The three forms cover 99% of real switches. The remaining 1% is the developer who is in a script and needs to switch programmatically — for that, the right answer is to close the current psql process and open a new one with a different connection string, not to use \c inside the script.
The seven flags that decide who you connect as
The \c meta-command accepts a small set of flags that change the behavior of the new connection. The flags are the same as the connection-string parameters, and the flags are the lever for the developer’s “I want to connect as this user, with these options” use case.
-reuse-previous=on/off. When on (the default in older versions), the new connection reuses the previous connection’s parameters for any field that is not specified. When off, the new connection resets to the connection parameters from the original psql invocation. The flag is the right answer for a developer who is switching between databases and wants to keep the same user, host, and port.
dbname, user, host, port, password. The five positional parameters. The form is \c <dbname> <user> <host> <port> <password>. The password is usually omitted (and the command prompts for it), but the form supports a cleartext password in the meta-command, which is useful in a script that has the password in an environment variable.
**-variable. A pre-3.2 psql flag. The flag is deprecated and is the wrong answer for any modern psql. The flag has been replaced by the connection-string parameters and the PGOPTIONS environment variable.
The seven flags (counting -reuse-previous as two values, dbname/user/host/port/password as five) are the floor. The developer should know which flag they want before they run the command, and the developer should not run \c with a cleartext password in a multi-user terminal.
The four places a switch can fail
A \c command that fails is a command that the developer is going to spend ten minutes debugging. The four places the command can fail are:
The target database does not exist. The \c command connects to a database. If the database does not exist, the connection fails with FATAL: database "<name>" does not exist. The fix is to verify the database name with \l (list databases) before the switch.
The user does not have permission. The \c command connects as a user. If the user does not have CONNECT permission on the target database, the connection fails with FATAL: permission denied for database "<name>". The fix is to grant the permission with GRANT CONNECT ON DATABASE <name> TO <user>, or to connect as a user that has the permission.
The host or port is wrong. The \c command uses the host and port from the original connection (unless overridden). If the developer is trying to connect to a database on a different host, the connection fails with a network error. The fix is to use the full connection-string form of \c with the right host and port.
The password is wrong. The \c command prompts for the password if the password is not cached. If the password is wrong, the connection fails with FATAL: password authentication failed for user "<name>". The fix is to use the right password, or to set the PGPASSWORD environment variable to avoid the prompt.
The four places cover the typical failures. There are also failures from the network being down, from the database server being in recovery, from the connection pool being exhausted, and from the SSL certificate being invalid — but the four are the ones the developer will see most often.
The way environment variables change the default target
The psql client reads a set of environment variables that set the default connection parameters. The variables are the lever for “I want to connect to this database without typing the host and port every time,” and the variables are the part the developer has to know to make the switch work in a script.
PGHOST. The default host. If set, psql connects to this host by default. The variable is the right answer for a developer who is always connecting to the same database server.
PGPORT. The default port. The Postgres default is 5432, but managed services usually use a different port. The variable is the right answer for a developer who is always connecting to a managed service.
PGUSER. The default user. The variable is the right answer for a developer who is always connecting as the same user.
PGDATABASE. The default database. The variable is the right answer for a developer who is always connecting to the same database. The variable is also the one that surprises developers the most — psql opens with the PGDATABASE database, and the developer has to use \c to switch.
PGPASSWORD. The password. The variable is the right answer for a script that needs to authenticate non-interactively. The variable is the wrong answer for a multi-user terminal, because the password is visible to anyone who can read the environment.
PGSSLMODE, PGSSLCERT, PGSSLKEY, PGSSLROOTCERT. The SSL parameters. The variables are the right answer for a developer who is connecting to a managed service that requires SSL.
The six variables are the floor. The developer can also use a ~/.pgpass file to store the password, or a ~/.psqlrc file to set the default options, or a service-name file in ~/.pg_service.conf to set the connection parameters by name. The variables are the most common, and the variables are the ones the developer should know first.
The five patterns that cover 80% of real switches
A short, opinionated list of patterns that show up in real Postgres work. The patterns are not the only ones, but they are the ones the developer should learn first.
The “I want to look at the application’s database as the application user” pattern. The developer is connected as postgres, the application is connected as app_user, and the developer wants to see the application’s data. The pattern is \c app_db app_user, then enter the password. The pattern is the right answer for a developer who is debugging the application’s behavior and needs to see the same data the application sees.
The “I want to run a script against a different database” pattern. The developer is in a psql -f script.sql invocation, and the script needs to run a query against a different database. The pattern is to close the current psql, then psql -d <other_db> -f script.sql. The pattern is the right answer for a script that needs to query multiple databases, and the pattern is the right answer for a CI job that needs to run migrations against a specific database.
The “I want to switch between two databases in the same session” pattern. The developer is in an interactive session, and needs to look at table A in database 1, then table B in database 2. The pattern is \c db1, run the query, \c db2, run the query, \c db1 to come back. The pattern is the right answer for a developer who is comparing schemas or data across databases.
The “I want to use a connection string to set everything” pattern. The developer has a DATABASE_URL environment variable, and wants to use it to set the connection. The pattern is \c "$DATABASE_URL", which parses the connection string and connects. The pattern is the right answer for a developer who is using a managed service that provides a connection string, and the pattern is the right answer for a developer who wants to set SSL options in the connection string.
The “I want to switch as a different user” pattern. The developer is connected as app_user, and needs to do something that requires superuser permissions (creating an extension, granting a permission, killing a long-running query). The pattern is \c <dbname> postgres, enter the postgres password, do the thing, \c <dbname> app_user to come back. The pattern is the right answer for a developer who is doing operational work that needs elevated permissions.
The five patterns are the floor. There are also patterns for switching with -reuse-previous=off to reset the connection parameters, for switching with a service=myapp parameter to use a service file, and for switching with application_name=... to set the application name on the new connection. The five are the ones the developer should learn first.
How this fits the rest of the stack
A database connection rarely lives in isolation. The connection usually opens from an application, closes when the application is done, and is managed by a connection pooler. The platform that handles the database should make the rest of the stack feel like part of the same conversation.
The services layer is the part of the platform that runs the long-lived API the database connection serves. The database layer is the part that holds the data the API reads and writes. The static layer is the part that hosts the dashboard the developer uses to see the data. The environment variables are the part that holds the connection string the API uses to connect.
A database connection on a platform where the service, the database, the storage, and the secrets are all in the same place is a connection the team is going to be able to debug. A database connection on a platform where each piece is in a different console is a connection the team is going to spend the first hour just opening the right tab.
For a team that wants to see the full cost of the project before it commits, the RunxBuild hosting calculator shows the line items together. The API, the database, the storage, the worker, the bandwidth — each one is a separate number, and the team’s mental model for the platform is the sum of those numbers.
FAQ
How do I switch databases in psql?
Use the meta-command \c <database_name> (or its long form \connect <database_name>). The command closes the current connection, opens a new one to the specified database, and updates the prompt. The session continues, but the binding has changed.
How do I switch databases as a different user in psql?
Use \c <database_name> <user>. The command prompts for the user’s password if the password is not cached. The form is the right answer when the developer is connected as postgres and wants to switch to the application’s database as the application user.
How do I switch databases using a connection string in psql?
Use \c <connstring>, where <connstring> is a full PostgreSQL connection string (postgresql://user:password@host:port/database?options=...). The form is the right answer when the developer is switching between two different database servers, or when the developer wants to set client options on the new connection.
Can I use SQL to switch databases in psql?
No. PostgreSQL does not have a USE <db> SQL command the way MySQL does. The only way to switch databases in a psql session is the \c meta-command, which closes the current connection and opens a new one. The session is bound to one database at a time.
Why is my \c command failing?
The most common causes are: the target database does not exist (FATAL: database "<name>" does not exist), the user does not have CONNECT permission on the target database (FATAL: permission denied for database "<name>"), the host or port is wrong (network error), or the password is wrong (FATAL: password authentication failed for user "<name>"). The fix is to verify each of the four before the switch.
How do I list all databases in psql?
Use the meta-command \l or \list. The command shows a table of databases on the current server, with the owner, the encoding, the collation, the ctype, and the access privileges. The command is the right answer for a developer who is looking for the right database name before the switch.
Can I switch databases in a script?
Not with the \c meta-command. The right answer is to close the current psql and open a new one with the -d flag (e.g. psql -d <other_db> -f script.sql). The pattern is the right answer for a CI job that needs to run migrations against a specific database, and the pattern is the right answer for a script that needs to query multiple databases.