From df015793cca50fe319a0ef7f162f0f6c3d78adbe Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 7 Jul 2026 12:22:03 +0200 Subject: [PATCH] Sync wiki from project files --- Repo-docs-RELEASE-DEPENDENCIES.md | 40 ++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index 58fd69f..18b35fd 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`. > Origin: `repository`. @@ -85,7 +85,22 @@ The installer uses a runtime lock, snapshots `pip freeze` plus WebUI `runtime/module-installer/runs`, and marks planned rows as applied only after all commands succeed. When `--migrate` is used with a `sqlite:///` database URL, the installer also snapshots the SQLite database with SQLite's backup API before -running migrations. +running migrations. For other database engines, pass external backup/restore +hooks: + +```bash +govoplan-module-installer \ + --supervise \ + --migrate \ + --database-backup-command 'pg_dump --format=custom "$GOVOPLAN_DATABASE_URL" > "$GOVOPLAN_DATABASE_BACKUP_PATH"' \ + --database-restore-command 'pg_restore --clean --if-exists --dbname "$GOVOPLAN_DATABASE_URL" "$GOVOPLAN_DATABASE_BACKUP_PATH"' \ + --health-url http://127.0.0.1:8000/health \ + --restart-command '' +``` + +The backup command runs before migrations. The restore command is stored in the +run record and runs during rollback unless an override is passed to +`--rollback`. Supervised mode treats package command failure, migration failure, restart failure, and health timeout as rollback triggers. It restores the Python/WebUI @@ -95,17 +110,30 @@ run outside the FastAPI server process; the admin UI saves and validates plans but does not mutate packages from an HTTP request. Package rollback is automatic. SQLite database rollback is automatic for -installer runs that used `--migrate` and captured a database snapshot. Non-SQLite -production deployments must provide their own managed backup/restore procedure -before running migrations; the current installer blocks automatic migration -backup for unsupported database URLs. +installer runs that used `--migrate` and captured a database snapshot. +Non-SQLite rollback is automatic when the run used +`--database-backup-command` and `--database-restore-command`; otherwise migrated +non-SQLite runs are blocked before package changes are applied. Rollback uses the saved run snapshot: ```bash govoplan-module-installer --rollback +govoplan-module-installer --rollback --database-restore-command '' ``` +Database hook commands run with these environment variables: + +- `GOVOPLAN_INSTALLER_RUN_DIR`: the run snapshot directory +- `GOVOPLAN_DATABASE_URL`: the configured database URL +- `GOVOPLAN_DATABASE_BACKUP_PATH`: a suggested backup artifact path inside the + run directory +- `GOVOPLAN_DATABASE_BACKUP_METADATA`: optional JSON metadata path that backup + commands may write for operator diagnostics + +Avoid embedding secrets directly in commands; prefer environment variables, +service credentials, or deployment-local secret injection. + Inspect installer history and lock state from the operator shell: ```bash