Connect PostgreSQL

Readly needs a relational database before it can persist users, books, progress, and annotations.

Task

Start PostgreSQL locally and add its connection string to Readly’s environment.

Files

Work with:

docker-compose.yml
.env
.env.example

If the starter does not already contain a database service, add PostgreSQL to the local Compose setup.

A minimal service can look like:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: readly
      POSTGRES_PASSWORD: readly
      POSTGRES_DB: readly
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Add the corresponding local connection string to .env:

DATABASE_URL="postgresql://readly:readly@localhost:5432/readly"

Keep the same variable name in .env.example, but do not commit real credentials.

Start the Service

Run:

docker compose up -d postgres

Then verify the container is running:

docker compose ps

Test

The PostgreSQL container should report a running/healthy state, and Readly should still start with:

npm run dev

Checkpoint

You are done when PostgreSQL is running locally and DATABASE_URL points Readly at it.