---
title: "psql — PostgreSQL Interactive Terminal"
type: entity
tags: [psql, cli, meta-commands, tooling]
updated: 2026-06-25
confidence: high
sources: [raw/web_community-postgresql-documentation-18-psql.md]
---
# psql — PostgreSQL Interactive Terminal

`psql` is a terminal-based front-end to PostgreSQL. It lets you type queries interactively, issue them to the server, and see the results; input can also come from a file or command-line arguments. It additionally provides **meta-commands** and shell-like features for scripting and administration.

## Synopsis and connecting

```
psql [option...] [dbname [username]]
```

Connection parameters can be given as options — `-d` (dbname), `-h` (host), `-p` (port), `-U` (username) — or via the environment variables `PGDATABASE`, `PGHOST`, `PGPORT`, `PGUSER`. A `~/.pgpass` file avoids retyping passwords. A connection string (`conninfo` or URI) may be used in place of a database name:

```bash
psql "service=myservice sslmode=require"
psql postgresql://dbmaster:5433/mydb?sslmode=require
```

At the prompt (`dbname=>`), input is sent to the server when a command-terminating semicolon is reached; a newline does not terminate a command, so statements may span several lines.

## Useful command-line options

- `-c command` — execute one command string, then exit.
- `-f filename` — read commands from a file (largely equivalent to `\i`).
- `-l` / `--list` — list all databases, then exit.
- `-X` / `--no-psqlrc` — skip the start-up `~/.psqlrc` file (recommended when restoring dumps).
- `-1` / `--single-transaction` — wrap all `-c`/`-f` work in one transaction.
- `-x` — expanded output; `-A` unaligned; `--csv` CSV output.

## Meta-commands

Anything beginning with an unquoted backslash is a `psql` meta-command processed by `psql` itself. Key ones:

- `\c` or `\connect [dbname [username] [host] [port] | conninfo]` — establish a new connection (reuses prior parameters in positional form).
- `\l` — list the databases in the server with names, owners, encodings, and access privileges.
- `\dt [pattern]` — list tables. (`\di` indexes, `\dv` views, `\dm` materialized views, `\ds` sequences, `\dE` foreign tables; combinable, e.g. `\dti`.)
- `\d [pattern]` — describe a relation: columns, types, indexes, constraints, rules, and triggers. `\d+` adds more detail. Without a pattern, equivalent to `\dtvmsE`.
- `\du` (alias `\dg`) — list database roles. `\drg` shows role memberships.
- `\dn` schemas, `\df` functions, `\dx` installed extensions, `\dp` access privileges.
- `\timing` — turn on/off display of how long each SQL statement takes (in milliseconds).
- `\copy table FROM 'filename' ...` / `\copy table TO 'filename' ...` — frontend (client-side) `COPY`; file accessibility and privileges are those of the local user, no SQL superuser rights required.
- `\e` / `\edit` — open the current query buffer (or a file) in your editor; on exit its contents return to the buffer.
- `\ef` / `\ev` — edit a function or view definition.
- `\i filename` — read input from a file and execute it as if typed at the keyboard.
- `\x` — toggle expanded table formatting (one column per line), useful for wide rows.
- `\g [filename | |command]` — send the current query buffer (like `;`), optionally redirecting output.
- `\watch [seconds]` — repeatedly execute the current query buffer.
- `\q` — quit.

## Scripting and exit status

`psql` returns 0 on normal completion, 1 on its own fatal error, 2 on a broken connection in a non-interactive session, and 3 when a script error occurs and `ON_ERROR_STOP` is set. Setting `ON_ERROR_STOP=on` makes scripts halt on the first SQL error rather than continuing. `\if`/`\elif`/`\else`/`\endif` provide conditional blocks.

## See also

- [[summaries/operations-and-reference-catalog]] — `psql` is the standard tool for restoring `pg_dump` text dumps.
- [[concepts/roles-and-security]] — `\du`, `\dp`, and the ACL display.