## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The database layer runs migrations during server startup via
`server.listen`; migrations that block this path delay instance
availability
> - Migration `0126_issue_comment_derived_attribution.sql` backfills
derived attribution columns on `issue_comments` using a LIMIT-5000 loop
with no index or keyset cursor — it re-scans the full table from the
start each batch, giving O(n²) complexity
> - On instances with millions of issue comments this blocked
`server.listen` for ~5 minutes during upgrade, causing CPU pegs and
unavailability
> - Editing 0126 in place is unsafe: the migration runner keys its
applied-set on file **content hash**, so any edit changes the hash,
causing the runner to re-apply the migration on already-migrated
databases and blocking startup
> - The safe remedy is delete-and-relocate: remove 0126 and add a new
forward migration 0132 that uses a temporary partial index + keyset
pagination (`id > last_comment_id ORDER BY id LIMIT 5000`) so every row
is visited exactly once — O(n)
> - This pull request implements that delete-and-relocate with
idempotency guards (IF NOT EXISTS DDL, backfill WHERE clause that skips
already-attributed rows) so it is a safe near-noop on already-migrated,
partially-migrated, and fresh databases alike
## Linked Issues or Issue Description
No pre-existing public GitHub issue. Inline bug report:
**What happened?**
The `0126_issue_comment_derived_attribution` migration runs during
server startup and uses a LIMIT-5000 batch loop that re-scans
`issue_comments` from row 1 each iteration (no index, no keyset cursor).
The result is O(n²) I/O that blocked `server.listen` on large instances.
**Expected behavior**
Backfill migrations should advance with a keyset cursor so each batch
reads a new slice; total work is O(n) and startup is not blocked.
**Steps to reproduce**
Run a Paperclip upgrade on an instance with ≥200k issue comments;
observe `server.listen` blocked for several minutes and CPU peg during
migration.
**Paperclip version or commit**
Reproduced on the current `master` branch prior to this fix.
**Deployment mode**
All deployment modes that run the migration runner at startup.
## What Changed
- **Deleted**
`packages/db/src/migrations/0126_issue_comment_derived_attribution.sql`
— the O(n²) LIMIT-5000 loop with no index/cursor
- **Added**
`packages/db/src/migrations/0132_issue_comment_derived_attribution_fast.sql`:
- Creates a temporary partial index over the eligible predicate before
backfilling
- Uses keyset pagination (`id > last_comment_id ORDER BY id LIMIT 5000`)
— each batch advances to the batch-max id, so every row is visited once
- Drops the temporary index at the end
- Columns/FKs guarded with `IF NOT EXISTS`; Option-A timing-tier cleanup
preserved; human-authored comments never touched
- `WHERE` clause in the backfill excludes rows already attributed (safe
near-noop on already-migrated DBs)
- **Updated** `packages/db/src/migrations/meta/_journal.json` — dropped
0126 entry, appended 0132
- **Added**
`packages/db/src/issue-comment-derived-attribution-migration.test.ts`
(345 lines) — covers fresh-install, already-0126-migrated idempotency,
and partial-backfill completion scenarios using embedded Postgres
## Verification
```bash
# Migration numbering guard
pnpm --filter @paperclipai/db check:migrations
# Migration tests (embedded Postgres, 3 scenarios)
pnpm --filter @paperclipai/db vitest run issue-comment-derived-attribution-migration.test.ts
```
Both pass locally. CI results will appear on this PR.
## Risks
**Migration safety — already-migrated databases:** Deleting 0126 leaves
an orphan row in the runner's applied-set. The runner only checks the
set for "has this been applied" — orphan rows are never re-applied. 0132
runs as a near-noop: IF NOT EXISTS DDL is skipped, and the backfill
WHERE clause excludes rows that already have attribution.
**Migration safety — partially-migrated databases:** Keyset pagination
is idempotent. 0132 picks up from the highest attributed row id, so a
partial prior run is completed correctly.
**No data loss:** The migration never deletes or overwrites
user-authored content. It only writes to derived attribution columns on
rows where attribution is absent.
**Rollback:** 0132 is a forward-only migration. If a rollback is needed,
the attribution columns remain (no harm) and can be ignored or cleaned
up in a subsequent migration.
## Model Used
Claude Sonnet 4.6 (`claude-sonnet-4-6`) via the Paperclip AI agent
harness, with tool use and extended context enabled. Implementation
authored by Priya Raman; PR opened via the Paperclip Git Expert agent.
## 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)
- [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
_(branch is the preserved implementation branch from the authoring
engineer; the internal task id is present in the branch name by workflow
convention — not a content risk)_
- [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 _(pending — CI running)_
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
_(pending — will be driven to terminal-green before merge)_
- [ ] I will address all Greptile and reviewer comments before
requesting merge _(pending — will action all findings)_
Co-authored-by: Paperclip <noreply@paperclip.ing>
Nicky Leach