wcz-layout/skills/start/steps/04-database-setup.md

# Database Setup

> Create `.env.local` if it does not exist, then preserve its existing keys when setting database values. Values written here are temporary when the project uses Vault: the Vault Setup step moves them into the Vault `default` secret. Both `DATABASE_URL` and `DATABASE_SCHEMA` stay in `.env.local` — drizzle-kit (`db:studio`, `db:generate`) reads both.

## User Input

Ask: **"Do you already have a Postgres database created for this project? (yes/no)"**

## Branch A — Existing database

1. Ask: **"Please enter your database schema name (e.g. `dev_portal`)."**
2. Update `.env.local` → set `DATABASE_SCHEMA=<user-input>`.

## Branch B — No database

Ask: **"Would you like me to create a local Postgres database using Docker? (yes/no)"**

- **No** → continue to next step.
- **Yes** → execute the Docker flow below.

### Docker flow

The container name is `<project-name>-postgres` where `<project-name>` is the kebab-case project name (read from the `name` field in `package.json`).

1. Ensure the Docker daemon is running. If not, start Docker Desktop via terminal automatically.
2. Auto-generate password.
3. Discover occupied ports by listing **all** containers (including stopped) and pick the first port in **5432 → 5450** that does **not** appear in the output. If all ports are occupied, stop and inform the user.
4. Run the container on the chosen port:

```powershell
docker run --name <project-name>-postgres -e POSTGRES_PASSWORD=<password> -d -p <PORT>:5432 postgres
```

- **Success** → continue.
- **Error** → stop and show the full error to the user.

5. Update `.env.local`:
   - Set `DATABASE_URL=postgres://postgres:<password>@localhost:<PORT>/postgres`.
   - Set `DATABASE_SCHEMA=public`.
6. Output exactly:
   > ✅ Local Postgres database created successfully on port [PORT]