added database backups and restore tags for images

This commit is contained in:
derekc committed 2026-10-28 00:05:13 -07:00
1 parent 7f2ccb491f
commit e81584bac1
1 file changed
+35 -1
+35 -1
View File
@@ -17,6 +17,25 @@ If this project's CLAUDE.md has an "Updates" section, follow it. It may list tes
2. Note the current branch and confirm it tracks a remote. 2. Note the current branch and confirm it tracks a remote.
3. Find out how this project builds, tests, lints, and runs. Check CLAUDE.md, README, package scripts, Makefile, Dockerfile, and docker-compose files. 3. Find out how this project builds, tests, lints, and runs. Check CLAUDE.md, README, package scripts, Makefile, Dockerfile, and docker-compose files.
4. **Run a baseline** of build, tests, lint, and (if possible) a container build, *before changing anything*. Record what passes and what already fails, so that later failures can be traced to a specific update and pre-existing problems aren't blamed on it. 4. **Run a baseline** of build, tests, lint, and (if possible) a container build, *before changing anything*. Record what passes and what already fails, so that later failures can be traced to a specific update and pre-existing problems aren't blamed on it.
5. **Create a rollback point** before changing anything. Use today's date as `<DATE>` (YYYY-MM-DD):
- **Code:** `git tag pre-update-<DATE>`. Add a suffix like `-2` if that tag already exists.
- **Images:** for each image this project builds or runs (from the Dockerfile and compose files), tag the version currently in use: `docker tag <image>:<current-tag> <image>:pre-update-<DATE>`. List the tags you created.
- **Data:** if the project has a database or stateful volume, back it up yourself (see "Database backup" below) before any changes. If the backup fails or can't be verified, **STOP**. Do not continue the update without a good backup.
### Database backup
- **Location:** use the backup path from CLAUDE.md's "Updates" section if one is set. Otherwise use `~/backups/<project-name>/`. It must be **outside the repo**. Create it with `chmod 700`, make each backup file `chmod 600`, and never commit a backup.
- **Filename:** `<db-name>-pre-update-<DATE>.<ext>`
- **Method:** take a consistent backup *without stopping the app* when the database supports it. Get credentials from the running container's environment or the compose/env files. Never print passwords in your output.
- PostgreSQL: `docker compose exec -T <svc> pg_dump -U <user> -Fc <db> > <file>.dump`
- MySQL/MariaDB: `docker compose exec -T <svc> mysqldump --single-transaction -u <user> -p"$PASS" <db> > <file>.sql`, then gzip it
- SQLite: `sqlite3 <db-file> ".backup '<file>.sqlite'"`. Never use a plain `cp` on a live SQLite file.
- MongoDB: `mongodump --archive --gzip`
- Redis or caches that only hold rebuildable data: skip them and say so.
- Anything else (an unknown volume, a database that can't be dumped live): **STOP and ask me** before stopping containers to tar the volume, because that means downtime.
- **Verify the backup** before moving on. The file must not be empty, and it must pass a quick check that it can be read: `pg_restore --list` for Postgres, `PRAGMA integrity_check` for SQLite, `gunzip -t` for gzipped dumps, or checking that a `.sql` file ends with the dump-complete marker. Report the file's size and path.
- **Write down the restore command** for this specific backup. It goes in the release notes Rollback section. Don't run a restore unless I ask.
- **Pruning:** keep the 5 most recent pre-update backups for each database. List any older ones and ask before deleting them.
## Phase 1: Inventory ## Phase 1: Inventory
@@ -95,6 +114,12 @@ One or two sentences on what changed and anything notable.
### Verification ### Verification
- Build / tests / lint / container build / smoke test results - Build / tests / lint / container build / smoke test results
### Rollback
- Git tag: `pre-update-<DATE>`
- Image tags: `<image>:pre-update-<DATE>` (list each)
- Database backup: path and size, or "not applicable"
- Restore command: the exact command for this backup
``` ```
Commit it as `docs(release-notes): YYYY.MM dependency updates`. Commit it as `docs(release-notes): YYYY.MM dependency updates`.
@@ -107,4 +132,13 @@ Commit it as `docs(release-notes): YYYY.MM dependency updates`.
- Before and after test results compared with the baseline - Before and after test results compared with the baseline
- Deferred items - Deferred items
- Anything I need to do manually on deploy (env var changes, DB migrations, volume or permission changes, image re-pulls) - Anything I need to do manually on deploy (env var changes, DB migrations, volume or permission changes, image re-pulls)
3. **Ask me to confirm**, then `git push`. If any final check fails, don't push. Explain what failed instead. 3. **Ask me to confirm**, then push the commits and the rollback tag together: `git push && git push origin pre-update-<DATE>`. If any final check fails, don't push. Explain what failed instead.
4. Print the rollback commands specific to this project. Fill in the real tag and image names:
- Undo one bad update: `git revert <commit>`, then rebuild and redeploy
- Undo the whole run: `git revert --no-edit pre-update-<DATE>..HEAD`, then rebuild and redeploy
- Run the old images immediately: change the image tags in compose to `pre-update-<DATE>`, then `docker compose up -d`
- Restore the database from the backup, only if a schema or data migration happened
## Housekeeping
Rollback tags pile up over time. When there are more than 3 `pre-update-*` image tags for an image, list the older ones and ask whether to remove them with `docker rmi <image>:pre-update-<old-date>`. Keep git tags. They cost nothing.