Skip to main content

Writing Data

Mutations can insert, update, and remove data from database tables.

Inserting new documents​

You can create new documents in the database with the db.insert method:

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

export const createTask = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    const taskId = await ctx.db.insert("tasks", { text: args.text });
    // do something with `taskId`
  },
});

The second argument to db.insert is a JavaScript object with data for the new document.

The same types of values that can be passed into and returned from queries and mutations can be written into the database. See Data Types for the full list of supported types.

The insert method returns a globally unique ID for the newly inserted document.

Updating existing documents​

Given an existing document ID the document can be updated using the following methods:

  1. The db.patch method will patch an existing document, shallow merging it with the given partial document. New fields are added. Existing fields are overwritten. Fields set to undefined are removed.
convex/tasks.ts
TS
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const updateTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    const { id } = args;
    console.log(await ctx.db.get(id));
    // { text: "foo", status: { done: true }, _id: ... }

    // Add `tag` and overwrite `status`:
    await ctx.db.patch(id, { tag: "bar", status: { archived: true } });
    console.log(await ctx.db.get(id));
    // { text: "foo", tag: "bar", status: { archived: true }, _id: ... }

    // Unset `tag` by setting it to `undefined`
    await ctx.db.patch(id, { tag: undefined });
    console.log(await ctx.db.get(id));
    // { text: "foo", status: { archived: true }, _id: ... }
  },
});
  1. The db.replace method will replace the existing document entirely, potentially removing existing fields:
convex/tasks.ts
TS
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const replaceTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    const { id } = args;
    console.log(await ctx.db.get(id));
    // { text: "foo", _id: ... }

    // Replace the whole document
    await ctx.db.replace(id, { invalid: true });
    console.log(await ctx.db.get(id));
    // { invalid: true, _id: ... }
  },
});

Deleting documents​

Given an existing document ID the document can be removed from the table with the db.delete method.

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

export const deleteTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    await ctx.db.delete(args.id);
  },
});

Write performance and limits​

To prevent accidental writes of large amounts of records, queries and mutations enforce limits detailed here.