psql Command Reference: Flags, Usage & CI Examples

psql is the PostgreSQL interactive terminal and non-interactive SQL runner.

psql connects to a PostgreSQL server and runs SQL interactively, from a single -c command, or from a -f file. In CI it seeds databases and runs migrations against a Postgres service container.

Common flags and usage

-h <host> / -p <port>: server host and port (default 5432)
-U <user> / -d <db>: connect as a role to a database
-c "SQL": run one command and exit
-f <file>: run SQL from a file
-v ON_ERROR_STOP=1: exit non-zero on the first SQL error
PGPASSWORD env or a postgresql:// URI: supply the password non-interactively

Example

shell

PGPASSWORD=${PGPASSWORD} psql -h localhost -U postgres -d app -v ON_ERROR_STOP=1 -f schema.sql
psql "${DATABASE_URL}" -c 'SELECT 1'

In CI

Pass credentials via PGPASSWORD or a connection URI, never interactively. Add -v ON_ERROR_STOP=1 to -f scripts so a failing migration statement actually fails the step instead of exiting 0. Gate psql behind pg_isready so it does not race a half-started service container.

Key takeaways

psql runs SQL interactively, from -c, or from a -f file.
Supply the password via PGPASSWORD or a postgresql:// URI in CI.
ON_ERROR_STOP=1 makes a broken -f migration fail the pipeline.