Catalog My learning Blog
PostgreSQL Course: Beginner to Production in 30 Days · Phase 1 · Lesson 1 · 6 min read

What Is PostgreSQL? Install It and Get Started

On this page
  1. What PostgreSQL is and what you'll set up
  2. Step 1: Install PostgreSQL on Linux, macOS or Windows
  3. Step 2: What a PostgreSQL cluster is
  4. Step 3: Connect with psql and use meta-commands
  5. Step 4: Find postgresql.conf and pg_hba.conf
  6. Common installation errors and fixes
  7. Check yourself

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.

Shell
# 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@18

On 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:

Shell
psql --version
# psql (PostgreSQL) 18.x

If 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:

Code
initdb -D /usr/local/pgsql/data -U postgres --pwprompt

That 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:

Shell
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 cleanly

Step 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:

Shell
sudo -u postgres psql

On 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:

SQL
CREATE DATABASE training_db;
\c training_db

Commands 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:

CommandWhat it shows
\lAll databases in the cluster
\c nameSwitch to another database
\dtTables in the current schema
\d tableA table's columns, indexes and constraints
\duRoles (users) and what they're allowed to do
\xToggle expanded output, handy for wide rows
\timingShow how long each query took
\? and \h SELECTHelp for meta-commands and for SQL syntax
\qQuit

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.conf controls how the server behaves: memory, logging, connection limits.
  • pg_hba.conf controls 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:

Code
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.

Code
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 your PATH. On Windows, add the installer's bin folder. On macOS, Homebrew installs versioned formulas "keg-only", so run brew link postgresql@18 or add $(brew --prefix postgresql@18)/bin to your PATH.
  • Connection refused. The server isn't running. It's almost never a password problem, since a bad password gives an authentication error instead. Check systemctl status postgresql or brew services list first.
  • role "yourname" does not exist. psql tried to log in with your OS username. Connect as postgres, 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. Use sudo -u postgres psql, or connect with -h localhost to 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.