playbook/antigravity-awesome-skills/skills/postgresql-cli/references/cli-options-and-variables.md

# psql CLI Options, Variables & Environment

Complete reference for psql command-line flags, configuration variables, and environment variables.

## Table of Contents

- [CLI Options](#cli-options)
- [Connection Parameters](#connection-parameters)
- [Input/Output Options](#inputoutput-options)
- [Output Format Options](#output-format-options)
- [psql Variables](#psql-variables)
- [Environment Variables](#environment-variables)
- [Configuration Files](#configuration-files)
- [Tab Completion](#tab-completion)
- [Editor Integration](#editor-integration)

---

## CLI Options

### Synopsis

```
psql [option...] [dbname [user]]
```

When `dbname` is the first non-option argument, it specifies the database. The second non-option argument specifies the user.

### General Options

| Flag | Description |
|------|-------------|
| `-a` / `--echo-all` | Print all nonempty input lines to stdout as they are read. Equivalent to `ECHO=all`. |
| `-b` / `--echo-errors` | Print failed SQL commands to stderr. Equivalent to `ECHO=errors`. |
| `-c command` / `--command=command` | Execute one or more SQL commands, then exit. Commands can be separated by semicolons. Each `-c` string is sent as a single request — multiple SQL commands within it execute in one transaction (unless explicit `BEGIN`/`COMMIT`). Cannot mix SQL and meta-commands in one `-c`. Returns 0 on success, 1 on error, 2 if connection fails. |
| `-d dbname` / `--dbname=dbname` | Database name to connect to |
| `-e` / `--echo-queries` | Copy all SQL commands sent to the server to standard output as well |
| `-E` / `--echo-hidden` | Echo hidden queries (the SQL generated by \d commands and other meta-commands) to stderr. Useful for learning how psql works internally. |
| `-f filename` / `--file=filename` | Execute commands from file, then exit. Use `-` for stdin (reads until EOF or `\q`; Readline not available). `-f` provides line-numbered error messages unlike shell redirection. |
| `-F separator` / `--field-separator=separator` | Field separator for unaligned output (default: `|`) |
| `-H` / `--html` | HTML output mode |
| `-l` / `--list` | List available databases, then exit. Connects to `postgres` database unless a different database is specified via `-d` or a non-option argument. |
| `-L filename` / `--log-file=filename` | Log all session output to file |
| `-n` / `--no-readline` | Disable enhanced command-line editing and tab completion |
| `-o filename` / `--output=filename` | Redirect all query output to file |
| `-P assignment` / `--pset=assignment` | Set printing option (format: `option=value`) |
| `-q` / `--quiet` | Quiet mode — no startup message, no informational messages |
| `-R separator` / `--record-separator=separator` | Record separator for unaligned output (default: newline) |
| `-s` / `--single-step` | Single-step mode. Confirm before each command is sent to the server. |
| `-S` / `--single-line` | Single-line mode. Newline terminates a query (as if semicolon). Not recommended — execution order can be unclear when mixing SQL and meta-commands on the same line. |
| `-t` / `--tuples-only` | Print rows only — no headers, footers |
| `-T table_options` / `--table-attr=table_options` | HTML table attributes |
| `-v assignment` / `--set=assignment` / `--variable=assignment` | Set psql variable (format: `name=value` sets, `name` unsets, `name=` sets to empty). Assignment happens at command-line processing time, so connection-state variables are overwritten later. |
| `-V` / `--version` | Print psql version and exit |
| `-w` / `--no-password` | Never issue a password prompt. Fails if password is required. Setting persists for the entire session, including `\connect` attempts. |
| `-W` / `--password` | Force password prompt. Setting persists for the entire session, including `\connect` attempts. |
| `-x` / `--expanded` | Turn on expanded table output |
| `-X` / `--no-psqlrc` | Do not read the startup file (~/.psqlrc) |
| `-z` / `--field-separator-zero` | Set field separator to NUL byte |
| `-0` / `--record-separator-zero` | Set record separator to NUL byte |
| `-1` / `--single-transaction` | Wrap `-f` or `-c` commands in a single transaction. If any command fails, all roll back. Warning: if the script itself contains `BEGIN`/`COMMIT`/`ROLLBACK`, this option will not have the expected effect. |
| `-?` / `--help[=topic]` | Show help. `topic` can be `commands` (backslash commands), `options` (CLI options, default), or `variables` (config variables). |
| `--csv` | Switch to CSV output mode. Equivalent to `\pset format csv`. |

---

## Connection Parameters

These options control how psql connects to PostgreSQL.

| Flag | Env Variable | Description |
|------|-------------|-------------|
| `-h host` | `PGHOST` | Host name or socket directory (default: local socket) |
| `-p port` | `PGPORT` | Port number (default: 5432) |
| `-U user` | `PGUSER` | Database user name |
| `-d dbname` | `PGDATABASE` | Database name |
| `-w` | — | Don't prompt for password |
| `-W` | — | Force password prompt |

**Connection URI:**
```
psql postgresql://user:password@host:5432/dbname?sslmode=require
psql postgresql:///dbname?host=/var/run/postgresql
```

**Service lookup:** If `PGSERVICE` or `service=name` in connection string is set, psql reads connection parameters from `pg_service.conf`.

---

## Input/Output Options

| Flag | Description |
|------|-------------|
| `-c command` | Execute command(s) then exit. Multiple commands separated by `;`. |
| `-f filename` | Read commands from file then exit. Use `-` for stdin. |
| `-1` | Run in a single transaction (only effective with `-c` or `-f`) |
| `-a` | Echo all input lines to stdout |
| `-b` | Echo failed SQL to stderr |
| `-e` | Echo queries to stdout |
| `-E` | Echo hidden queries (\d internals) to stderr |
| `-L file` | Log all output to file |
| `-o file` | Redirect output to file |
| `-n` | Disable readline |

**Common patterns:**
```bash
# Run a migration in a transaction
psql -1 -f migration.sql mydb

# Execute a single query
psql -c "SELECT count(*) FROM users" mydb

# Pass a variable from the command line
psql -v table=users -c 'SELECT count(*) FROM :"table"' mydb

# Batch process with for-loop
for f in /tmp/*.sql; do psql -1 -f "$f" mydb; done

# Echo internal queries to learn psql
psql -E mydb -c "\d+ users"
```

---

## Output Format Options

| Flag | Description |
|------|-------------|
| `-A` / `--no-align` | Unaligned (delimiter-separated) output |
| `-F sep` | Field separator (default: `|`) |
| `-H` / `--html` | HTML table output |
| `-P opt=val` | Set pset option (e.g., `-P pager=off`) |
| `-R sep` | Record separator (default: newline) |
| `-t` | Tuples only (no headers/footers) |
| `-T attrs` | HTML table attributes |
| `-x` | Expanded display |
| `-z` / `-0` | NUL separators |

**Script-friendly output pattern:**
```bash
# CSV output
psql --csv -c "SELECT id, name FROM users" mydb

# Custom delimiter output
psql -A -F ',' -t -c "SELECT id, name FROM users" mydb

# NUL-separated for xargs -0
psql -A -z -t -c "SELECT filename FROM files_to_process" mydb | xargs -0 process

# JSON-friendly (one value per line)
psql -A -t -c "SELECT json_agg(row_to_json(t)) FROM (SELECT id, name FROM users) t" mydb
```

---

## psql Variables

psql maintains internal variables that control behavior. Set with `\set`, unset with `\unset`, view all with `\set` (no arguments).

### Automatic Variables

| Variable | Description |
|----------|-------------|
| `AUTOCOMMIT` | `on` (default) or `off`. When off, psql auto-issues implicit `BEGIN` before any command not in a transaction block (except `BEGIN`/`VACUUM` etc.). You must explicitly `COMMIT` or `ROLLBACK`. |
| `COMP_KEYWORD_CASE` | `lower`, `upper`, `preserve-lower` (default), `preserve-upper`. Controls tab-completion keyword casing. `preserve-lower`/`preserve-upper` preserves case of already-typed input; empty input completes as lower/upper case. |
| `DBNAME` | Current database name. Set automatically on connect. |
| `ECHO` | `none` (default), `all`, `queries`, `errors`. Controls what gets echoed. `all` echoes all commands (including scripts). `queries` echoes only SQL queries, not meta-commands. `errors` echoes failed SQL commands to stderr (set by `-b`). |
| `ECHO_HIDDEN` | `off`, `on`, `noexec`. When `on`, shows hidden queries (SQL behind \d commands). `noexec` shows them without executing. |
| `ENCODING` | Current client encoding. Set automatically. |
| `ERROR` | `true` if the last query failed, `false` otherwise. |
| `FETCH_COUNT` | Integer (default: 0). When set, psql fetches rows in batches of this size instead of all at once. Useful for large result sets. |
| `HIDE_TABLEAM` | If set, hide table access methods in `\d+` output. |
| `HIDE_TOAST_COMPRESSION` | If set, hide compression method in `\d+` output. |
| `HISTCONTROL` | `none` (default), `ignorespace`, `ignoredups`, `ignoreboth`. Controls history saving. |
| `HISTFILE` | Path to history file (default: `~/.psql_history`). Can include psql variable references, e.g. `\set HISTFILE ~/.psql_history-:DBNAME`. |
| `HISTSIZE` | Maximum number of history entries (default: 500). A negative value disables the limit. |
| `HOST` | Current server host. Set automatically on connect. |
| `IGNOREEOF` | If set, prevents Ctrl-D from exiting. Value is the number of EOFs to ignore before quitting. |
| `LAST_ERROR_MESSAGE` | Error message from the last failed query. |
| `LAST_ERROR_SQLSTATE` | SQLSTATE error code from the last failed query (`00000` if no error). |
| `LASTOID` | OID of the last affected row by `INSERT` or `\lo_import`. Always 0 for PG 12+ tables (OID column removed). |
| `ON_ERROR_ROLLBACK` | `off` (default), `on`, `interactive`. When `on`, errors inside a transaction create savepoints automatically, allowing continued execution. `interactive` only activates in interactive sessions, not when reading scripts. |
| `ON_ERROR_STOP` | `off` (default) or `on`. When `on`, a query error or meta-command error stops script execution and exits. Critical for safe scripting. |
| `PIPELINE_COMMAND_COUNT` | Number of queued commands in current pipeline. |
| `PIPELINE_RESULT_COUNT` | Number of commands with pending results in current pipeline. |
| `PIPELINE_SYNC_COUNT` | Number of queued sync messages in current pipeline. |
| `PORT` | Current server port. Set automatically on connect. |
| `PROMPT1`, `PROMPT2`, `PROMPT3` | Prompt format strings (see below). |
| `QUIET` | `on` or `off`. Quiet mode. |
| `ROW_COUNT` | Number of rows affected by the last query. |
| `SERVER_VERSION_NAME` | Server version string. |
| `SERVER_VERSION_NUM` | Server version as integer (e.g., 160000 for 16.0). |
| `SERVICE` | Service name from the connection, if applicable. |
| `SHELL_ERROR` | `true` if the last shell command (`\!`, `\g`, `\o`, `\w`, `\copy`, backquote) failed, `false` otherwise. |
| `SHELL_EXIT_CODE` | Exit code of the last shell command (0-127 normal exit, 128-255 signal termination, -1 launch failure). |
| `SHOW_ALL_RESULTS` | `on` (default) or `off`. When on, show all results from combined queries. |
| `SHOW_CONTEXT` | `never`, `errors`, `always`. Controls display of `CONTEXT:` in messages. Default: `errors`. |
| `SINGLELINE` | `on` or `off`. Newline acts as query terminator. |
| `SINGLESTEP` | `on` or `off`. Confirm before each command. |
| `SQLSTATE` | SQLSTATE error code from the last query. |
| `USER` | Current database user. Set automatically on connect. |
| `VERSION` | psql client full version string. |
| `VERSION_NAME` | psql client short version (e.g., `18beta1`). |
| `VERSION_NUM` | psql client version as integer (e.g., `180000`). |
| `WATCH_INTERVAL` | Default interval (seconds) for `\watch` command (default: 2). |
| `VERBOSITY` | `default`, `verbose`, `terse`, `sqlstate`. Controls error message detail level. |

### SQL Interpolation

psql variables can be interpolated into SQL statements using colon-prefixed syntax. This is **plain text substitution**, not parameterized queries — understand the differences to use it safely.

| Syntax | Behavior | Example |
|--------|----------|---------|
| `:varname` | Unquoted substitution. The variable's value replaces `:varname` literally, which can break SQL syntax or enable injection if the value contains special characters. | `\set table users` → `SELECT * FROM :table;` → `SELECT * FROM users;` |
| `:'varname'` | Single-quoted string substitution. The value is placed inside single quotes, with any embedded single quotes and backslashes escaped. This is the safest form for values. | `\set name O'Brien` → `SELECT * FROM users WHERE name = :'name';` → `SELECT * FROM users WHERE name = 'O''Brien';` |
| `:"varname"` | Double-quoted identifier substitution. The value is placed inside double quotes, with embedded double quotes doubled. Use this for table/column names. | `\set col first name` → `SELECT :"col" FROM users;` → `SELECT "first name" FROM users;` |
| `:{?varname}` | Variable existence test. Always expands — `TRUE` if defined, `FALSE` otherwise. Designed for use in `\if` conditions. | `\if :{?myvar}` → true if `myvar` was set |
| `\:varname` | Escaped colon. The colon is not treated as a variable reference — `:varname` is passed through literally. | `SELECT \:not_a_var FROM t;` → `SELECT :not_a_var FROM t;` |

Note: Variable interpolation does NOT occur inside quoted SQL literals or identifiers. Therefore `':foo'` does not produce a quoted string from the variable (and wouldn't be safe even if it did — it can't handle embedded quotes properly). Use `:'foo'` instead.

**Safety guidance**: Always prefer `:'varname'` (quoted string) over `:varname` (unquoted) when substituting user-provided values. Unquoted substitution can break SQL syntax or enable injection. For the safest programmatic parameter passing, use `\bind` with the extended query protocol (which provides true parameterized queries).

### Key Variables for Scripting

**ON_ERROR_STOP** — The most important variable for scripts. Set it in scripts to ensure they abort on the first error instead of continuing:

```
-- At the top of any script:
\set ON_ERROR_STOP on

-- Now any error stops execution
INSERT INTO users (id) VALUES (1);
INSERT INTO users (id) VALUES ('bad');  -- aborts here
INSERT INTO users (id) VALUES (2);      -- never reached
```

**AUTOCOMMIT** — Turn off to manually manage transactions:

```
\set AUTOCOMMIT off
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;
\set AUTOCOMMIT on
```

**FETCH_COUNT** — For very large result sets that would consume too much memory:

```
\set FETCH_COUNT 1000
SELECT * FROM huge_table;
```

**ERROR / SQLSTATE / LAST_ERROR_MESSAGE** — For conditional logic:

```
INSERT INTO unique_table (id) VALUES (1);
\if :ERROR
  \echo 'Insert failed: ' :LAST_ERROR_MESSAGE
\else
  \echo 'Insert succeeded, rows affected: ' :ROW_COUNT
\endif
```

### Prompt Customization

`PROMPT1` is the normal prompt (default: `'%/%R%x%# '`). `PROMPT2` appears when a command is incomplete (continuation) (default: `'%/%R%x%# '`). `PROMPT3` appears during `COPY FROM STDIN` when row values are needed (default: `'>> '`).

**Format specifiers:**

| Spec | Output |
|------|--------|
| `%/` | Current database name |
| `%~` | Like `%/` but `~` if the database is your default database |
| `%m` | Host name (truncated at first dot), or `[local]` for Unix sockets |
| `%M` | Full host name, `[local:/dir/name]` for non-default Unix sockets |
| `%>` | Port number |
| `%n` | User name |
| `%s` | Service name (from connection) |
| `%#` | `#` if superuser, `>` otherwise |
| `%p` | Process ID of the server backend |
| `%R` | PROMPT1: `=` normally, `^` in single-line mode, `@` if conditional stack inactive (e.g., inside skipped `\if`), `!` if not connected. PROMPT2: `-` (continuation), `*` (comment), `'` (single-quoted), `"` (double-quoted), `$` (dollar-quoted), `(` (parenthesized). PROMPT3: empty. |
| `%w` | Whitespace matching the visible width of the last PROMPT1 output (for aligning PROMPT2) |
| `%x` | Transaction status: empty (idle), `*` (in transaction block), `!` (failed transaction), `?` (unknown or no connection) |
| `%l` | Line number inside the current statement, starting from 1 |
| `%P` | Pipeline status: `on` (pipeline mode active), `off` (not in pipeline mode), `abort` (pipeline aborted) |
| `%%` | Literal `%` |
| `%` digits | Character with the given octal code (e.g., `%033` = ESC character) |
| `%:varname:` | Value of psql variable |
| `` %`[command]` `` | Output of shell command (trailing newline stripped) |
| `%[ ... %]` | Tell Readline that the contained text is invisible (for ANSI escape codes) |

**Common prompt configurations:**
```
-- Show database and user
\set PROMPT1 '%n@%m %/%R%# '

-- Show transaction status
\set PROMPT1 '%/%x%# '

-- Production-safe prompt (color-coded)
-- Note: %033 is octal for ESC character; %[...%] tells Readline these chars are invisible
\set PROMPT1 '%[%033[1;31m%]%/%[%033[0m%]%R%# '
```

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PGDATABASE` | Default database name |
| `PGHOST` | Default host (or socket directory) |
| `PGPORT` | Default port (5432) |
| `PGUSER` | Default user |
| `PGPASSWORD` | Password (not recommended — use `~/.pgpass` instead) |
| `PGPASSFILE` | Path to password file (default: `~/.pgpass`) |
| `PGSERVICE` | Service name from `pg_service.conf` |
| `PGSERVICEFILE` | Path to service file |
| `PGOPTIONS` | Default options to pass to the server |
| `PGSSLMODE` | SSL mode (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`) |
| `PGREQUIRESSL` | Legacy SSL flag (use `PGSSLMODE` instead) |
| `PGSSLCERT` | Client certificate path |
| `PGSSLKEY` | Client key path |
| `PGSSLROOTCERT` | Root certificate path |
| `PGSSLCRL` | Certificate revocation list path |
| `PGREQUIREPEER` | Require peer username for Unix socket connections |
| `PGKRBSRVNAME` | Kerberos service name |
| `PGGSSLIB` | GSS library to use |
| `PGCONNECT_TIMEOUT` | Connection timeout in seconds |
| `PGCLIENTENCODING` | Client encoding (overrides auto-detected locale setting) |
| `PGDATESTYLE` | Date display format |
| `PGTZ` | Time zone |
| `PGSYSCONFDIR` | System config directory |
| `PG_COLOR` | Color output (`auto`, `always`, `never`) |
| `COLUMNS` | When `\pset columns` is 0, controls `wrapped` format width and the threshold for activating pager or switching to expanded auto mode |
| `PSQL_EDITOR` | Editor for `\e`, `\ef`, `\ev`. Takes precedence over `EDITOR` and `VISUAL`. |
| `PSQL_EDITOR_LINENUMBER_ARG` | Command-line argument for passing line numbers to the editor (default: `+`). E.g., set to `--line ` for editors that use `--line N` syntax. |
| `PSQL_HISTORY` | Alternative history file path (overrides `HISTFILE`) |
| `PSQLRC` | Alternative `.psqlrc` location |
| `PSQL_PAGER` | Pager command (overrides `PAGER`) |
| `PSQL_WATCH_PAGER` | Pager command specifically for `\watch` output (overrides `PSQL_PAGER` and `PAGER` when set). Unix only. |
| `EDITOR` / `VISUAL` | Editor for `\e`, `\ef`, `\ev` (checked after `PSQL_EDITOR`) |
| `SHELL` | Shell for `\!` |
| `TMPDIR` | Temp directory for temp files |
| `LANG` | Locale (affects sorting, number formatting) |

### The ~/.pgpass File

Store passwords securely instead of using `PGPASSWORD`:

```
# Format: hostname:port:database:username:password
# Use * as wildcard
localhost:5432:mydb:myuser:YOUR_PASSWORD
*:5432:*:admin:YOUR_PASSWORD
```

Permissions must be 0600: `chmod 600 ~/.pgpass`

---

## Configuration Files

### ~/.psqlrc

Executed on every interactive psql startup (unless `-X` is used). Perfect for personal customizations:

```sql
-- ~/.psqlrc example
\set ON_ERROR_STOP on
\timing on
\pset null '(null)'

-- Custom prompt showing database and transaction status
\set PROMPT1 '%n@%m %/%x%# '

-- Shortcuts
\set HISTSIZE 10000
\set HISTCONTROL ignoredups

-- Show how long queries took
\echo 'Welcome to' :DBNAME
```

### Version-specific psqlrc

Append `-` and the version number for version-specific configuration. psql reads the most specific match:

- `~/.psqlrc-18` — applies for psql 18.x
- `~/.psqlrc-18.3` — applies specifically for psql 18.3
- System-level: `psqlrc-18` in the `pg_config --sysconfdir` directory

### System-wide psqlrc

System-level psql configuration at `pg_config --sysconfdir`/psqlrc (use `PGSYSCONFDIR` to override). Applied before user `~/.psqlrc`.

### Windows paths

On Windows, user config is at `%APPDATA%\postgresql\psqlrc.conf` and history at `%APPDATA%\postgresql\psql_history`.

---

## Tab Completion

psql provides intelligent tab completion for:
- SQL keywords
- Table, view, and column names
- Function names and arguments
- Schema-qualified names
- `\d` command patterns

Tab completion sends queries to the server to fetch metadata. This can interfere with operations: e.g., after `BEGIN`, a tab completion query means `SET TRANSACTION ISOLATION LEVEL` is too late.

To disable tab completion permanently, add to `~/.inputrc`:
```
$if psql
set disable-completion on
$endif
```

Or use `-n` to disable for a single session.

---

## Editor Integration

`\e`, `\ef`, and `\ev` use the editor specified by:
1. `PSQL_EDITOR` environment variable (highest priority)
2. `EDITOR` environment variable
3. `VISUAL` environment variable
4. Default: `vi` (Unix), `notepad.exe` (Windows)

Use `PSQL_EDITOR_LINENUMBER_ARG` to control how line numbers are passed (default: `+`).

**Useful editor settings:**
```bash
export EDITOR='vim'
# or for VS Code:
export EDITOR='code --wait'
# or for nano:
export EDITOR='nano'
```