Migration Script

// Template
module.exports = {
  async up(db) {
    await db.collection('orders').updateMany(
      { status: { $exists: false } },
      { $set: { status: 'pending' } }
    );
  },
  async down(db) {
    await db.collection('orders').updateMany(
      { status: 'pending' },
      { $unset: { status: '' } }
    );
  },
};

Step 3 — Handle Data Transformation

• For field renames: copy data to new field, verify, then unset old field.
• For type changes: cast values explicitly; handle nulls and edge cases.
• For large collections: use cursor-based iteration with batch size to control memory.
• Never drop a collection in up — archive or rename instead.

Step 4 — Test on Local Docker MongoDB

• Start local MongoDB: docker compose up -d mongo.
• Seed with representative data (use seed-data skill if needed).
• Run the migration: node src/migrations/<file>.js up.
• Verify with a quick query or count check.
• Run rollback: node src/migrations/<file>.js down.
• Confirm data is restored to pre-migration state.

Step 5 — Document in Changelog

• Add an entry to the project changelog or state/STATE.md describing the migration.
• Note any manual steps required (e.g., Atlas index builds).
• Record the migration order if multiple migrations are pending.
• Update state/AI_AGENT_HANDOFF.md if the migration affects other agents' work.

Checklist

• up and down functions both implemented.
• Bulk operations used for large collections.
• Tested locally against Docker MongoDB.
• Rollback verified.
• Changelog / state/STATE.md updated.