Add migration system for schema evolution

[Copilot]

Implements a migration framework to handle Casbin schema changes with transaction support, rollback capability, and automatic verification before adapter operations.

Implementation

Core Migration System

• MigrationManager class handles migration execution, tracking, and rollback
• Migrations stored in casbin_migrations collection with ID, description, and timestamp
• Transaction support when using MongoDB replica sets; automatic rollback on failure
• Initial baseline migration (001_initial_schema) marks current schema state

Adapter Integration

• runMigrations() - Execute pending migrations
• rollbackMigration() - Revert last applied migration
• getMigrationStatus() - Query migration state
• ensureMigrations() - Auto-called before loadPolicy() to enforce schema currency
• skipMigrations: true option to disable system

Migration Structure

const migration = {
  id: '002_add_tenant_field',
  description: 'Add multi-tenancy support',
  up: async (connection, session) => {
    const CasbinRule = connection.models.CasbinRule;
    await CasbinRule.updateMany(
      { tenant: { $exists: false } },
      { $set: { tenant: 'default' } },
      session ? { session } : {}
    );
  },
  down: async (connection, session) => {
    const CasbinRule = connection.models.CasbinRule;
    await CasbinRule.updateMany(
      {},
      { $unset: { tenant: '' } },
      session ? { session } : {}
    );
  }
};

Usage

const adapter = await MongooseAdapter.newAdapter('mongodb://localhost/casbin');
await adapter.runMigrations();  // Apply pending migrations

// Or disable auto-check
const adapter = await MongooseAdapter.newAdapter(uri, {}, { skipMigrations: true });

Testing

• Unit tests for MigrationManager (11 cases)
• Integration tests for execution, transactions, and rollback (20 cases)
• CLI tool (examples/migrate.js) for migration management
• Complete documentation in MIGRATIONS.md with examples

Backward Compatibility

No breaking changes. Migration system is opt-out via skipMigrations: true.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Create a migration feature for Casbin schema changes</issue_title>
<issue_description>Following up the discussion had here, mongoose adapter needs a way to adapt possible schema changes to ensure that previous users of the adapter have a possibility reliable and documented way to upgrade to a new version.

This requires some thinking and design. However the bare minimum should involve:

1. Migrations are done via transactions if available.
2. You should be able to downgrade a migration as well. Incase there are some something goes wrong.
3. Adapter should probably check that each migration is done before being operational.
4. Migrations should be put under tests.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Create a migration feature for Casbin schema changes #63

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[hsluoyz]

@nodece @Shivansh-yadav13 please review

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}