feat(database): add an infrastructure-error classifier and read-retry helper

[d-cs]

Summary

Adds two shared primitives to @internal/database for surviving brief database connection blips: a classifier that recognises connectivity/infrastructure failures (as opposed to real query errors), and withInfraRetry, a helper that retries an operation on those failures.

Details

isInfrastructureError / looksLikeConnectivityError recognise connection-level failures (unreachable server, closed connection, connection reset, connect timeouts) and deliberately do not match query or validation errors, so retries never mask a real bug.

withInfraRetry(run, config) retries run on a classified infrastructure error with jittered backoff, gated by a shared token-bucket budget so a mass freeze cannot amplify into a retry storm. It has an enabled kill-switch (off by default) and reuses the existing retry-budget primitive.

It must only wrap operations that are safe to run more than once (reads, or writes made idempotent); it deliberately provides no path that silently retries a non-idempotent write.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d85831a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 693c45de-66e3-488b-b78e-987280d429d9

📥 Commits

Reviewing files that changed from the base of the PR and between e77d850 and d85831a.

📒 Files selected for processing (4)

• internal-packages/database/src/infraError.test.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraRetry.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: All PR Checks

🧰 Additional context used

📓 Path-based instructions (9)

We use vitest exclusively.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

**Prefer static imports over dynamic imports.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Add crumbs as you write code — not just when debugging.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Use `$replica` from `~/db.server` for read-heavy queries in the webapp.

📄 CodeRabbit inference engine (internal-packages/database/CLAUDE.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Use Prisma for database interactions in internal-packages/database with PostgreSQL

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Use vitest for all tests in the Trigger.dev repository

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Use function declarations instead of default exports

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

Use types over interfaces for TypeScript Avoid using enums; prefer string unions or const objects instead

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs Do not use high-cardinality attributes in OTEL metr...

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

Files:

• internal-packages/database/src/infraRetry.ts
• internal-packages/database/src/infraError.ts
• internal-packages/database/src/infraRetry.test.ts
• internal-packages/database/src/infraError.test.ts

🧠 Learnings (4)

📚 Learning: 2026-06-04T18:16:35.386Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3836
File: apps/supervisor/src/backpressure/backpressureMonitor.ts:3-5
Timestamp: 2026-06-04T18:16:35.386Z
Learning: When reviewing TypeScript in this repo, apply the rule “prefer type aliases over interfaces” only to data/object shapes and union/intersection type modeling. If an interface is being used as a behavioral contract for collaborators to implement (e.g., method-shape interfaces that define required behavior, such as `BackpressureLogger` / `BackpressureSignalSource` in `apps/supervisor/src/backpressure/backpressureMonitor.ts`), keep it as an `interface` and do not flag it as a type-alias-vs-interface violation.

Applied to files:

• internal-packages/database/src/infraRetry.ts

📚 Learning: 2026-05-18T08:21:27.694Z

Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3632
File: apps/webapp/sentry.server.ts:4-21
Timestamp: 2026-05-18T08:21:27.694Z
Learning: When handling Prisma errors for P1001 ("Can't reach database server"), do not assume it only appears under a single property name. Prisma may surface P1001 via either `PrismaClientKnownRequestError` (`err.code === "P1001"`, e.g., mid-query connection drops) or `PrismaClientInitializationError` (`err.errorCode === "P1001"`, e.g., client startup connection failure). To reliably detect the condition, check `err.code === "P1001" || err.errorCode === "P1001"`, and avoid review rules that would incorrectly flag `err.code === "P1001"` as unreachable/never-matching.

Applied to files:

• internal-packages/database/src/infraError.ts

📚 Learning: 2026-05-18T08:21:27.694Z

Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3632
File: apps/webapp/sentry.server.ts:4-21
Timestamp: 2026-05-18T08:21:27.694Z
Learning: When handling Prisma error P1001 ("Can't reach database server") in TypeScript, don’t assume a single error shape. Prisma can surface P1001 via two different error classes/fields: `PrismaClientKnownRequestError` exposes it as `err.code === "P1001"` (common during mid-query connection drops), while `PrismaClientInitializationError` exposes it as `err.errorCode === "P1001"` (common on client startup failure). Therefore, predicates should use `err.code === "P1001" || err.errorCode === "P1001"`. Do not flag `err.code === "P1001"` as “unreachable/never matches,” as it is expected in production.

Applied to files:

• internal-packages/database/src/infraError.ts

📚 Learning: 2026-06-16T09:19:47.637Z

Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3960
File: apps/webapp/test/prismaInfrastructureErrorCapture.test.ts:0-0
Timestamp: 2026-06-16T09:19:47.637Z
Learning: In this repo’s Vitest setup, `vitest.config.ts` uses `globals: true`, so identifiers like `vi`, `describe`, `it`, and `expect` are available as globals in Vitest test files. During code review, do not flag missing `vi`/`describe`/`it`/`expect` imports as a runtime error or correctness issue when they’re used in `*.test.ts/tsx` or `*.spec.ts/tsx` files. Explicit imports are still preferred for consistency, but they’re not required for runtime behavior.

Applied to files:

• internal-packages/database/src/infraRetry.test.ts

---

Walkthrough

The database package adds Prisma and connectivity-error classification. It adds withInfraRetry with configurable attempts, jittered backoff, retry budgets, injected timing, and callbacks. Tests cover classification, retry behavior, budget limits, default classification, attempt limits, and delay calculation. The package index re-exports both new modules.

Merge Risk: ⚪ Minimal · up to d8583

This localized change adds database error classification and an opt-in retry helper; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 5 files.
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.
Title check	✅ Passed	The title clearly and concisely describes the two primary changes: infrastructure-error classification and a database retry helper.
Description check	✅ Passed	The description is on-topic and clearly explains the classifier, retry behavior, safety constraints, kill-switch, backoff, and shared retry budget. It omits the template sections for issue closure, ch…

Full details: Description check

Explanation

The description is on-topic and clearly explains the classifier, retry behavior, safety constraints, kill-switch, backoff, and shared retry budget. It omits the template sections for issue closure, checklist, explicit testing steps, changelog, and screenshots, but the core change description is complete.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tri-13553-infra-retry-util

---

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.}