@lunora/cli

--- name: lunora-performance-audit description: Diagnoses and fixes Lunora performance problems — full-table scans, missing indexes, OCC write conflicts, oversized subscriptions, and sharding/`.global()` scaling. Use when queries are slow, mutations conflict, `lunora insights` reports a hot-spot, or `@lunora/advisor` flags a table. --- # Lunora Performance Audit Systematically diagnose Lunora performance issues, route to the right fix, and apply it across sibling functions consistently. ## When to Use - Queries feel slow or read far more rows than they return. - Mutations retry or conflict under load (OCC). - Subscriptions fan out updates too broadly or re-run too often. - The Lunora Studio **Advisors** tab or `@lunora/advisor` flags a table. ## When Not to Use - Scale is small, traffic is modest, and there is no measured problem — prefer simpler code. Do not introduce sharding, digests, or splits on speculation. ## Core Workflow 1. **Scope** one concrete user flow with a clear entry and exit. 2. **Trace** every `ctx.db` read and write in that flow. 3. **Route** to the matching problem class below. 4. **Fix siblings** consistently — every function touching the same table should read it the same indexed way. 5. **Verify** behavior is unchanged and the advisor finding clears. ## Signal Gathering ### Runtime signal: `lunora insights` When the worker is running and has served traffic, start here — it reports the measured problem, not a suspected one: ```bash lunora insights # against the local dev worker lunora insights --shard channel:demo # scope to one shard lunora insights --limit 25 --json # machine-readable, more rows lunora insights --prod --url https://app.example.com --token $LUNORA_ADMIN_TOKEN ``` It ranks per-function **write-conflict hot-spots** (OCC contention — the sharding signal), **error rates**, and **latency outliers**. A function at the top of the write-conflict list is the direct input to the OCC section below; a latency outlier usually resolves to the read-amplification section. The Studio **Issues** panel and `lunora logs` cover the error side in more detail once `insights` tells you where to look. ### Static signal: the advisors These need no traffic, so they also work on a cold codebase: - **Lunora Studio → Advisors tab** surfaces `@lunora/advisor` findings live in dev. - `@lunora/advisor` runs ~90 static lints over `defineSchema` + discovered query reads / insert writes (plus a few runtime lints). The performance/schema rules most relevant here: - `filter-without-index` — a query filters a table with no covering index. - `unindexed-foreign-key` — a relation/FK column has no index. - `duplicate-index` / `empty-index` — wasted or malformed indexes. - `index-references-unknown-field`, `relation-references-unknown-field`, `relation-references-unknown-table` — broken index/relation definitions. - `table-without-insert` — a table is read but never written (often a schema/typo signal). ## Problem Class: Read Amplification (the common one) **Symptom:** a query reads the whole table to return a few rows; `filter-without-index` fires. **Fix:** read through an index, not `.filter()`. Declare the index on the table and use `.withIndex()` with an equality/range on the leading columns. ```ts // Bad — scans every row, then filters in memory. const mine = (await ctx.db.query("documents").collect()).filter((d) => d.orgId === orgId); // Good — declare the index… documents: defineTable({ orgId: v.string(), createdAt: v.number() /* … */ }).index("by_org_created", ["orgId", "createdAt"]); // …and read through it. const mine = await ctx.db .query("documents") .withIndex("by_org_created", (q) => q.eq("orgId", orgId)) .collect(); ``` Index columns are ordered: put equality columns first, then the range/sort column. Fix every sibling query on the table the same way. ## Problem Class: Write Conflicts (OCC) **Symptom:** mutations on hot rows retry or fail under concurrency, or the function tops the write-conflict section of `lunora insights`. ShardDO uses optimistic concurrency control — concurrent writes to the same DO that touch overlapping state conflict and retry. **Fixes, in order of preference:** 1. **Narrow the write.** Patch only the fields that changed; avoid read-modify- write over rows another mutation also touches. 2. **Partition with `.shardBy(key)`.** Move per-user / per-tenant / per-room state into its own DO so writes for different keys never contend. This is the primary horizontal-scale lever — most write contention is a single-DO hotspot. 3. **Avoid unbounded counters/aggregates in the hot path.** Accumulate in a sharded/append shape and fold lazily rather than serializing every writer through one row. ## Problem Class: Subscription Cost **Symptom:** a `useQuery` re-runs and re-pushes to many clients on unrelated writes. **Fixes:** - **Scope query args tightly** so a subscription only depends on the rows it renders — a query keyed by `orgId` should not re-run for another org's write. - **Read through indexes** (above) so the reactive dependency is the narrow index range, not the whole table. - ShardDO subscriptions are **hibernated WebSockets** — idle connections cost nothing; the lever is _how many rows each live query depends on_, not raw connection count. ## Problem Class: Cross-Region Reads **Symptom:** read-heavy, rarely-written data is slow for far-away users. **Fix:** chain `.global()` on the table to replicate it to D1 for low-latency cross-region reads (with read-your-writes via the Sessions API). Reserve it for read-mostly tables — `.global()` adds the D1 migration flow (see the `lunora-migration-helper` skill) and write-path cost. If the dataset outgrows D1, `.global({ backend: "hyperdrive" })` serves the same reactive `.global()` contract from Postgres/MySQL over Cloudflare Hyperdrive — see the `lunora-setup-hyperdrive-global` skill (and `lunora migrate d1-to-hyperdrive` to move an existing dataset). ### `.shardBy(key)` vs `.global()` — choose one per table - `.shardBy(key)`: partitions a table across Durable Objects by key — scales _writes_ (e.g. messages per room). Reads are per-shard. - `.global()`: replicates a table to D1 — scales _cross-region reads_ with read-your-writes (e.g. a mostly-read catalog). - They are not combined on the same table; the default (neither) is a single root-scoped ShardDO. ## Guardrails - Prefer simpler code when scale is small or the signal is weak. - Do not recommend structural changes (digest tables, document splitting, sharding) without a measured signal or a known hot path. - When you change how one function reads/writes a table, change its siblings to match — half-migrated access patterns are their own bug. ## Checklist - [ ] Scoped one concrete flow; traced every `ctx.db` read/write. - [ ] Ran `lunora insights` (if the worker has traffic) for the measured signal. - [ ] Checked the Studio Advisors tab / `@lunora/advisor` findings. - [ ] Read amplification: replaced `.filter()` with an indexed `.withIndex()`. - [ ] Write conflicts: narrowed writes and/or partitioned with `.shardBy(key)`. - [ ] Subscription cost: scoped query args so live queries depend on few rows. - [ ] Cross-region: applied `.global()` only to read-mostly tables. - [ ] Fixed sibling functions consistently; verified behavior unchanged.