Installing PostgreSQL and Using psql

PostgreSQL ships with psql, an interactive command-line client that's the fastest way to explore and manage a database — and the tool used throughout this tutorial series.

Installing PostgreSQL

• Windows/macOS — download the installer from postgresql.org, which bundles psql, pgAdmin (a GUI), and the server itself.
• Linux (Debian/Ubuntu) — sudo apt install postgresql postgresql-contrib
• Docker (fastest way to try it without installing anything system-wide):

docker run --name my-postgres -e POSTGRES_PASSWORD=mysecret -p 5432:5432 -d postgres

Connecting with psql

psql -U postgres -h localhost

• -U postgres — connect as the postgres superuser
• -h localhost — connect to a local server (omit for the Unix socket on Linux/macOS)

You'll be prompted for the password, then dropped into an interactive prompt: postgres=#

Essential psql Commands

Command	Description
\l	List all databases
\c dbname	Connect to a different database
\dt	List tables in the current database
\d tablename	Describe a table's columns, types, and indexes
\du	List roles/users
\q	Quit psql
\?	Show all available backslash commands

A Quick Session

postgres=# \l
postgres=# CREATE DATABASE shop;
postgres=# \c shop
shop=# CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT);
shop=# \dt
shop=# \d products
shop=# \q

Common Errors & Troubleshooting

• psql: command not found — the PostgreSQL bin directory isn't on your system PATH. On Windows, add the install path (e.g. C:\Program Files\PostgreSQL\16\bin) to your environment variables; on macOS/Linux, check your package manager placed it on PATH correctly.
• Docker container exits immediately after starting — check docker logs my-postgres; a common cause is forgetting -e POSTGRES_PASSWORD=..., which the official image requires on first run.
• \d tablename shows "Did not find any relation" — you're likely connected to the wrong database, or the table is in a different schema than your search_path checks by default. Run \dt to see what actually exists in the current database first.

Key Takeaways

• psql is the standard interactive client for PostgreSQL — every SQL statement you type runs immediately against the connected database.
• Backslash commands (\l, \dt, \d) are psql-specific shortcuts, not SQL — they don't end with a semicolon.
• \d tablename is the single most useful command for quickly checking a table's structure.