Last updated:
Lunora exposes three function kinds. Which one you pick depends on the side effects you need and the reactivity guarantees the client gets back.
| Kind | Side effects | Reactive | Use when |
|---|---|---|---|
query | reads only | yes, clients auto-subscribe | listing/reading data |
mutation | reads + writes | broadcasts deltas | inserts/updates/deletes |
action | anything, including fetch() | no | calling external APIs, queues, sending email |
import { mutation, query, v } from "@/lunora/_generated/server";
export const list = query.input({ channelId: v.id("channels"), limit: v.optional(v.number()) }).query(async ({ ctx, args: { channelId, limit } }) => {
return ctx.db
.query("messages")
.withIndex("by_channel", (q) => q.eq("channelId", channelId))
.order("desc")
.take(limit ?? 50);
});
export const send = mutation.input({ channelId: v.id("channels"), text: v.string() }).mutation(async ({ ctx, args }) => {
if (!ctx.auth.userId) throw new Error("must be signed in");
await ctx.db.insert("messages", { ...args, userId: ctx.auth.userId });
});The example above filters within one shard: server-side ctx.db reads run
inside the Durable Object the request already resolved to. On a sharded schema
(.shardBy(...)), the client chooses which shard a query runs against, and Lunora
default-denies a client-named non-default shard: the request is rejected with
403 FORBIDDEN_SHARD until the worker configures authorizeShard (or opts into open
access with allowUnauthenticatedShardAccess). So a query that works in tests can
still be denied at the edge if shard access isn't configured. See
Securing shard access.
ctx.db
Inside a query you get a read-only DatabaseReader. Inside a mutation
you get a DatabaseWriter with insert, patch, replace and delete (plus
the batch forms below). Both are typed by your schema, so
ctx.db.insert("messages", ...) errors at compile time if the shape is wrong.
Atomic updates
A number column accepts an operator in place of a value, and a boolean column
accepts { toggle: true }. The store applies it to the value the row holds when
the write runs, so you do not read the row first and a concurrent writer cannot
make you overwrite its change:
await ctx.db.counters.patch(id, { hits: { increment: 1 } });
await ctx.db.accounts.patch(id, { balance: { decrement: 25 }, frozen: { toggle: true } });increment, decrement, multiply and divide take a finite number. The column
must already hold a number: patching a null field, dividing by zero, or a result
that is not finite is rejected with a VALIDATION_ERROR and the row is left alone.
Operators work in patch, patchIf, patchMany and the update side of upsert.
Your row-level security (RLS) update policy is checked against the row the store actually writes, with
the operator already applied, not against the operator.
A column takes arithmetic operators when it is a v.number(), v.timestamp() or
v.date() (so expiresAt: { increment: ttlMs } works), or a v.union of one of
those with v.null() (optional or not), and { toggle: true } when it is a
v.boolean(). Any other column, such as v.any(), v.object(...), a v.literal(...)
or a union of a number and a string, stores { increment: 1 } as the plain value it
is.
On a .global() table a write that loses its version check re-reads the row and
applies the operator again, up to 16 times, instead of reporting a conflict. (A
Durable Object runs one mutation at a time, so a shard table does not race; only a
before-update trigger that awaits outside I/O can let another write in there.) A
.before update trigger therefore runs once per attempt, so keep it free of side
effects. RLS and .dropStalePatches() treat an operator as relative: the update
policy is checked against the row each attempt produces, and a patch is never
dropped as stale because the counter it increments moved.
applyPlanToCollections applies operators to the local copy, so a mutator whose
optimistic body and server body share a plan stays in agreement. In a hand-written
optimistic update you do the arithmetic yourself.
Updating one key inside an object column
A dotted key in patch sets one value inside an object column and keeps the rest of the object:
await ctx.db.users.patch(id, { "profile.plan": "team", "profile.address.city": "Paris" });Several paths into the same column fold into one write. Missing objects on the way down are created. Every
path is checked against the schema first (each step must name a field of the nested v.object, and the
value must satisfy its validator), so a typo or a wrong type is a VALIDATION_ERROR rather than a stray key.
Setting a column and a path into it in the same patch is refused as ambiguous, and an operator such as
increment applies to a top-level column only.
The merge is made against the row the store reads when the write runs, and on a .global() table a
lost version check re-reads and re-applies it rather than reporting a conflict. A path patch works with patchIf
and patchMany, your RLS update policy sees the merged row, and .dropStalePatches() judges it by
the value at the end of the path, so someone else editing a different key of the same object is not a conflict.
Batch writes
insertMany / deleteMany / patchMany apply many rows in one call. That
saves the network round-trips of a per-row loop and still runs the full single-row
pipeline for each row (defaults, validators, triggers, RLS, companion/change data capture (CDC)/broadcast).
Each is available both flat and per-table:
// flat
const ids = await ctx.db.insertMany("messages", [{ body: "a" }, { body: "b" }]);
await ctx.db.patchMany("messages", [{ id: ids[0], patch: { body: "edited" } }]);
await ctx.db.deleteMany("messages", [ids[1]]);
// per-table (scopes every id to this table)
await ctx.db.messages.deleteMany([ids[0]]);- Atomic within a mutation. The Durable Object (DO) runs each mutation in a
BEGIN/COMMITspan, so if any row in a batch throws (a validator, an RLS denial, a conflict), the whole mutation rolls back. ThelunoraTestharness mirrors this, so your tests see the same all-or-nothing behavior. (Actions have no transaction span, because they do external I/O that can't be rolled back, so rows an action writes before a later failure persist.) - Capped at 500 rows per call by default; pass
options.limitto raise it, or chunk larger sets yourself. An over-cap call is rejected before any write. deleteManyreturns{ deleted }, the number of ids requested (an unknown id is a no-op, not an error).insertManyreturns the minted ids in input order.- The per-table form (
ctx.db.<table>.deleteMany) scopes every id to that table, the same wayctx.db.<table>.deletedoes: a foreign id resolves to nothing.
insertManyUnsafe — trusted bulk import
For large trusted imports (seed, migration, admin tooling), ctx.db.insertManyUnsafe
writes the whole batch in one multi-row INSERT and skips the per-row
.check() validators and before/after triggers. That's the "unsafe": it
trusts the data and bypasses the integrity pipeline for throughput.
await ctx.db.insertManyUnsafe("events", rows, { allowExplicitId: true });It still applies column defaults, maintains all indexes and companions
(search/aggregate/rank/CDC + live subscriptions), and still enforces RLS:
secure-by-default and your table's insert policy apply exactly as for insertMany
(there is no RLS-bypassing writer). allowExplicitId preserves a supplied _id.
An id that contains a NUL character (U+0000) is refused with BAD_REQUEST, on every store.
Use it only for data you control; reach for insertMany for anything user-supplied.
ctx.auth
Carries the verified identity for the request. ctx.auth.userId is the signed-in
user's id, or null for an anonymous caller, so a truthy check both narrows it to
string and acts as your "is signed in" guard. For the full decoded claims (email,
roles, and so on), call await ctx.auth.getIdentity(), which returns the identity
object or null.
ctx.scheduler
Available in mutations and actions. ctx.scheduler.runAfter(ms, fn, args)
enqueues a deferred call against the SchedulerDO.