Mutations

Convex mutations — transactional write functions. Cannot call third-party APIs.

Mutations write data, transactionally. ACID guarantees: either everything in the mutation succeeds, or none of it does.

Anatomy

convex/tasks.ts

import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const create = mutation({
  args: {
    teamId: v.id("teams"),
    title:  v.string(),
  },
  handler: async (ctx, { teamId, title }) => {
    const user = await ctx.auth.getUserIdentity();
    if (!user) throw new Error("Not signed in");

    return await ctx.db.insert("tasks", {
      teamId,
      title,
      status:    "open",
      createdBy: user.subject as Id<"users">,
      createdAt: Date.now(),
    });
  },
});

On the client

import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

const create = useMutation(api.tasks.create);

await create({ teamId, title: "New task" });

Database operations

await ctx.db.insert("table", { ...fields });
await ctx.db.patch(id, { field: newValue });        // partial update
await ctx.db.replace(id, { ...allFields });         // full replace
await ctx.db.delete(id);
const doc = await ctx.db.get(id);

Limits

• No third-party API calls — use actions for that.
• 10-second timeout.
• Atomic: if the mutation throws, all writes are rolled back.

Patterns

Auth-scoped write

const user = await ctx.auth.getUserIdentity();
if (!user) throw new Error("Not signed in");
await ctx.db.insert("posts", { ...args, authorId: user.subject });

Permission check

const target = await ctx.db.get(id);
if (target.ownerId !== user.subject) throw new Error("Permission denied");
await ctx.db.delete(id);

Cascading delete

const children = await ctx.db
  .query("comments")
  .withIndex("by_post", q => q.eq("postId", id))
  .collect();
for (const c of children) await ctx.db.delete(c._id);
await ctx.db.delete(id);

Related

Queries

Read data.

Actions

For writes that need third-party calls.

Schema

Validators and constraints.