From 8987283277e3b975dca969d763205a9213c1bee8 Mon Sep 17 00:00:00 2001 From: Guido X Jansen Date: Sun, 1 Mar 2026 13:46:58 +0100 Subject: [PATCH] docs: update migration docs to reflect migration-based workflow (#56) Replace outdated drizzle-kit push references with the current migration-on-startup approach. --- docs/security-hardening.md | 2 +- docs/upgrading.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/security-hardening.md b/docs/security-hardening.md index 2e862de..3513637 100644 --- a/docs/security-hardening.md +++ b/docs/security-hardening.md @@ -217,7 +217,7 @@ Barazo uses three PostgreSQL roles with least-privilege access: | `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. During alpha, schema is applied via `drizzle-kit push` at deploy time. In beta, `barazo_migrator` will run proper migrations. +The API server connects with the database user configured in `DATABASE_URL`. On startup, it runs pending Drizzle migrations using a dedicated single-connection client, then opens the main connection pool. In a future hardening phase, migration will use a separate `barazo_migrator` role with DDL privileges, while `barazo_app` will be restricted to DML only. ### Connection Security diff --git a/docs/upgrading.md b/docs/upgrading.md index 82d8d9f..a0a0462 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -18,7 +18,9 @@ docker compose ps ./scripts/smoke-test.sh https://your-domain.com ``` -The database schema is applied via `drizzle-kit push` during deployment. No manual schema step is needed. +Database migrations are applied automatically when the API container starts. The Drizzle migration runner checks for pending migrations and applies them before accepting requests. No manual schema step is needed. + +**Important:** Database migrations are forward-only. If you need to rollback, restore from the pre-upgrade backup. ## Pinned Version Upgrade @@ -75,5 +77,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** -- schema is pushed on deploy, but rollback may require the backup +- **Database schema changes** -- migrations run automatically on startup, but rollback requires restoring from the pre-upgrade backup - **Caddy configuration changes** -- check if Caddyfile needs updates -- 2.51.2