155 lines
4.0 KiB
Markdown
155 lines
4.0 KiB
Markdown
# 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)
|