Add paginator support from convex-helpers for component migrations

[ianmacartney]

Add convex-helpers pagination support

• Add convex-helpers to use paginator instead of .paginate
• Add optional schema parameter to Migrations constructor enabling customRange and component support
• Detect cursor format with isNewFormatCursor() helper to handle both new JSON array cursors and legacy encrypted cursors
• Create local component example in example/convex/localComponent/ demonstrating migrations within a Convex component
• Require schema parameter when using customRange functionality
• Add tests for cursor format detection

[coderabbitai]

Warning

Review limit reached

@ianmacartney, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 57 minutes and 31 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: get-convex/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e7aaf849-493c-4d52-8d58-3b1e8246ae90

📥 Commits

Reviewing files that changed from the base of the PR and between 86a9f56 and 5bcceac.

📒 Files selected for processing (1)

• README.md

📝 Walkthrough

Walkthrough

This PR extends the Convex migrations library to support running migrations within Convex components using the convex-helpers paginator. The Migrations class now accepts an optional schema parameter, enabling safer pagination without relying on legacy opaque cursors. A new isNewFormatCursor helper detects cursor format and branches between convex-helpers paginator and legacy query logic. Logging now includes componentPath for generating correct CLI instructions. The example adds a complete local component demonstration with schema definition, migrations, seeding, and proper wiring. Package dependencies are updated and documentation revised to show schema-aware initialization.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant MigrationsClient
  participant isNewFormatCursor
  participant Paginator
  participant LegacyDB
  CLI->>MigrationsClient: start migration (cursor)
  MigrationsClient->>isNewFormatCursor: isNewFormatCursor(cursor)
  alt new-format
    MigrationsClient->>Paginator: paginator(schema).query(table, pageCursor)
    Paginator->>MigrationsClient: page results & next cursor
  else old-format
    MigrationsClient->>LegacyDB: ctx.db.query(table, index, ...)
    LegacyDB->>MigrationsClient: query results & opaque cursor
  end
  MigrationsClient->>CLI: logStatusAndInstructions(componentPath, status, args)

Loading

Possibly Related PRs

• get-convex/migrations#15: Modifies migration execution and status instruction construction in the same logging/execution paths.
• get-convex/migrations#47: Related work touching function-metadata usage and migration invocation logic that overlaps pagination/customRange handling.

Suggested Reviewers

• reeceyang

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding paginator support from convex-helpers for component migrations, which is central to all the modifications across the codebase.
Description check	✅ Passed	The description is directly related to the changeset, detailing the key additions including convex-helpers pagination support, optional schema parameter, cursor format detection, component example, and tests.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ian/paginator-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ianmacartney]

• test short circuiting #48
• Add paginator support from convex-helpers for component migrations #27 👈 (View in Graphite)
• Allow calling migration mutations directly #47 : 1 other dependent PR (#49 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@convex-dev/migrations@27

commit: 5bcceac

[ianmacartney]

needs some work

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.md (1)

101-108: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add missing punctuation for readability.

Line 103 is missing a period after the customRange link and before "As always". The current text runs two sentences together.

📝 Proposed fix

-The `schema` provides type safety for migration definitions and support
-for pagination over custom indexes with
-[`customRange`](`#migrating-a-subset-of-a-table-using-an-index`)
-As always, database operations in migrations will abide
+The `schema` provides type safety for migration definitions and support
+for pagination over custom indexes with
+[`customRange`](`#migrating-a-subset-of-a-table-using-an-index`).
+As always, database operations in migrations will abide

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 101 - 108, The sentence after the `customRange` link
runs into the next sentence — add a period after the `customRange` link (i.e.,
end the sentence "pagination over custom indexes with
[`customRange`](`#migrating-a-subset-of-a-table-using-an-index`)." ) so that "As
always, database operations..." begins a new sentence; also ensure surrounding
sentences referencing `schema` and `internalMutation` remain unchanged except
for this punctuation fix.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 3: The changelog heading "0.3.5 alpha" is inconsistent with the package
version "0.3.5-alpha.1"; update the heading in CHANGELOG.md (the line containing
"## 0.3.5 alpha") to match the package version format (e.g., "## 0.3.5-alpha.1"
or at least "## 0.3.5-alpha") so release tracking and automation use the exact
version string.

---

Outside diff comments:
In `@README.md`:
- Around line 101-108: The sentence after the `customRange` link runs into the
next sentence — add a period after the `customRange` link (i.e., end the
sentence "pagination over custom indexes with
[`customRange`](`#migrating-a-subset-of-a-table-using-an-index`)." ) so that "As
always, database operations..." begins a new sentence; also ensure surrounding
sentences referencing `schema` and `internalMutation` remain unchanged except
for this punctuation fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: get-convex/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5d58283a-5f99-4bd9-a0d0-f970e2a207bd

📥 Commits

Reviewing files that changed from the base of the PR and between c194ed6 and 8dd5afa.

⛔ Files ignored due to path filters (6)

• example/convex/_generated/api.d.ts is excluded by !**/_generated/**
• example/convex/localComponent/_generated/api.ts is excluded by !**/_generated/**
• example/convex/localComponent/_generated/component.ts is excluded by !**/_generated/**
• example/convex/localComponent/_generated/dataModel.ts is excluded by !**/_generated/**
• example/convex/localComponent/_generated/server.ts is excluded by !**/_generated/**
• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (12)

• CHANGELOG.md
• README.md
• example/convex/convex.config.ts
• example/convex/example.ts
• example/convex/localComponent/convex.config.ts
• example/convex/localComponent/example.ts
• example/convex/localComponent/schema.ts
• example/convex/tsconfig.json
• package.json
• src/client/index.test.ts
• src/client/index.ts
• src/client/log.ts

[reeceyang]

I wonder if we can add a test to example/ that tests that migrations in a component work?

[ianmacartney]

there's code in localComponent/example.ts that I ran - overall this repo doesn't have e2e tests, which would be good to add (e.g. now workflow as part of release will run some workflows on a real deployment)