lunora-performance-audit

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:

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.

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