Database Configuration
Start with a development database, inspect your data, and prepare a separate production database.
Web uses PostgreSQL with a pooled driver. Start with local Docker or a hosted development database, then prepare a separate production database.
Before You Start
Install dependencies at the repository root. Use a new development database for first setup. If this is an existing customized database, read Updating Your Project before applying migrations.
Development PostgreSQL
For local Docker Postgres:
pnpm muse:init --yes --app web --docker
pnpm db:seedFor a hosted development database such as Neon, create a database, copy its connection string (including the provider's TLS parameters), and use:
pnpm muse:init --yes --app web --database-url "postgres://USER:PASSWORD@HOST:5432/DATABASE"
pnpm db:seedChoose one of these paths. Init writes DATABASE_URL in apps/web/.env.local and applies the initial migrations. If you already completed Quick Start, do not reinitialize just to inspect data.
Check migration state and open the database browser:
pnpm db:status
pnpm db:studioOpen the Studio URL printed in the terminal. Inspect seeded users without editing their auth records manually. Node uses a connection pool; DATABASE_POOL_MAX defaults to 5. Adjust it to your host's connection allowance if necessary.
Check Your Result
- Initialization and the matching seed command complete without database errors.
- The development user can sign in and saved account changes remain after refresh.
- Node
pnpm db:statusreports the expected migration state; Studio shows your development database.
Common Problems
| Problem | Fix |
|---|---|
| Connection refused | Check the Postgres host/port and whether Docker or your database service is running |
| Authentication or TLS error | Copy the full provider connection string; escape reserved password characters appropriately |
| Too many connections | Check database limits and the Node pool maximum |
| Old production data exists | Back up and design incremental migrations; do not replay the fresh-install baseline |
When You Add Tables
The schema is packages/db/src/schema.ts. Generate the matching database migrations. Shared queries in packages/db/src/queries/ receive db first; application wrappers bind the driver. Components must not access the database directly.