Skip to main content

Installation

Learning Focus

Use this lesson to understand Installation with practical steps and examples for every major platform.

Docker provides the most repeatable and isolated environment for learning. You can destroy and recreate it in seconds.

Quick Start​

docker run --name pg-lab \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d postgres:16

Connect​

psql -h localhost -U postgres -d postgres

With Persistent Storage​

docker run --name pg-lab \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pg_lab \
  -p 5432:5432 \
  -v pg_data:/var/lib/postgresql/data \
  -d postgres:16

Docker Compose (For Richer Setups)​

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    container_name: pg-lab
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: pg_lab
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data

volumes:
  pg_data:
docker compose up -d

Windows Installation​

  1. Download the installer:

  2. Run the installer:

    • Select components: PostgreSQL Server, pgAdmin 4, Command Line Tools
    • Set installation directory (default: C:\Program Files\PostgreSQL\16)
    • Set data directory
    • Set superuser (postgres) password
    • Default port: 5432
    • Default locale: your system locale

  3. Verify installation:

    psql --version
    • Should return: psql (PostgreSQL) 16.x

  4. Connect:

    psql -U postgres

Method 2: Chocolatey (Package Manager)​

choco install postgresql16

Method 3: Scoop​

scoop install postgresql

macOS Installation​

  1. Install Homebrew (if not installed):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install PostgreSQL:

    brew install postgresql@16

  3. Start PostgreSQL service:

    brew services start postgresql@16

  4. Verify:

    psql --version
    psql -U $(whoami) -d postgres

Method 2: Postgres.app (GUI-Based)​

  1. Download from https://postgresapp.com/

  2. Drag to Applications folder

  3. Click "Initialize" to create a default cluster

  4. Add CLI tools to PATH:

    echo 'export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc

Linux Installation​

Ubuntu/Debian​

  1. Add the official PostgreSQL APT repository (for latest version):

    sudo apt install -y postgresql-common
    sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

  2. Install PostgreSQL:

    sudo apt update
    sudo apt install -y postgresql-16 postgresql-client-16

  3. Check status:

    sudo systemctl status postgresql

  4. Connect:

    sudo -u postgres psql

CentOS / RHEL / Rocky Linux​

  1. Add PostgreSQL repository:

    sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

  2. Disable built-in PostgreSQL module:

    sudo dnf -qy module disable postgresql

  3. Install PostgreSQL:

    sudo dnf install -y postgresql16-server postgresql16

  4. Initialize and start:

    sudo /usr/pgsql-16/bin/postgresql-16-setup initdb
    sudo systemctl start postgresql-16
    sudo systemctl enable postgresql-16

  5. Connect:

    sudo -u postgres psql

Arch Linux​

sudo pacman -S postgresql
sudo -u postgres initdb -D /var/lib/postgres/data
sudo systemctl start postgresql
sudo systemctl enable postgresql

Post-Installation Setup for All Systems​

  1. Connect to PostgreSQL:

    sudo -u postgres psql    # Linux
    psql -U postgres          # Docker / Windows / macOS

  2. Set or change the postgres password:

    ALTER USER postgres WITH PASSWORD 'NewSecurePassword123!';

  3. Create a lab database:

    CREATE DATABASE pg_lab;
    \c pg_lab
    SELECT version();

  4. Create a test table and insert data:

    CREATE TABLE users (
      id   bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
      name text NOT NULL
    );

    INSERT INTO users (name) VALUES ('Test User');
    SELECT * FROM users;

Installing Client Tools​

pgAdmin 4 (Official GUI)​

Windows/macOS:

Linux (Ubuntu/Debian):

curl -fsS https://www.pgadmin.org/static/packages_pgdg/pgadmin4.pub | sudo gpg --dearmor -o /usr/share/keyrings/pgadmin4.gpg
echo "deb [signed-by=/usr/share/keyrings/pgadmin4.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/$(lsb_release -cs) pgadmin4 main" | sudo tee /etc/apt/sources.list.d/pgadmin4.list
sudo apt update
sudo apt install -y pgadmin4-desktop

