Data Migrations

The Data Migrations system manages database schema evolution and data transformations in Wrkbelt. Built on NestJS and Mongoose, it provides a robust framework for tracking and executing database changes.

Entity Relationship Diagram

Key Features

Migration Tracking

• Unique Names: Each migration has a unique identifier (e.g., 001_seed-users_and_rbac)
• Status Management: Tracks migration states (pending, completed, rolled_back, failed)
• Execution Metrics: Records execution time and completion status
• Timestamps: Automatic tracking of creation and update times

Migration Scripts

• Dependency Injection: Full access to NestJS dependency injection system
• Type Safety: TypeScript interfaces ensure consistent migration structure
• Bidirectional: Support for both up() and down() operations
• Logging: Built-in logger for tracking migration progress

Implementation Details

Migration Interface

interface MigrationInterface {
  unique_name: string;     // Unique identifier
  description: string;     // Purpose description
  logger: Logger;          // NestJS logger
  up(): Promise<void>;     // Forward migration
  down(): Promise<void>;   // Rollback migration
}

Migration States

• pending: Migration hasn't been executed
• completed: Successfully executed
• rolled_back: Successfully reversed
• failed: Execution failed, needs attention

Example Migration

@Injectable()
export class SeedUsersAndRBAC implements MigrationInterface {
  public readonly unique_name = '001_seed-users-and-rbac';
  public readonly description = 'Seeds initial users and RBAC data';
  
  constructor(
    private userService: UserService,
    private roleService: RoleService
  ) {}

  async up(): Promise<void> {
    // Forward migration logic
  }

  async down(): Promise<void> {
    // Rollback logic
  }
}

Design Principles

1. Atomicity

   • Each migration is a single, atomic operation
   • Rollback support for failed migrations
   • Transaction support where possible

2. Dependency Management

   • NestJS dependency injection
   • Service-based operations
   • Clean separation of concerns

3. Reliability

   • Status tracking
   • Error handling
   • Execution metrics
   • Detailed logging

4. Maintainability

   • Clear naming conventions
   • Descriptive metadata
   • Version control friendly
   • Self-documenting structure