Local PostgreSQL

PostgreSQL is now the recommended local path because the shared Prisma schema and committed migration history in this repo target PostgreSQL. This page shows the simplest ways to do that: a native local install, a local Docker container, or a hosted development database.

When to choose PostgreSQL locally

Choose this	When it makes sense	Use SQLite only when
Native local PostgreSQL	You want the easiest laptop-friendly setup without Docker	You are doing throwaway local prototyping and will not reuse that SQLite state later
Docker PostgreSQL	You want a disposable local server with minimal machine-wide setup	You do not want Docker running locally
Hosted PostgreSQL for dev	Your team shares one development database or you work across multiple machines	You want isolated disposable local state and accept that it is a separate lane

Warning

SQLite is no longer the shared default migration lane. If you keep a local SQLite setup, treat it as disposable and separate from the committed PostgreSQL migration history.

Option 1: Native local PostgreSQL apps and installers

If you do not want Docker, use one of the normal native PostgreSQL distributions. These are often the easiest path for beginners because they install the actual database server, create a local service, and usually ship with simple admin tools.

Option	Best for	Docs
Postgres.app	macOS users who want the quickest native local server	Postgres.app
EDB Interactive Installer	Windows, macOS, or Linux users who want the official guided installer flow	EDB PostgreSQL downloads
pgAdmin	People who want a GUI to inspect and manage a local or remote PostgreSQL server	pgAdmin downloads

Note

pgAdmin is a management UI, not the PostgreSQL server itself. Pair it with Postgres.app, the EDB installer, Docker, or any other running PostgreSQL instance.

Native install workflow

Install PostgreSQL locally

Use Postgres.app on macOS, the EDB Interactive Installer, or another standard PostgreSQL package for your OS. Make sure you end up with a running local PostgreSQL service.

Create a local database and credentials

Create a database such as saasybase_dev and a local user/password you are comfortable using for development. If your installer created a default postgres superuser, you can start with that and tighten it later.

Set DATABASE_URL

Point .env.local at that local PostgreSQL instance.

DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/saasybase_dev?schema=public"

Verify, migrate, and seed

Confirm Prisma resolves the intended PostgreSQL instance, then apply the baseline migration history and seed the app.

npm run prisma:diagnose-provider
npm run prisma:deploy
npx prisma db seed
npm run dev

Helpful GUI tools

If you prefer not to create databases from the command line, use a GUI:

pgAdmin works well for creating databases, checking tables, and verifying that Prisma actually created the schema you expected.
Prisma Studio is still the easiest app-specific data browser once migrations are applied: run npm run prisma:studio.

Option 2: Docker PostgreSQL

This is the best choice when you want local PostgreSQL without installing the database globally on your machine.

Official reference: PostgreSQL Docker image.

Docker setup steps

Start the PostgreSQL Container

Run the official PostgreSQL image as a background daemon, exposing port 5432 to your host machine.

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

Configure Environment Variable

Update your .env.local file to point to the newly running local database. Prisma and the app share this connection string.

DATABASE_URL="postgresql://saasybase:saasybase@localhost:5432/saasybase_dev?schema=public"

Verify Provider, Initialize Schema, and Seed

Confirm Prisma resolves the correct PostgreSQL target, then apply the existing migration history, seed the baseline data, and start the development server.

npm run prisma:diagnose-provider
npm run prisma:deploy
npx prisma db seed
npm run dev

Warning

The sample password saasybase is only for disposable local development. Change it for any shared, staged, or internet-reachable database.

Note

Prisma reads DATABASE_URL through prisma.config.ts. If you keep a secrets provider enabled for other environments, verify it is not overriding your local connection string before you run npm run prisma:deploy.

Option 3: Hosted PostgreSQL for development

This is a good fit when you want one shared development database, or you work across multiple machines and do not want to keep database state tied to one laptop.

Official or primary docs you can start with:

Typical connection string

DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/DBNAME?schema=public"

Put that value in .env.local, then run the normal PostgreSQL Prisma path for this repo.

The exact copy path differs by provider: Neon exposes it from the project connection-string panel, Supabase from the database settings and pooler screens, Railway from service variables, and Render from the database info view. The format SaaSyBase expects is still standard PostgreSQL connection-string syntax.

npm run prisma:diagnose-provider
npm run prisma:deploy
npx prisma db seed

Decision guide

If you want...	Choose...
the easiest non-Docker setup on one laptop	Postgres.app or the EDB installer
the recommended local path on the shared repo migration lane	Native local PostgreSQL or Docker PostgreSQL
a shared development database for a team	Hosted PostgreSQL
throwaway local prototyping only	SQLite

Note

Once you are thinking about staging or production, continue to Deployment and Secrets & Providers. That is where the database target starts interacting with hosting, migrations, and secret management.