Local PostgreSQL

Option A — Postgres.app (macOS, recommended)

1. Download and install Postgres.app
2. Open it and start the server
3. Open a terminal and create a database:

Configure your $PATH to use the included command line tools. Add this to ~/.zshrc file":

# Postgres.app
export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

createdb app-db-name

4. Your connection string to be updated in .env.local:

DATABASE_URL=postgres://username:password@localhost:5432/app-db-name

Option B — Docker

docker run --name betterstarter-db \
  -e POSTGRES_DB=betterstarter \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d postgres:16

Connection string:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/betterstarter

Apply Schema Locally

Once DATABASE_URL is set in .env.local:

For first-time local setup, apply current schema directly:

pnpm db:push

When pulling new migration files from the repo, apply them locally:

pnpm db:migrate

Only run pnpm db:generate when you changed schema code and want to create a new migration file.

GUI Tools

• Postgres.app + TablePlus
• pgAdmin 4
• DBeaver