From 0a4b850ce71e0d316a2df5fc0d58e9771feecdbe Mon Sep 17 00:00:00 2001 From: Guido X Jansen Date: Sun, 1 Mar 2026 10:44:16 +0100 Subject: [PATCH] docs: replace migration references with drizzle-kit push for alpha (#55) During alpha, schema changes use drizzle-kit push, not migrations. Update docs, env example, PR template, and scripts to reflect this. MIGRATION_DATABASE_URL is reserved for beta when proper migrations are introduced. --- .env.example | 4 ++-- .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/configuration.md | 2 +- docs/deployment-checklist.md | 4 ++-- docs/installation.md | 2 +- docs/security-hardening.md | 4 ++-- docs/upgrading.md | 4 ++-- scripts/reset-staging.sh | 6 +++--- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.env.example b/.env.example index de57768..a5bd13d 100644 --- a/.env.example +++ b/.env.example @@ -37,8 +37,8 @@ POSTGRES_DB="barazo" # Uses the application role with INSERT/UPDATE/DELETE/SELECT privileges DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}" -# Migration database URL (used only by migration scripts) -# Uses a migration role with DDL privileges +# Migration database URL (reserved for beta -- not used in alpha) +# Will use a migration role with DDL privileges when proper migrations are needed # MIGRATION_DATABASE_URL="postgresql://barazo_migrator:CHANGE_ME@postgres:5432/${POSTGRES_DB}" # ============================================================================== diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index af93ade..bb8c2c3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -34,7 +34,7 @@ Closes # - [ ] No TypeScript errors (`pnpm typecheck`) - [ ] No ESLint warnings (`pnpm lint`) - [ ] Documentation updated (if applicable) -- [ ] Database migration included (if schema changed) +- [ ] Database schema updated (if schema changed) - [ ] Breaking changes documented below (if applicable) - [ ] CI checks pass - [ ] No secrets or credentials in code diff --git a/docs/configuration.md b/docs/configuration.md index 08f12bd..af2b476 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -20,7 +20,7 @@ All Barazo environment variables with descriptions, defaults, and examples. | `POSTGRES_DB` | Yes | -- | Database name | | `POSTGRES_PORT` | No | `5432` | Host port mapping (dev compose only) | | `DATABASE_URL` | Yes | -- | Connection string for the API. Format: `postgresql://user:pass@postgres:5432/dbname` | -| `MIGRATION_DATABASE_URL` | No | -- | Connection string for migrations (DDL role, if using role separation) | +| `MIGRATION_DATABASE_URL` | No | -- | Connection string for schema changes (DDL role, if using role separation). Reserved for beta -- not used in alpha. | ## Cache (Valkey) diff --git a/docs/deployment-checklist.md b/docs/deployment-checklist.md index 39ac077..c16d4b2 100644 --- a/docs/deployment-checklist.md +++ b/docs/deployment-checklist.md @@ -88,7 +88,7 @@ This checklist covers the first production deployment of `barazo.forum`. For sel | `POSTGRES_PASSWORD` | (generated above) | | `VALKEY_PASSWORD` | (generated above) | | `DATABASE_URL` | `postgresql://barazo_app:@postgres:5432/barazo` | - | `MIGRATION_DATABASE_URL` | `postgresql://barazo_migrator:@postgres:5432/barazo` | + | ~~`MIGRATION_DATABASE_URL`~~ | Not used in alpha. Reserved for beta when migrations are needed. | | `TAP_ADMIN_PASSWORD` | (generated above) | | `SESSION_SECRET` | (generated above) | | `OAUTH_CLIENT_ID` | `https://barazo.forum` | @@ -234,7 +234,7 @@ docker compose pull docker compose up -d ``` -Database migrations run automatically on API startup. If a migration introduced a breaking change, restore from backup (see [Backup & Restore](backups.md)). +During alpha, the database schema is rebuilt on deploy. If a schema change causes issues, restore from backup (see [Backup & Restore](backups.md)). ### Daily Checks diff --git a/docs/installation.md b/docs/installation.md index cc4030c..0d6d627 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -171,7 +171,7 @@ To wipe all staging data and start fresh: ./scripts/reset-staging.sh ``` -This drops and recreates the database, flushes the cache, and restarts all services. The API applies migrations automatically on startup. Run `seed-staging.sh` afterward to repopulate test data. +This drops and recreates the database, flushes the cache, and restarts all services. The schema is applied automatically on startup. Run `seed-staging.sh` afterward to repopulate test data. ### Smoke Test diff --git a/docs/security-hardening.md b/docs/security-hardening.md index 61e3540..2e862de 100644 --- a/docs/security-hardening.md +++ b/docs/security-hardening.md @@ -213,11 +213,11 @@ Barazo uses three PostgreSQL roles with least-privilege access: | Role | Privileges | Used By | |------|-----------|---------| -| `barazo_migrator` | DDL (CREATE, ALTER, DROP) | Migration scripts only | +| `barazo_migrator` | DDL (CREATE, ALTER, DROP) | Schema changes (reserved for beta) | | `barazo_app` | DML (SELECT, INSERT, UPDATE, DELETE) | API server | | `barazo_readonly` | SELECT only | Search, public endpoints, reporting | -The API server connects with `barazo_app` -- it cannot modify the schema. Migrations use `barazo_migrator` and run only during startup. +The API server connects with `barazo_app` -- it cannot modify the schema. During alpha, schema is applied via `drizzle-kit push` at deploy time. In beta, `barazo_migrator` will run proper migrations. ### Connection Security diff --git a/docs/upgrading.md b/docs/upgrading.md index 138ef72..82d8d9f 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -18,7 +18,7 @@ docker compose ps ./scripts/smoke-test.sh https://your-domain.com ``` -Database migrations run automatically when the API starts. No manual migration step is needed. +The database schema is applied via `drizzle-kit push` during deployment. No manual schema step is needed. ## Pinned Version Upgrade @@ -75,5 +75,5 @@ Major version bumps (e.g., 1.x to 2.x) may include breaking changes that require Common breaking changes to watch for: - **Environment variable renames** -- update your `.env` file -- **Database schema changes** -- migrations run automatically, but rollback may require the backup +- **Database schema changes** -- schema is pushed on deploy, but rollback may require the backup - **Caddy configuration changes** -- check if Caddyfile needs updates diff --git a/scripts/reset-staging.sh b/scripts/reset-staging.sh index ff51efc..dbbac1d 100755 --- a/scripts/reset-staging.sh +++ b/scripts/reset-staging.sh @@ -11,7 +11,7 @@ # What it does: # 1. Stops API and Web services (keeps postgres/valkey running) # 2. Drops and recreates the staging database -# 3. Restarts all services (API runs migrations on startup) +# 3. Restarts all services (schema is applied on startup) # # Environment: # COMPOSE_FILE Docker Compose files (default: docker-compose.yml -f docker-compose.staging.yml) @@ -95,7 +95,7 @@ echo "Flushing Valkey cache..." # On staging, we restart valkey instead to clear all data. $COMPOSE_CMD restart valkey -# Step 4: Restart all services (API runs migrations on startup) +# Step 4: Restart all services (schema is applied on startup) echo "Starting all services..." $COMPOSE_CMD up -d @@ -112,6 +112,6 @@ fi echo "" echo "Staging reset complete." -echo "The API will run database migrations automatically on startup." +echo "The database schema will be applied automatically on startup." echo "" echo "To seed test data, run: ./scripts/seed-staging.sh" -- 2.51.2