1---
2name: convex-performance-audit
3description:
4  Audits Convex performance for reads, subscriptions, write contention, and
5  function limits. Use for slow features, insights findings, OCC conflicts, or
6  read amplification.
7---
8 
9# Convex Performance Audit
10 
11Diagnose and fix performance problems in Convex applications, one problem class
12at a time.
13 
14## When to Use
15 
16- A Convex page or feature feels slow or expensive
17- `npx convex insights --details` reports high bytes read, documents read, or
18  OCC conflicts
19- Low-freshness read paths are using reactivity where point-in-time reads would
20  do
21- OCC conflict errors or excessive mutation retries
22- High subscription count or slow UI updates
23- Functions approaching execution or transaction limits
24- The same performance pattern needs fixing across sibling functions
25 
26## When Not to Use
27 
28- Initial Convex setup, auth setup, or component extraction
29- Pure schema migrations with no performance goal
30- One-off micro-optimizations without a user-visible or deployment-visible
31  problem
32 
33## Guardrails
34 
35- Prefer simpler code when scale is small, traffic is modest, or the available
36  signals are weak
37- Do not recommend digest tables, document splitting, fetch-strategy changes, or
38  migration-heavy rollouts unless there is a measured signal, a clearly
39  unbounded path, or a known hot read/write path
40- In Convex, a simple scan on a small table is often acceptable. Do not invent
41  structural work just because a pattern is not ideal at large scale
42 
43## First Step: Gather Signals
44 
45Start with the strongest signal available:
46 
471. If deployment Health insights are already available from the user or the
48   current context, treat them as a first-class source of performance signals.
492. If CLI insights are available, run `npx convex insights --details`. Use
50   `--prod`, `--preview-name`, or `--deployment-name` when needed.
51   - If the local repo's Convex CLI is too old to support `insights`, try
52     `npx -y convex@latest insights --details` before giving up.
533. If the repo already uses `convex-doctor`, you may treat its findings as
54   hints. Do not require it, and do not treat it as the source of truth.
554. If runtime signals are unavailable, audit from code anyway, but keep the
56   guardrails above in mind. Lack of insights is not proof of health, but it is
57   also not proof that a large refactor is warranted.
58 
59## Signal Routing
60 
61After gathering signals, identify the problem class and read the matching
62reference file.
63 
64| Signal                                                         | Reference                                 |
65| -------------------------------------------------------------- | ----------------------------------------- |
66| High bytes or documents read, JS filtering, unnecessary joins  | `references/hot-path-rules.md`            |
67| OCC conflict errors, write contention, mutation retries        | `references/occ-conflicts.md`             |
68| High subscription count, slow UI updates, excessive re-renders | `references/subscription-cost.md`         |
69| Function timeouts, transaction size errors, large payloads     | `references/function-budget.md`           |
70| General "it's slow" with no specific signal                    | Start with `references/hot-path-rules.md` |
71 
72Multiple problem classes can overlap. Read the most relevant reference first,
73then check the others if symptoms remain.
74 
75## Escalate Larger Fixes
76 
77If the likely fix is invasive, cross-cutting, or migration-heavy, stop and
78present options before editing.
79 
80Examples:
81 
82- introducing digest or summary tables across multiple flows
83- splitting documents to isolate frequently-updated fields
84- reworking pagination or fetch strategy across several screens
85- switching to a new index or denormalized field that needs migration-safe
86  rollout
87 
88When correctness depends on handling old and new states during a rollout,
89consult `skills/convex-migration-helper/SKILL.md` for the migration workflow.
90 
91## Workflow
92 
93### 1. Scope the problem
94 
95Pick one concrete user flow from the actual project. Look at the codebase,
96client pages, and API surface to find the flow that matches the symptom.
97 
98Write down:
99 
100- entrypoint functions
101- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`
102- tables read
103- tables written
104- whether the path is high-read, high-write, or both
105 
106### 2. Trace the full read and write set
107 
108For each function in the path:
109 
1101. Trace every `ctx.db.get()` and `ctx.db.query()`
1112. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`
1123. Note foreign-key lookups, JS-side filtering, and full-document reads
1134. Identify all sibling functions touching the same tables
1145. Identify reactive stats, aggregates, or widgets rendered on the same page
115 
116In Convex, every extra read increases transaction work, and every write can
117invalidate reactive subscribers. Treat read amplification and invalidation
118amplification as first-class problems.
119 
120### 3. Apply fixes from the relevant reference
121 
122Read the reference file matching your problem class. Each reference includes
123specific patterns, code examples, and a recommended fix order.
124 
125Do not stop at the single function named by an insight. Trace sibling readers
126and writers touching the same tables.
127 
128### 4. Fix sibling functions together
129 
130When one function touching a table has a performance bug, audit sibling
131functions for the same pattern.
132 
133After finding one problem, inspect both sibling readers and sibling writers for
134the same table family, including companion digest or summary tables.
135 
136Examples:
137 
138- If one list query switches from full docs to a digest table, inspect the other
139  list queries for that table
140- If one mutation isolates a frequently-updated field or splits a hot document,
141  inspect the other writers to the same table
142- If one read path needs a migration-safe rollout for an unbackfilled field,
143  inspect sibling reads for the same rollout risk
144 
145Do not leave one path fixed and another path on the old pattern unless there is
146a clear product reason.
147 
148### 5. Verify before finishing
149 
150Confirm all of these:
151 
1521. Results are the same as before, no dropped records
1532. Eliminated reads or writes are no longer in the path where expected
1543. Fallback behavior works when denormalized or indexed fields are missing
1554. Frequently-updated fields are isolated from widely-read documents where
156   needed
1575. Every relevant sibling reader and writer was inspected, not just the original
158   function
159 
160## Reference Files
161 
162- `references/hot-path-rules.md` - Read amplification, invalidation,
163  denormalization, indexes, digest tables
164- `references/occ-conflicts.md` - Write contention, OCC resolution, hot document
165  splitting
166- `references/subscription-cost.md` - Reactive query cost, subscription
167  granularity, point-in-time reads
168- `references/function-budget.md` - Execution limits, transaction size, large
169  documents, payload size
170 
171Also check the official
172[Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)
173page for additional patterns covering argument validation, access control, and
174code organization that may surface during the audit.
175 
176## Checklist
177 
178- [ ] Gathered signals from insights, dashboard, or code audit
179- [ ] Identified the problem class and read the matching reference
180- [ ] Scoped one concrete user flow or function path
181- [ ] Traced every read and write in that path
182- [ ] Identified sibling functions touching the same tables
183- [ ] Applied fixes from the reference, following the recommended fix order
184- [ ] Fixed sibling functions consistently
185- [ ] Verified behavior and confirmed no regressions
186