From 326cca5870cf0bb3600b355d054a863a3cb8a9e4 Mon Sep 17 00:00:00 2001 From: Paul Payne Date: Sun, 17 May 2026 19:24:52 +0000 Subject: [PATCH] docs: Add backup/restore database naming conventions to ADDING-APPS.md Co-Authored-By: Claude Opus 4.6 --- ADDING-APPS.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/ADDING-APPS.md b/ADDING-APPS.md index 1500326..82d23ed 100644 --- a/ADDING-APPS.md +++ b/ADDING-APPS.md @@ -369,6 +369,30 @@ When apps need database URLs with embedded credentials, **always use a dedicated Add `apps.myapp.dbUrl` to your manifest's `defaultSecrets`, and the system will generate the complete URL with embedded credentials automatically when the app is added. +### Backup/Restore Database Name Conventions + +Wild Cloud's backup/restore system uses blue-green deployments. During restore, a standby copy of the app is created with a colored database name (e.g., `myapp_green`). The system automatically patches env vars in your Kubernetes resources to point to the standby database. + +**How it works:** The restore system compiles your kustomize resources, finds env vars whose values match the original database name, and generates kustomize JSON patches to replace them with the standby database name. It uses env var naming conventions to distinguish database name fields from username fields (since both often have the same value). + +**Env var naming guidelines for database-related fields:** + +- **Database name env vars** should contain one of: `DATABASE`, `DB_NAME`, `DBNAME`, or `__DATABASE` in the env var name (e.g., `LISTMONK_db__database`, `DB_NAME`, `POSTGRES_DB`) +- **Database URL env vars** are detected by containing `://` in the value (e.g., `postgresql://user:pass@host/dbname`) +- **Username env vars** should contain `USER` in the name (e.g., `DB_USER`, `LISTMONK_db__user`) — these will NOT be patched even if the value matches the database name +- Avoid env var names that are ambiguous about whether they hold a database name or username + +**Example — correct naming:** +```yaml +env: + - name: DB_NAME # Will be patched (contains "DB_NAME") + value: myapp + - name: DB_USER # Will NOT be patched (contains "USER") + value: myapp + - name: DATABASE_URL # Will be patched (contains "://") + value: "postgresql://myapp:secret@postgres/myapp" +``` + ## Security Requirements ### Security Contexts