Local PostgreSQL Setup with Docker

This guide explains how to set up a local PostgreSQL database server using Docker Desktop. This is useful for developing and testing applications locally without relying on a cloud-based Supabase instance, or for general database work.

Prerequisites

Docker Desktop Installed: Ensure you have Docker Desktop installed and running on your system. You can download it from the official Docker website.
For Windows users, ensure you have WSL 2 (Windows Subsystem for Linux 2) enabled and set as the default backend for Docker Desktop for optimal performance.

Setup Instructions (macOS & Windows)

The following commands are generally the same for both macOS and Windows when using Docker Desktop.

1. Pull the Official PostgreSQL Image

Open your terminal (Terminal on macOS, PowerShell or Command Prompt on Windows) and run the following command to download the latest official PostgreSQL image from Docker Hub:

docker pull postgres

2. Run the PostgreSQL Container

Execute the command below to start a new PostgreSQL container. This command will:

Name the container local-postgres for easy reference.
Set the default superuser (postgres) password to mysecretpassword. You should change this to a strong, unique password.
Map port 5432 on your host machine to port 5432 in the container (the default PostgreSQL port).
Run the container in detached mode (-d), meaning it runs in the background.

docker run --name local-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres

Important!

Replace mysecretpassword with a secure password of your choice. Remember this password as you'll need it to connect.

3. Connect to Your Local PostgreSQL Instance

You can now connect to your local PostgreSQL server using any database management tool like pgAdmin, DBeaver, TablePlus, or via `psql` if you have PostgreSQL client tools installed.

Connection Details:

Host: localhost (or 127.0.0.1)
Port: 5432
Database Name: postgres (this is the default database; you can create others)
User: postgres
Password: The password you set in the `docker run` command (e.g., mysecretpassword).

Managing Your Container

Stop the Container

To stop your PostgreSQL container without removing it:

docker stop local-postgres

Start the Container

To start an existing, stopped container:

docker start local-postgres

View Container Logs

To see the logs from your PostgreSQL container (useful for troubleshooting):

docker logs local-postgres

Remove the Container

If you want to completely remove the container (this will delete all data within it unless you've set up persistent storage):

docker stop local-postgres && docker rm local-postgres

Data Persistence (Important Note)

The docker run command used above does not configure persistent storage. This means if you remove the container (e.g., with docker rm local-postgres), all data, including your databases and tables, will be deleted.

For development and testing where data loss is acceptable, this setup is fine. However, if you need your data to persist even if the container is removed or recreated, you should use Docker Volumes.

To run the container with a named volume for data persistence, you would modify the run command like this:

docker run --name local-postgres-persistent -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -v postgres_data:/var/lib/postgresql/data -d postgres

In this command, -v postgres_data:/var/lib/postgresql/data creates a named volume called postgres_data (or uses an existing one) and mounts it to the directory where PostgreSQL stores its data inside the container. This volume will persist even if you remove the container. You can manage volumes using commands like docker volume ls and docker volume rm postgres_data.

Further Learning

For more advanced Docker concepts, don't forget to just ask your AI coding tool (Cursor, Claude Code, etc.)! Topics like volumes, networking, and Docker Compose are all great ones to ask about. Or, please refer to the official Docker documentation.

Alternative: Supabase Local Development

Run a full Supabase stack locally using the Supabase CLI.

1. Install the Supabase CLI

npm install -g supabase

Or with Homebrew on macOS: brew install supabase/tap/supabase

2. Initialise a Supabase project

supabase init

3. Start local Supabase services

This spins up a local Postgres database, Auth, Storage, and more — all running in Docker containers.

supabase start

After starting, the CLI will display local URLs and keys you can use in your .env file for development.

4. Stop local services

supabase stop

Connecting from Your App

Use these connection strings in your application code or .env file.

Standard PostgreSQL Connection String

Replace the values with your actual credentials from the Docker setup above.

postgresql://postgres:mysecretpassword@localhost:5432/postgres

Environment Variable Example

Add this to your .env file:

DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/postgres"

Supabase Local Connection

When using supabase start, the CLI will output the local URLs and anon key. Use those values in your .env:

VITE_SUPABASE_URL=http://localhost:54321
VITE_SUPABASE_ANON_KEY=<your-local-anon-key>