How-To Guide

How to Install PostgreSQL

PostgreSQL is the most advanced open-source relational database. Here's how to install it on any OS and run your first query in under 15 minutes.

📋 What You'll Need

A computer running Windows, macOS, or Linux
About 400 MB of free disk space
Administrator access (to install software)
15 minutes of your time

✅ PostgreSQL is completely free and open source.

🐘 Why PostgreSQL?

Postgres is the database powering Instagram, Reddit, Spotify, and thousands of startups. You'll use it for:

Storing user accounts and authentication data
Backing Next.js, Node.js, Python, and Rails apps
Running complex queries with joins, aggregations, and window functions
Full-text search, JSON storage, and geospatial data

Download the Installer

Go to the official site:

👉 postgresql.org/download

;

Choose your platform:

Windows: EDB installer (interactive)
Mac: EDB installer, or Homebrew: brew install postgresql@16
Linux: Use your distro's package manager (see step 2b)

Run the Installer

Windows:

Open the downloaded .exe file
Click through the wizard — accept all defaults
Set a password for the postgres user (remember it!)
Keep the default port 5432
Uncheck "Launch Stack Builder" at the end

Mac:

Follow the EDB installer, or use Homebrew
Homebrew: brew services start postgresql@16

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

Verify Installation

Open a terminal (Command Prompt, Terminal, or bash) and run:

psql --version

You should see something like psql (PostgreSQL) 16.3.

Then connect to the default database:

psql -U postgres

Enter your password. You should see the psql prompt: postgres=#. Type \q to exit.

Create Your First Database

Connect again and create a test database:

psql -U postgres
CREATE DATABASE mytestdb;
\c mytestdb
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE
);
INSERT INTO users (name, email) VALUES ('Sarah', 'sarah@example.com');
SELECT * FROM users;

You should see one row with Sarah and her email. 🎉

💡 psql commands: \l lists databases, \dt lists tables, \d users describes the users table, \q quits.

🧠 Essential psql Commands

\l              list all databases
\c dbname       connect to a database
\dt             list tables in current database
\d tablename    show table structure
\du             list database users
\q              quit psql
\?              help on psql commands
\h              help on SQL commands

🔧 Troubleshooting

"psql: command not found"

Postgres isn't on your PATH. On Windows, restart your terminal. On macOS with Homebrew, run brew link postgresql@16. On Linux, ensure postgresql-client is installed.

"could not connect to server"

Postgres isn't running. On Windows, check Services. On macOS, run brew services start postgresql@16. On Linux, run sudo systemctl start postgresql.

Forgot the postgres password

Reset it by editing pg_hba.conf to use trust authentication temporarily, then ALTER USER postgres PASSWORD 'newpassword';