Interface: GenericMutationCtx<DataModel>
server.GenericMutationCtx
A set of services for use within Convex mutation functions.
The mutation context is passed as the first argument to any Convex mutation function run on the server. Mutations run transactionally, all reads and writes within a single mutation are atomic and isolated.
You should generally use the MutationCtx type from
"./_generated/server".
Example
import { mutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
export const createTask = mutation({
args: { text: v.string() },
returns: v.id("tasks"),
handler: async (ctx, args) => {
// ctx.db: read and write documents
const taskId = await ctx.db.insert("tasks", { text: args.text, completed: false });
// ctx.auth: check the authenticated user
const identity = await ctx.auth.getUserIdentity();
// ctx.scheduler: schedule functions for later
await ctx.scheduler.runAfter(0, internal.notifications.send, { taskId });
return taskId;
},
});
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Properties
db
• db: GenericDatabaseWriter<DataModel>
A utility for reading and writing data in the database.
Use ctx.db.insert(), ctx.db.patch(), ctx.db.replace(), and
ctx.db.delete() to write data. Use ctx.db.get() and ctx.db.query()
to read data. All operations within a mutation are atomic.
Defined in
auth
• auth: Auth
Information about the currently authenticated user.
Call await ctx.auth.getUserIdentity() to get the current user's identity,
or null if the user is not authenticated.
Defined in
storage
• storage: StorageWriter
A utility for reading and writing files in storage.
Use ctx.storage.generateUploadUrl() to create an upload URL for clients,
ctx.storage.getUrl(storageId) to get a URL for a stored file,
or ctx.storage.delete(storageId) to remove one.
Defined in
scheduler
• scheduler: Scheduler
A utility for scheduling Convex functions to run in the future.
Example
// Schedule an action to run immediately after this mutation commits:
await ctx.scheduler.runAfter(0, internal.emails.sendWelcome, { userId });
// Schedule a cleanup to run in 24 hours:
await ctx.scheduler.runAfter(24 * 60 * 60 * 1000, internal.tasks.cleanup, {});
Defined in
runQuery
• runQuery: <Query>(query: Query, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>
Type declaration
▸ <Query>(query, ...args): Promise<FunctionReturnType<Query>>
Call a query function within the same transaction.
The query runs within the same transaction as the calling mutation,
seeing a consistent snapshot of the database. Requires a
FunctionReference (e.g., api.myModule.myQuery or
internal.myModule.myQuery).
NOTE: Often you can extract shared logic into a helper function instead.
runQuery incurs overhead of running argument and return value validation,
and creating a new isolated JS context.
Example
const user = await ctx.runQuery(internal.users.getUser, { userId });
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query", "public" | "internal"> |
Parameters
| Name | Type |
|---|---|
query | Query |
...args | OptionalRestArgs<Query> |
Returns
Promise<FunctionReturnType<Query>>
Defined in
runMutation
• runMutation: <Mutation>(mutation: Mutation, ...args: OptionalRestArgs<Mutation>) => Promise<FunctionReturnType<Mutation>>
Type declaration
▸ <Mutation>(mutation, ...args): Promise<FunctionReturnType<Mutation>>
Call a mutation function within the same transaction.
The mutation runs in a sub-transaction, so if it throws an error, all of its writes will be rolled back. Requires a FunctionReference.
NOTE: Often you can extract shared logic into a helper function instead.
runMutation incurs overhead of running argument and return value
validation, and creating a new isolated JS context.
Type parameters
| Name | Type |
|---|---|
Mutation | extends FunctionReference<"mutation", "public" | "internal"> |
Parameters
| Name | Type |
|---|---|
mutation | Mutation |
...args | OptionalRestArgs<Mutation> |
Returns
Promise<FunctionReturnType<Mutation>>