> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript convex/tasks.ts theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/convex/actions) for that.
* **10-second timeout**.
* **Atomic**: if the mutation throws, all writes are rolled back.

## Patterns

<Tabs>
  <Tab title="Auth-scoped write">
    ```typescript theme={null}
    const user = await ctx.auth.getUserIdentity();
    if (!user) throw new Error("Not signed in");
    await ctx.db.insert("posts", { ...args, authorId: user.subject });
    ```
  </Tab>

  <Tab title="Permission check">
    ```typescript theme={null}
    const target = await ctx.db.get(id);
    if (target.ownerId !== user.subject) throw new Error("Permission denied");
    await ctx.db.delete(id);
    ```
  </Tab>

  <Tab title="Cascading delete">
    ```typescript theme={null}
    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);
    ```
  </Tab>
</Tabs>

## Related

<CardGroup cols={3}>
  <Card title="Queries" icon="search" href="/convex/queries">
    Read data.
  </Card>

  <Card title="Actions" icon="zap" href="/convex/actions">
    For writes that need third-party calls.
  </Card>

  <Card title="Schema" icon="database" href="/convex/schema">
    Validators and constraints.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.