Write data inside a Convex mutation using insert/patch/replace/delete, relying on single-transaction and OCC guarantees

Documented steps

1. Define the mutation as export const name = mutation({ args: { ...v validators... }, handler: async (ctx, args) => {...} }), importing mutation from "./_generated/server" and v from "convex/values".
2. Insert a new document with const id = await ctx.db.insert("tasks", { text: args.text }); Convex assigns _id and _creationTime and returns the new document's ID.
3. Shallow-merge an update with await ctx.db.patch("tasks", id, { tag: "bar", status: { archived: true } }) — note the table name is the FIRST argument; this adds/overwrites the given fields and leaves other fields untouched (setting a field to undefined removes it).
4. Fully overwrite a document with await ctx.db.replace("tasks", id, { invalid: true }); fields not included in the new value are dropped.
5. Remove a document with await ctx.db.delete("tasks", args.id) — again table name first.
6. Rely on the whole mutation handler executing as a single transaction: all ctx.db reads see one consistent snapshot, and all writes commit together only if the handler finishes without throwing.
7. Understand Convex optimistic concurrency control: mutations read record versions, and at commit Convex checks whether every read version is still current; on conflict Convex automatically re-runs the whole mutation function.
8. Keep mutations deterministic — no fetch() or filesystem calls — since that determinism is what lets Convex safely auto-retry a mutation on an OCC conflict; use actions for third-party API calls.
9. Stay within transaction read/write limits so the mutation can commit; batch large workloads across multiple mutations.
10. Push functions with npx convex dev or npx convex deploy, then call the mutation from React via useMutation(api.module.functionName); React and Rust clients execute mutations sequentially in a queue.
11. Official docs: https://docs.convex.dev/database/writing-data and https://docs.convex.dev/database/advanced/occ