create-migration_skill

Overview

This skill creates a new database migration file for the NestJS-based service and guides registration and testing. It scaffolds a migration under apps/core/src/migration/version/ using a strict v<major>.<minor>.<patch>.ts naming pattern. The generated template includes checks to keep migrations idempotent and examples for common operations like rename, transform, index creation, and deletion.

How this skill works

It generates a TypeScript migration file that receives a MongoDB Db instance and performs safe checks before modifying data. The template demonstrates patterns: early-exit when not needed, detection of already-applied changes, batch processing with a cursor, and updateMany/updateOne operations. After creating the file you register the migration in apps/core/src/migration/history.ts so it runs automatically at startup and is recorded in the mx_migration collection.

When to use it

• Changing document schemas (rename fields, remove fields)
• Adding default values or new indexed fields
• Transforming stored configuration or data formats
• Batch migrating large collections without exhausting memory
• Adding or updating indexes to enforce uniqueness

Best practices

• Name files as v<major>.<minor>.<patch>.ts and place under apps/core/src/migration/version/
• Make migrations idempotent: check existing state before applying changes
• Use cursors and for-await loops for large datasets to avoid memory issues
• Record and register each migration in apps/core/src/migration/history.ts
• Back up production data and test migrations locally with the provided vitest pattern

Example use cases

• Rename a deprecated field across posts and articles with $rename
• Populate a newly added field with default values where it is missing
• Transform configuration objects in options collection to a new schema via cursor processing
• Remove obsolete user attributes using $unset
• Create a unique index on slug to enforce uniqueness across posts