up

docs/airgap/vex-raw-migration-rollback.md

@@ -0,0 +1,154 @@
+# 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
+
+```javascript
+// 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#)
+
+```csharp
+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:
+
+```javascript
+// 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:
+
+```bash
+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
+
+```javascript
+// 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:
+
+```javascript
+// Check existing indexes
+db.vex_raw.getIndexes()
+```
+
+### Validator Removal Fails
+
+If the validator command fails, verify you have the correct permissions:
+
+```javascript
+// Check current user roles
+db.runCommand({ usersInfo: 1 })
+```
+
+## Related Documentation
+
+- [VEX Raw Schema Validation](vex-raw-schema-validation.md)
+- [MongoDB Index Management](https://www.mongodb.com/docs/manual/indexes/)
+- [Excititor Architecture](../modules/excititor/architecture.md)