mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-14 17:40:37 +02:00
Nicky LeachandPaperclip
c4e80ccdc8
## Thinking Path > - Paperclip uses versioned PostgreSQL migrations to preserve application data. > - Drizzle uses schema snapshots to generate future migrations. > - The database package already prunes snapshots to the five newest files. > - PR #15749 added three snapshots but left eight in the resulting tree. > - This PR removes the three excess files and documents the retention requirements. > - Coding agents and Greptile receive the same scoped rule for future migration changes. ## Linked Issues or Issue Description Refs #15749. Related: #16191 includes overlapping snapshot cleanup with its new migration. This PR isolates the existing excess and the repository rule; it has no dependency on that feature. **What happened?** The migration metadata directory contains snapshots 0331–0338. The existing pruning script retains only the newest five, but the older three were left in master. **Expected behavior** Keep snapshots 0334–0338. Commit snapshot pruning alongside additions and recheck the combined tree after rebases or merges. Preserve all SQL migrations and journal entries. **Steps to reproduce** At master commite3029c632, list `packages/db/src/migrations/meta/*_snapshot.json`. There are eight files. Run `pnpm --filter @paperclipai/db prune:snapshots`; snapshots 0331–0333 are removed. **Paperclip version or commit**e3029c632. Repository maintenance; deployment mode is not applicable. ## What Changed - Remove snapshots 0331–0333 using the existing pruning script. - Add `rules/database-migration-snapshots.mdc` with retention, generation, rebase, preservation, and review requirements. - Register the rule in `.greptile/files.json` with matching scope patterns. ## Verification - Existing `prune:snapshots` script completed successfully via `npm run --prefix packages/db prune:snapshots`. - Existing migration numbering and safety checks passed, run with the available tsx loader. Safety reported only baseline-covered historical findings. - A local assertion check confirmed exactly snapshots 0334–0338 remain, with retained snapshots and journal byte-for-byte equal to the base. SQL migrations are unchanged. - A local assertion check verified that rule globs equal the Greptile scope, all manifest paths exist, representative migration/schema files match, and unrelated server/UI files do not match. - `node scripts/check-maps.mjs` and `git diff --check` passed. - Full application typecheck, test suite, and build were not run for this metadata and review-rule-only change. No runtime code, schema, SQL, or dependencies changed. ## Risks Low risk. The five newest schema snapshots remain unchanged. Database migration history is preserved. The rule supplies agent and review guidance; it does not add a new CI enforcement gate. Recheck retention if another migration merges first. ## Model Used OpenAI GPT-6 via Codex, with reasoning and shell/file tools. The exact runtime model ID and context-window size are not exposed in this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
60 lines
2.8 KiB
Plaintext
60 lines
2.8 KiB
Plaintext
---
|
|
description: Keep the five newest Drizzle schema snapshots and preserve executable migration history.
|
|
globs: "packages/db/src/schema/**,packages/db/src/migrations/**,packages/db/package.json,packages/db/drizzle.config.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Database migration snapshots
|
|
|
|
## Scope and purpose
|
|
|
|
This rule applies to database schema changes, migration files, and migration
|
|
generation configuration. Drizzle snapshots under
|
|
`packages/db/src/migrations/meta/` describe schema state for future generation.
|
|
They are not database backups or the executable migration history.
|
|
|
|
## Requirements
|
|
|
|
- Keep only the five newest `*_snapshot.json` files, ordered by their numeric
|
|
migration prefix. If fewer than five exist, retain all of them. Always retain
|
|
the newest snapshot.
|
|
- Generate schema migrations with `pnpm db:generate` from the repository root.
|
|
Its existing `prune:snapshots` step removes older snapshots. Commit those
|
|
deletions with the generated migration; do not restore them to reduce the diff.
|
|
- After a merge, rebase, cherry-pick, or migration renumbering, check the final
|
|
combined snapshot set again. A branch that was correctly pruned before a
|
|
merge can contain too many snapshots afterward. Run the existing command:
|
|
|
|
```sh
|
|
pnpm --filter @paperclipai/db prune:snapshots
|
|
```
|
|
|
|
- Pruning removes only old `*_snapshot.json` files. Preserve historical SQL
|
|
migrations and every existing `_journal.json` entry. Do not rewrite retained
|
|
snapshot contents or IDs as part of retention cleanup.
|
|
- Include snapshot deletions in the same PR that adds snapshots. A separate
|
|
cleanup PR may remove an existing excess without generating a new migration.
|
|
- Before pushing, inspect the migration diff and run
|
|
`pnpm --filter @paperclipai/db check:migrations`. Verify the retained snapshot
|
|
names separately: the numbering check validates SQL files and journal entries,
|
|
but does not enforce snapshot retention.
|
|
|
|
## Examples and exceptions
|
|
|
|
If the checkout contains `0331` through `0338`, retain `0334` through `0338`
|
|
and delete snapshots `0331`, `0332`, and `0333`. Adding snapshot `0339` then
|
|
removes snapshot `0334`. Multiple additions can require multiple deletions.
|
|
|
|
SQL-only migrations do not require an invented snapshot. Select the five newest
|
|
existing snapshots; do not assume every journal entry has one. An unrelated PR
|
|
does not need to repair historical snapshot retention.
|
|
|
|
## Review criteria
|
|
|
|
For a PR that changes migrations or snapshots, inspect the resulting tree, not
|
|
only its additions. Flag more than five snapshots, deletion of a snapshot that
|
|
belongs in the newest five, restoration of pruned snapshots, or removal of SQL
|
|
files or journal entries as part of pruning. Check again after rebases and
|
|
conflict resolution. The pruning command in `packages/db/package.json` remains
|
|
the implementation of the retention policy.
|