convex-mutations_skill

Overview

This skill gives practical guidance for implementing Convex mutation functions focused on correctness, safety, and scheduling. It covers defining and registering mutations, validator usage, common database operations, transaction semantics, and scheduling background jobs. Use it to standardize mutation patterns and avoid common pitfalls.

How this skill works

The skill inspects mutation design and behavior: how functions are declared and registered, what validators are applied, and which ctx.db operations are used (insert, patch, replace, delete). It explains transaction boundaries and how scheduled jobs are enqueued with ctx.scheduler.runAfter, including auth propagation and internal-function patterns. It also covers calling queries and other mutations for validation and composition.

When to use it

• Creating or updating server-side mutation functions that change Convex data
• Performing database operations: insert, patch (shallow merge), replace, or delete
• Scheduling future work or background jobs with ctx.scheduler.runAfter
• Coordinating transactional updates and queued tasks to avoid race conditions
• Calling queries within mutations for validation or invoking other mutations/actions

Best practices

• Always declare argument validators for every mutation to enforce input shape and prevent runtime errors
• Choose ctx.db.insert for new documents, ctx.db.patch for partial updates, and ctx.db.replace for full replacements
• Keep mutations short and synchronous; they run with a ~1 second execution window and can write up to the platform limit of documents
• Enqueue scheduled jobs with ctx.scheduler.runAfter inside the same transaction to ensure atomicity of enqueuing and DB changes
• Use internal (privileged) functions for scheduled jobs because scheduled executions receive null auth state
• Annotate return types when calling mutations in the same file to avoid circular TypeScript issues

Example use cases

• Insert a message document and schedule an AI response generation job immediately after the insert
• Patch a user profile to update status and lastUpdated timestamp without replacing the whole document
• Replace a configuration document when deploying a full new settings object
• Schedule periodic background cleanup tasks using runAfter with safe minimum intervals and internal privileges
• Call a validation query from a mutation before performing a multi-document transaction to ensure referential integrity