95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# Backend Runtime Rules
|
|
|
|
This document defines runtime configuration requirements for the generated backend. Generators must produce a project that runs without errors when these rules are followed.
|
|
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
The backend **must** have a `.env` file at the project root (e.g. `server/.env` or backend package root). This file must **not** be committed with real credentials; provide an example instead (e.g. `.env.example`).
|
|
|
|
## Required variables
|
|
|
|
| Variable | Required | Description |
|
|
| ------------ | -------- | --------------------------------------- |
|
|
| DATABASE_URL | Yes | PostgreSQL connection string for Prisma |
|
|
|
|
## Example
|
|
|
|
```env
|
|
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"
|
|
```
|
|
|
|
## Generation requirement
|
|
|
|
When generating the backend, **always** create:
|
|
|
|
1. **`.env.example`** — with placeholder DATABASE_URL and instructions.
|
|
2. **`.env`** — with the same placeholder so the app can start; user replaces with real values.
|
|
|
|
If the generator does not create `.env`, the first run will fail with:
|
|
|
|
```
|
|
Environment variable not found: DATABASE_URL
|
|
```
|
|
|
|
---
|
|
|
|
# Prisma Client Generation
|
|
|
|
After the Prisma schema is generated or modified, the Prisma client must be generated.
|
|
|
|
## Command
|
|
|
|
```bash
|
|
npx prisma generate
|
|
```
|
|
|
|
## Lifecycle rule
|
|
|
|
Add to generated `package.json` so that `prisma generate` runs after every `npm install`:
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"postinstall": "prisma generate"
|
|
}
|
|
}
|
|
```
|
|
|
|
This ensures that after cloning or installing dependencies, the Prisma client is available without a manual step.
|
|
|
|
**Note:** Path may need to be adjusted if Prisma schema lives in a subfolder (e.g. `prisma generate` is typically run from the package root where `prisma/schema.prisma` exists).
|
|
|
|
---
|
|
|
|
# Database Migration
|
|
|
|
The generation process must document and support database migration.
|
|
|
|
## Command
|
|
|
|
```bash
|
|
npx prisma migrate dev
|
|
```
|
|
|
|
Run after:
|
|
|
|
1. Prisma schema has been generated or updated.
|
|
2. `npx prisma generate` has been run.
|
|
|
|
## Generation requirement
|
|
|
|
1. Include migration in the backend generation pipeline (see `generation/backend-generation.md`).
|
|
2. Document in README or post-generation validation that the user must run `npx prisma migrate dev` before first run (or provide a setup script that runs it).
|
|
|
|
---
|
|
|
|
# Summary
|
|
|
|
| Requirement | Action |
|
|
| --------------- | ------------------------------------------------------------- |
|
|
| DATABASE_URL | Create `.env` and `.env.example` with DATABASE_URL |
|
|
| Prisma client | Run `npx prisma generate`; add `postinstall` script |
|
|
| Database schema | Document/run `npx prisma migrate dev` after schema generation |
|