Document npm run db:up / db:down and db:studio

docs/development/database.md

@@ -5,6 +5,22 @@ description: Migrations, operational scripts, and database maintenance for Pages
 
 Pages CMS stores app state in PostgreSQL: auth data, collaborators, parsed config, and cache metadata. Content itself stays in GitHub.
 
+## Local database
+
+Start the local development database (Docker Compose, data persisted in a named volume):
+
+```bash
+npm run db:up
+```
+
+Stop it with `npm run db:down`. Connection defaults live in `.env.development`; override them in `.env.local` if your database differs.
+
+You can browse the database with [Drizzle Studio](https://orm.drizzle.team/drizzle-studio/overview):
+
+```bash
+npm run db:studio
+```
+
 ## Migrations
 
 Generate a migration when the schema changes:

docs/development/environment-variables.md

@@ -57,6 +57,7 @@ openssl rand -base64 32
 
 - If you use the GitHub App helper, it writes the GitHub App variables for you.
 - `GITHUB_APP_NAME` must be the app slug, not the display name.
+- `DATABASE_URL` is required in production. In development, it defaults to the local Docker database through the committed `.env.development` (override it in `.env.local` if your database differs).
 - `BASE_URL` is required in production. In development, it defaults to `http://localhost:3000`.
 - `BASE_URL`, callback URL, setup URL, and webhook URL must all point to the same app instance.
 - Use one canonical production URL only. Do not mix a custom domain and a `*.netlify.app` URL for the same install.

docs/guides/installing/index.md

@@ -6,9 +6,11 @@ description: Run Pages CMS locally with PostgreSQL, environment variables, and a
 ## Step 1: Start PostgreSQL
 
 ```bash
-docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16
+npm run db:up
 ```
 
+This runs Postgres with Docker Compose: data is persisted in a named volume, and the command returns once the database is ready. Stop it later with `npm run db:down`.
+
 ## Step 2: Install dependencies
 
 ```bash
@@ -18,11 +20,12 @@ npm install
 ## Step 3: Create `.env.local`
 
 ```bash
-DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms
 BETTER_AUTH_SECRET=your-random-secret
 CRYPTO_KEY=your-random-secret
 ```
 
+`DATABASE_URL` defaults to the local Docker database (see `.env.development`); set it in `.env.local` only if your database differs.
+
 You can generate secrets with:
 
 ```bash