From e81584bac17eb488767efd43ac47c66fa3beb0e9 Mon Sep 17 00:00:00 2001 From: Derek Cooper Date: Wed, 28 Oct 2026 00:05:13 -0700 Subject: [PATCH] added database backups and restore tags for images --- slash-commands/update-deps.md | 36 ++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/slash-commands/update-deps.md b/slash-commands/update-deps.md index 730e022..cecb420 100644 --- a/slash-commands/update-deps.md +++ b/slash-commands/update-deps.md @@ -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. 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. +5. **Create a rollback point** before changing anything. Use today's date as `` (YYYY-MM-DD): + - **Code:** `git tag pre-update-`. 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 : :pre-update-`. 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//`. It must be **outside the repo**. Create it with `chmod 700`, make each backup file `chmod 600`, and never commit a backup. +- **Filename:** `-pre-update-.` +- **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 pg_dump -U -Fc > .dump` + - MySQL/MariaDB: `docker compose exec -T mysqldump --single-transaction -u -p"$PASS" > .sql`, then gzip it + - SQLite: `sqlite3 ".backup '.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 @@ -95,6 +114,12 @@ One or two sentences on what changed and anything notable. ### Verification - Build / tests / lint / container build / smoke test results + +### Rollback +- Git tag: `pre-update-` +- Image tags: `:pre-update-` (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`. @@ -107,4 +132,13 @@ Commit it as `docs(release-notes): YYYY.MM dependency updates`. - Before and after test results compared with the baseline - Deferred items - 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-`. 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 `, then rebuild and redeploy + - Undo the whole run: `git revert --no-edit pre-update-..HEAD`, then rebuild and redeploy + - Run the old images immediately: change the image tags in compose to `pre-update-`, 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 :pre-update-`. Keep git tags. They cost nothing.