What Is PostgreSQL? Install It and Get Started
On this page
What PostgreSQL is and what you'll set up
A running PostgreSQL server on your machine, a database called training_db, and enough psql to look around inside it. Every later lesson assumes this setup, so it's worth getting it right once.
PostgreSQL (often just "Postgres") is a free, open-source relational database. It started as the POSTGRES research project at UC Berkeley in 1986, gained SQL support in the mid-1990s and was renamed PostgreSQL in 1996. A new major version ships every year and each one is supported for five years. At the time of writing the current release is PostgreSQL 18. PostgreSQL 19 reached its first release candidate on October 15, 2026, and is planned for November 19, 2026. Everything in this course runs on 18, and the few places where 19 changes something are noted.
Three things set it apart from many databases you might already know:
- It follows the SQL standard closely, so window functions, CTEs and full outer joins all behave the way the textbook says.
- Readers and writers don't block each other. A long report doesn't stop new orders from being written. Day 24 explains how (it's called MVCC).
- You can extend it. Extensions add new data types and index types, such as PostGIS for maps or pgvector for embeddings.
Step 1: Install PostgreSQL on Linux, macOS or Windows
Pick your operating system.
# Debian / Ubuntu: installs and starts the distro's PostgreSQL version
sudo apt update
sudo apt install postgresql postgresql-contrib
# RHEL / Fedora
sudo dnf install postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql
# macOS with Homebrew
brew install postgresql@18
brew services start postgresql@18On Windows, download the installer linked from postgresql.org/download/windows. It installs the server, the command-line tools and pgAdmin, and asks you to set a password for the postgres user.
Check that the client tools work:
psql --version
# psql (PostgreSQL) 18.xIf you get "command not found", jump to the common errors at the end.
Step 2: What a PostgreSQL cluster is
The installer did more than copy files. It created a cluster. The name misleads almost everyone: a cluster isn't several servers. It's one data directory holding a set of databases, managed by one running server process. The directory is usually called PGDATA.
The packages above create it for you. If you ever build one by hand, the tool is initdb:
initdb -D /usr/local/pgsql/data -U postgres --pwpromptThat fills the empty directory with the system catalogs, three starter databases (postgres, template0 and template1) and the config files. initdb refuses to run on a directory that isn't empty, which protects you from wiping a real cluster by accident. Since PostgreSQL 18, new clusters also get data checksums turned on by default, so silent disk corruption is detected when pages are read.
You start and stop the server with your service manager, or with pg_ctl for a hand-built cluster:
sudo systemctl status postgresql # Linux packages
pg_ctl -D /usr/local/pgsql/data -l logfile start # hand-built cluster
pg_ctl -D /usr/local/pgsql/data stop -m fast # fast: roll back open work and disconnect cleanlyStep 3: Connect with psql and use meta-commands
psql is the command-line client you'll use throughout the course. On Linux, the package created an OS user called postgres that can log in without a password:
sudo -u postgres psqlOn macOS with Homebrew, your own user is the superuser, so psql postgres works. With the Windows installer, use psql -U postgres -h localhost and the password you chose.
You should see a prompt like postgres=#. Now create your course database and switch to it:
CREATE DATABASE training_db;
\c training_dbCommands that start with a backslash are meta-commands. psql handles them itself instead of sending them to the server. These are the ones you'll use every day:
| Command | What it shows |
|---|---|
\l | All databases in the cluster |
\c name | Switch to another database |
\dt | Tables in the current schema |
\d table | A table's columns, indexes and constraints |
\du | Roles (users) and what they're allowed to do |
\x | Toggle expanded output, handy for wide rows |
\timing | Show how long each query took |
\? and \h SELECT | Help for meta-commands and for SQL syntax |
\q | Quit |
Run \dt now. It reports no relations, because the database is empty. That's what you should see.
Step 4: Find postgresql.conf and pg_hba.conf
Two files in the cluster control most of what you'll change:
postgresql.confcontrols how the server behaves: memory, logging, connection limits.pg_hba.confcontrols who may connect, from where, to which database, and how they prove who they are. HBA stands for host-based authentication.
Ask the server where they are instead of guessing, because the location differs by operating system:
SHOW config_file;
SHOW hba_file;Most settings only need a reload after you edit them. A few, like shared_buffers, need a full restart.
SELECT pg_reload_conf();Each line of pg_hba.conf has the same shape: connection type, database, user, client address, and authentication method. On a learning machine you'll often see peer (trust the OS user) or even trust (no password at all). Both are fine on your laptop. Neither is acceptable on a server other people can reach. Use scram-sha-256 there.
Common installation errors and fixes
psql: command not found. The client isn't on yourPATH. On Windows, add the installer'sbinfolder. On macOS, Homebrew installs versioned formulas "keg-only", so runbrew link postgresql@18or add$(brew --prefix postgresql@18)/binto yourPATH.Connection refused. The server isn't running. It's almost never a password problem, since a bad password gives an authentication error instead. Checksystemctl status postgresqlorbrew services listfirst.role "yourname" does not exist. psql tried to log in with your OS username. Connect aspostgres, or create a role for yourself (Day 21 covers roles).Peer authentication failed. You connected as a database user that doesn't match your OS user over a local socket. Usesudo -u postgres psql, or connect with-h localhostto use password authentication.
Check yourself
One data directory with its databases, run by a single server process. Several servers working together would be replication (Day 27), not a cluster in this sense.
Whether the server is running, with systemctl status postgresql or brew services list. A wrong password produces an authentication error, not a refused connection.
Run SELECT pg_reload_conf(); as a superuser, or pg_ctl reload. Most settings, including logging ones, are picked up by every session on reload without disconnecting anyone. Only settings marked as needing a restart, such as shared_buffers, require stopping the server; pending_restart in pg_settings shows which changes are waiting.
trust lets anyone who can reach the server connect as any user with no password. On your own machine you control who can reach it; on a shared server you don't.
The server is reachable, but its client authentication file has no rule that allows your address, user and database. Add a line to pg_hba.conf for your network with a password method such as scram-sha-256, then reload. Also check that listen_addresses includes an interface your laptop can reach.