git.stella-ops.org/docs/airgap/vex-raw-migration-rollback.md

VEX Raw Migration Rollback Guide

This document describes how to rollback migrations applied to the vex_raw collection.

Migration: 20251127-vex-raw-idempotency-indexes

Description

Adds unique idempotency indexes to enforce content-addressed storage:

• idx_provider_sourceUri_digest_unique: Prevents duplicate documents from same provider/source
• idx_digest_providerId: Optimizes evidence queries by digest
• idx_retrievedAt: Supports time-based queries and future TTL operations

Rollback Steps

Option 1: MongoDB Shell

// Connect to your MongoDB instance
mongosh "mongodb://localhost:27017/excititor"

// Drop the idempotency indexes
db.vex_raw.dropIndex("idx_provider_sourceUri_digest_unique")
db.vex_raw.dropIndex("idx_digest_providerId")
db.vex_raw.dropIndex("idx_retrievedAt")

// Verify indexes are dropped
db.vex_raw.getIndexes()

Option 2: Programmatic Rollback (C#)

using StellaOps.Excititor.Storage.Mongo.Migrations;

// Get the database instance
var database = client.GetDatabase("excititor");

// Execute rollback
await database.RollbackIdempotencyIndexesAsync(cancellationToken);

// Verify rollback
var verified = await database.VerifyIdempotencyIndexesExistAsync(cancellationToken);
Console.WriteLine($"Indexes exist after rollback: {verified}"); // Should be false

Option 3: MongoDB Compass

1. Connect to your MongoDB instance
2. Navigate to the excititor database
3. Select the vex_raw collection
4. Go to the "Indexes" tab
5. Click "Drop Index" for each of:
   • idx_provider_sourceUri_digest_unique
   • idx_digest_providerId
   • idx_retrievedAt

Impact of Rollback

Before rollback (indexes present):

• Documents are prevented from being duplicated
• Evidence queries are optimized
• Unique constraint enforced

After rollback (indexes dropped):

• Duplicate documents may be inserted
• Evidence queries may be slower
• No unique constraint enforcement

Re-applying the Migration

To re-apply the migration after rollback:

// MongoDB shell
db.vex_raw.createIndex(
  { "providerId": 1, "sourceUri": 1, "digest": 1 },
  { unique: true, name: "idx_provider_sourceUri_digest_unique", background: true }
)

db.vex_raw.createIndex(
  { "digest": 1, "providerId": 1 },
  { name: "idx_digest_providerId", background: true }
)

db.vex_raw.createIndex(
  { "retrievedAt": 1 },
  { name: "idx_retrievedAt", background: true }
)

Or run the migration runner:

stellaops excititor migrate --run 20251127-vex-raw-idempotency-indexes

Migration: 20251125-vex-raw-json-schema

Description

Adds a JSON Schema validator to the vex_raw collection with validationAction: warn.

Rollback Steps

// MongoDB shell - remove the validator
db.runCommand({
  collMod: "vex_raw",
  validator: {},
  validationAction: "off",
  validationLevel: "off"
})

// Verify validator is removed
db.getCollectionInfos({ name: "vex_raw" })[0].options

Impact of Rollback

• Documents will no longer be validated against the schema
• Invalid documents may be inserted
• Existing documents are not affected

General Rollback Guidelines

1. Always backup first: Create a backup before any rollback operation
2. Test in staging: Verify rollback procedure in a non-production environment
3. Monitor performance: Watch for query performance changes after rollback
4. Document changes: Log all rollback operations for audit purposes

Troubleshooting

Index Drop Fails

If you see "IndexNotFound" errors, the index may have already been dropped or was never created:

// Check existing indexes
db.vex_raw.getIndexes()

Validator Removal Fails

If the validator command fails, verify you have the correct permissions:

// Check current user roles
db.runCommand({ usersInfo: 1 })

Related Documentation

• VEX Raw Schema Validation
• MongoDB Index Management
• Excititor Architecture