DBeaver (Universal Database Tool)​

# Ubuntu/Debian
sudo snap install dbeaver-ce

# macOS
brew install --cask dbeaver-community

DataGrip (JetBrains IDE)​

Common Installation Issues​

Windows:

  • psql: could not connect to server: Connection refused
    • Check that the PostgreSQL service is running (Services → postgresql-x64-16)

macOS:

  • command not found: psql
    • Add to PATH: echo 'export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"' >> ~/.zshrc

Linux:

  • psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed
    • Check that the service is running: sudo systemctl status postgresql
    • Verify the socket directory exists: ls /var/run/postgresql/

Docker:

  • connection refused when connecting to localhost:5432
    • Ensure you published the port: -p 5432:5432
    • Wait a few seconds after starting the container

Configuration Files Location​

OSData DirectoryMain Config
Ubuntu/Debian/var/lib/postgresql/16/main//etc/postgresql/16/main/postgresql.conf
CentOS/RHEL/var/lib/pgsql/16/data//var/lib/pgsql/16/data/postgresql.conf
macOS (Homebrew)/opt/homebrew/var/postgresql@16/Same directory
WindowsC:\Program Files\PostgreSQL\16\data\Same directory
Docker/var/lib/postgresql/data/Same directory

Uninstallation Guides​

Windows:

  1. Control Panel → Uninstall Programs → PostgreSQL 16
  2. Delete data directory: C:\Program Files\PostgreSQL\16

macOS:

brew services stop postgresql@16
brew uninstall postgresql@16
rm -rf /opt/homebrew/var/postgresql@16

Ubuntu/Debian:

sudo apt purge postgresql-16 postgresql-client-16
sudo rm -rf /etc/postgresql /var/lib/postgresql

Docker:

docker stop pg-lab && docker rm pg-lab
docker volume rm pg_data  # if using named volume

Next Steps After Installation​

  1. Create a non-superuser role:

    CREATE ROLE app_user LOGIN PASSWORD 'SecurePass123!';
    GRANT CONNECT ON DATABASE pg_lab TO app_user;
    GRANT USAGE ON SCHEMA public TO app_user;
    GRANT ALL ON ALL TABLES IN SCHEMA public TO app_user;

  2. Test remote connection (if needed):

    # Edit pg_hba.conf to allow remote connections
    # Add: host all all 0.0.0.0/0 scram-sha-256
    # Then reload:
    sudo systemctl reload postgresql

  3. Configure firewall:

    sudo ufw allow 5432/tcp  # Linux

Version Check & Updates​

Check installed version:

SELECT version();

Or from the command line:

psql --version
pg_config --version

Update PostgreSQL (Ubuntu example):

sudo apt update && sudo apt upgrade postgresql-16

You're now ready to start working with PostgreSQL!

Concept Map​

flowchart LR
    A[Choose Platform] --> B[Install PostgreSQL]
    B --> C[Start Service]
    C --> D[Connect with psql]
    D --> E[Create Lab Database]
    E --> F[Create Test Tables]

Common Pitfalls​

PitfallConsequencePrevention
Not installing postgresql-client separatelyCan't connect from other machinesInstall postgresql-client-16 for remote psql access
Forgetting Docker port mappingconnection refused on localhostAlways use -p 5432:5432
Using default postgres superuser for applicationsHigh blast radius on mistakesCreate dedicated roles with least privilege
Not securing the default installationOpen to local connectionsRun through pg_hba.conf settings and set strong passwords

Quick Reference​

# Check client and server availability
psql --version
sudo systemctl status postgresql   # Linux
brew services list                  # macOS

# Connect to PostgreSQL
sudo -u postgres psql               # Linux (peer auth)
psql -h localhost -U postgres        # Docker / password auth

What's Next​