convex-mutations

name	convex-mutations
description	This skill should be used when implementing Convex mutation functions. It provides comprehensive guidelines for defining, registering, calling, and scheduling mutations, including database operations, transactions, and scheduled job patterns.

Convex Mutations Skill

This skill provides specialized guidance for implementing Convex mutation functions, including best practices for function definition, registration, database operations, and scheduling patterns.

When to Use This Skill

Use this skill when:

• Defining new mutation functions to write or modify data in the Convex database
• Performing database operations (insert, patch, replace, delete)
• Calling mutations from other Convex functions
• Scheduling future mutations with ctx.scheduler.runAfter
• Handling transactional operations
• Coordinating mutations with actions for background processing

Skill Resources

This skill includes comprehensive reference documentation in references/mutation-guidelines.md that covers:

Core Mutation Development

• Function definition syntax using the new function syntax
• Mutation registration (mutation and internalMutation)
• Argument validators and their usage
• Function calling patterns (ctx.runQuery and ctx.runMutation)
• Function references (api and internal objects)
• File-based routing for mutation paths

Database Operations

• ctx.db.insert() - Create new documents
• ctx.db.patch() - Shallow merge updates into existing documents
• ctx.db.replace() - Fully replace existing documents
• Error handling for missing documents
• Transaction semantics and consistency guarantees

Advanced Mutation Features

• Scheduling: Using ctx.scheduler.runAfter() to queue background jobs
  • Scheduling mutations and actions for future execution
  • Understanding that auth state does NOT propagate to scheduled jobs
  • Using internal functions for scheduled jobs that need privileges
  • Avoiding tight loops and respecting 10-second minimum intervals
• Transactional Behavior: Understanding mutation transactions
  • Enqueuing scheduler jobs is transactional within mutations
  • Race condition prevention through transaction boundaries

Function Composition

• Calling queries within mutations for validation
• Calling mutations from mutations
• Using return type annotations for same-file mutation calls

How to Use This Skill

1. Read the reference documentation at references/mutation-guidelines.md to understand the complete mutation patterns
2. Follow the syntax examples for defining mutation functions with proper validators
3. Use appropriate database operations (insert, patch, replace) based on your needs
4. Schedule background work using ctx.scheduler.runAfter for long-running operations
5. Remember auth state does NOT propagate to scheduled jobs; use internal functions for privileged operations
6. Leverage transactions for consistency across multiple operations

Key Mutation Guidelines

• ALWAYS include argument validators for all mutation functions
• Use ctx.db.patch() for partial updates and ctx.db.replace() for full replacements
• Use ctx.scheduler.runAfter() to schedule actions (e.g., AI responses, notifications)
• Remember that scheduled jobs have null auth state; use internal functions instead
• Mutations execute for at most 1 second and can write up to 8192 documents
• Return null implicitly if your mutation doesn't have an explicit return value
• Use return type annotations when calling mutations in the same file (TypeScript circularity workaround)

Example: Mutation with Database Operation and Scheduling

import { mutation, internalAction } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const sendMessage = mutation({
  args: {
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
  },
  handler: async (ctx, args) => {
    // Validate channel and user exist
    const channel = await ctx.db.get(args.channelId);
    if (!channel) {
      throw new Error("Channel not found");
    }

    // Insert message into database
    await ctx.db.insert("messages", {
      channelId: args.channelId,
      authorId: args.authorId,
      content: args.content,
    });

    // Schedule AI response generation (transactional)
    await ctx.scheduler.runAfter(0, internal.functions.generateResponse, {
      channelId: args.channelId,
    });

    return null;
  },
});

export const updateUserStatus = mutation({
  args: {
    userId: v.id("users"),
    status: v.string(),
  },
  handler: async (ctx, args) => {
    // Patch updates an existing document with shallow merge
    await ctx.db.patch(args.userId, {
      status: args.status,
      lastUpdated: Date.now(),
    });
    return null;
  },
});

For more detailed information and additional patterns, refer to the complete reference documentation.