@ftschopp/dynatable-migrations 1.0.0 → 1.2.0

package/src/core/tracker.ts

@@ -1,12 +1,22 @@
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { PutCommand, GetCommand, QueryCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  PutCommand,
+  GetCommand,
+  QueryCommand,
+  UpdateCommand,
+  DeleteCommand,
+  TransactWriteCommand,
+} from '@aws-sdk/lib-dynamodb';
 import { MigrationTracker, MigrationRecord, SchemaChange, MigrationConfig } from '../types';
 
+const LOCK_TTL_SECONDS = 300; // 5 minutes
+
 export class DynamoDBMigrationTracker implements MigrationTracker {
   private client: DynamoDBDocumentClient;
   private tableName: string;
   private trackingPrefix: string;
   private gsi1Name: string;
+  private lockId: string | null = null;
 
   constructor(client: DynamoDBDocumentClient, config: MigrationConfig) {
     this.client = client;
@@ -36,18 +46,104 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     }
   }
 
+  /**
+   * Acquire a distributed lock to prevent concurrent migrations
+   */
+  async acquireLock(): Promise<boolean> {
+    const lockKey = {
+      PK: `${this.trackingPrefix}#LOCK`,
+      SK: `${this.trackingPrefix}#LOCK`,
+    };
+
+    const now = Date.now();
+    const expiresAt = now + LOCK_TTL_SECONDS * 1000;
+    this.lockId = `lock-${now}-${Math.random().toString(36).substring(7)}`;
+
+    try {
+      await this.client.send(
+        new PutCommand({
+          TableName: this.tableName,
+          Item: {
+            ...lockKey,
+            lockId: this.lockId,
+            acquiredAt: new Date().toISOString(),
+            expiresAt,
+          },
+          // Only succeed if lock doesn't exist or has expired
+          ConditionExpression:
+            'attribute_not_exists(PK) OR expiresAt < :now',
+          ExpressionAttributeValues: {
+            ':now': now,
+          },
+        })
+      );
+      return true;
+    } catch (error: any) {
+      if (error.name === 'ConditionalCheckFailedException') {
+        this.lockId = null;
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Release the distributed lock
+   */
+  async releaseLock(): Promise<void> {
+    if (!this.lockId) return;
+
+    const lockKey = {
+      PK: `${this.trackingPrefix}#LOCK`,
+      SK: `${this.trackingPrefix}#LOCK`,
+    };
+
+    try {
+      await this.client.send(
+        new DeleteCommand({
+          TableName: this.tableName,
+          Key: lockKey,
+          // Only delete if we own the lock
+          ConditionExpression: 'lockId = :lockId',
+          ExpressionAttributeValues: {
+            ':lockId': this.lockId,
+          },
+        })
+      );
+    } catch (error: any) {
+      // Lock may have expired or been taken by someone else
+      if (error.name !== 'ConditionalCheckFailedException') {
+        throw error;
+      }
+    } finally {
+      this.lockId = null;
+    }
+  }
+
+  /**
+   * Get all applied migrations with pagination support
+   */
   async getAppliedMigrations(): Promise<MigrationRecord[]> {
-    const result = await this.client.send(
-      new QueryCommand({
-        TableName: this.tableName,
-        KeyConditionExpression: 'PK = :pk',
-        ExpressionAttributeValues: {
-          ':pk': this.trackingPrefix,
-        },
-      })
-    );
+    const items: MigrationRecord[] = [];
+    let lastKey: Record<string, any> | undefined;
+
+    do {
+      const result = await this.client.send(
+        new QueryCommand({
+          TableName: this.tableName,
+          KeyConditionExpression: 'PK = :pk',
+          ExpressionAttributeValues: {
+            ':pk': this.trackingPrefix,
+          },
+          ExclusiveStartKey: lastKey,
+        })
+      );
+
+      items.push(...((result.Items || []) as MigrationRecord[]));
+      lastKey = result.LastEvaluatedKey;
+    } while (lastKey);
 
-    return (result.Items || []) as MigrationRecord[];
+    return items;
   }
 
   async getCurrentVersion(): Promise<string | null> {
@@ -64,70 +160,138 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
     return result.Item?.currentVersion || null;
   }
 
+  /**
+   * Mark migration as applied using TransactWrite for atomicity
+   * Handles both new migrations and re-applying rolled back migrations
+   */
   async markAsApplied(
     version: string,
     name: string,
     schemaDefinition?: Record<string, any>,
-    schemaChanges?: SchemaChange[]
+    schemaChanges?: SchemaChange[],
+    checksum?: string
   ): Promise<void> {
     const now = new Date().toISOString();
 
-    // Create migration record
-    await this.client.send(
-      new PutCommand({
-        TableName: this.tableName,
-        Item: {
-          PK: this.trackingPrefix,
-          SK: version,
-          version,
-          name,
-          timestamp: now,
-          appliedAt: now,
-          status: 'applied',
-          schemaDefinition,
-          schemaChanges,
-        } as MigrationRecord,
-      })
-    );
+    // Check if migration record already exists (e.g., rolled back or failed)
+    const existing = await this.getMigration(version);
 
-    // Update current version pointer
-    await this.client.send(
-      new UpdateCommand({
-        TableName: this.tableName,
-        Key: {
-          PK: `${this.trackingPrefix}#CURRENT`,
-          SK: `${this.trackingPrefix}#CURRENT`,
-        },
-        UpdateExpression: 'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
-        ExpressionAttributeValues: {
-          ':version': version,
-          ':updatedAt': now,
-          ':gsi1sk': version,
-        },
-      })
-    );
+    if (existing) {
+      // Update existing record (re-applying a rolled back or failed migration)
+      // Build dynamic update expression - DynamoDB doesn't accept undefined values
+      const setParts = ['#status = :status', 'appliedAt = :appliedAt', '#name = :name'];
+      const expressionValues: Record<string, any> = {
+        ':status': 'applied',
+        ':appliedAt': now,
+        ':name': name,
+      };
+
+      if (schemaDefinition !== undefined) {
+        setParts.push('schemaDefinition = :schemaDef');
+        expressionValues[':schemaDef'] = schemaDefinition;
+      }
+      if (schemaChanges !== undefined) {
+        setParts.push('schemaChanges = :schemaChanges');
+        expressionValues[':schemaChanges'] = schemaChanges;
+      }
+      if (checksum !== undefined) {
+        setParts.push('checksum = :checksum');
+        expressionValues[':checksum'] = checksum;
+      }
+
+      await this.client.send(
+        new TransactWriteCommand({
+          TransactItems: [
+            {
+              Update: {
+                TableName: this.tableName,
+                Key: {
+                  PK: this.trackingPrefix,
+                  SK: version,
+                },
+                UpdateExpression: `SET ${setParts.join(', ')} REMOVE #error, failedAt, rolledBackAt`,
+                ExpressionAttributeNames: {
+                  '#status': 'status',
+                  '#name': 'name',
+                  '#error': 'error',
+                },
+                ExpressionAttributeValues: expressionValues,
+                // Only allow re-applying if not currently applied
+                ConditionExpression: '#status <> :status',
+              },
+            },
+            {
+              Update: {
+                TableName: this.tableName,
+                Key: {
+                  PK: `${this.trackingPrefix}#CURRENT`,
+                  SK: `${this.trackingPrefix}#CURRENT`,
+                },
+                UpdateExpression:
+                  'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+                ExpressionAttributeValues: {
+                  ':version': version,
+                  ':updatedAt': now,
+                  ':gsi1sk': version,
+                },
+              },
+            },
+          ],
+        })
+      );
+    } else {
+      // Create new migration record
+      await this.client.send(
+        new TransactWriteCommand({
+          TransactItems: [
+            {
+              Put: {
+                TableName: this.tableName,
+                Item: {
+                  PK: this.trackingPrefix,
+                  SK: version,
+                  version,
+                  name,
+                  timestamp: now,
+                  appliedAt: now,
+                  status: 'applied',
+                  schemaDefinition,
+                  schemaChanges,
+                  checksum,
+                } as MigrationRecord,
+                // Ensure migration wasn't already applied
+                ConditionExpression: 'attribute_not_exists(PK)',
+              },
+            },
+            {
+              Update: {
+                TableName: this.tableName,
+                Key: {
+                  PK: `${this.trackingPrefix}#CURRENT`,
+                  SK: `${this.trackingPrefix}#CURRENT`,
+                },
+                UpdateExpression:
+                  'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+                ExpressionAttributeValues: {
+                  ':version': version,
+                  ':updatedAt': now,
+                  ':gsi1sk': version,
+                },
+              },
+            },
+          ],
+        })
+      );
+    }
   }
 
+  /**
+   * Mark migration as rolled back using TransactWrite for atomicity
+   */
   async markAsRolledBack(version: string): Promise<void> {
-    await this.client.send(
-      new UpdateCommand({
-        TableName: this.tableName,
-        Key: {
-          PK: this.trackingPrefix,
-          SK: version,
-        },
-        UpdateExpression: 'SET #status = :status, rolledBackAt = :timestamp',
-        ExpressionAttributeNames: {
-          '#status': 'status',
-        },
-        ExpressionAttributeValues: {
-          ':status': 'rolled_back',
-          ':timestamp': new Date().toISOString(),
-        },
-      })
-    );
+    const now = new Date().toISOString();
 
-    // Find previous version and update current pointer
+    // Find previous version
     const migrations = await this.getAppliedMigrations();
     const appliedMigrations = migrations
       .filter((m) => m.status === 'applied' && m.version !== version)
@@ -135,43 +299,91 @@ export class DynamoDBMigrationTracker implements MigrationTracker {
 
     const previousVersion = appliedMigrations[0]?.version || 'v0000';
 
+    // Use TransactWrite to atomically update record and pointer
     await this.client.send(
-      new UpdateCommand({
-        TableName: this.tableName,
-        Key: {
-          PK: `${this.trackingPrefix}#CURRENT`,
-          SK: `${this.trackingPrefix}#CURRENT`,
-        },
-        UpdateExpression: 'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
-        ExpressionAttributeValues: {
-          ':version': previousVersion,
-          ':updatedAt': new Date().toISOString(),
-          ':gsi1sk': previousVersion,
-        },
+      new TransactWriteCommand({
+        TransactItems: [
+          {
+            Update: {
+              TableName: this.tableName,
+              Key: {
+                PK: this.trackingPrefix,
+                SK: version,
+              },
+              UpdateExpression: 'SET #status = :status, rolledBackAt = :timestamp',
+              ExpressionAttributeNames: {
+                '#status': 'status',
+              },
+              ExpressionAttributeValues: {
+                ':status': 'rolled_back',
+                ':timestamp': now,
+              },
+            },
+          },
+          {
+            Update: {
+              TableName: this.tableName,
+              Key: {
+                PK: `${this.trackingPrefix}#CURRENT`,
+                SK: `${this.trackingPrefix}#CURRENT`,
+              },
+              UpdateExpression:
+                'SET currentVersion = :version, updatedAt = :updatedAt, GSI1SK = :gsi1sk',
+              ExpressionAttributeValues: {
+                ':version': previousVersion,
+                ':updatedAt': now,
+                ':gsi1sk': previousVersion,
+              },
+            },
+          },
+        ],
       })
     );
   }
 
   async markAsFailed(version: string, error: string): Promise<void> {
-    await this.client.send(
-      new UpdateCommand({
-        TableName: this.tableName,
-        Key: {
-          PK: this.trackingPrefix,
-          SK: version,
-        },
-        UpdateExpression: 'SET #status = :status, #error = :error, failedAt = :timestamp',
-        ExpressionAttributeNames: {
-          '#status': 'status',
-          '#error': 'error',
-        },
-        ExpressionAttributeValues: {
-          ':status': 'failed',
-          ':error': error,
-          ':timestamp': new Date().toISOString(),
-        },
-      })
-    );
+    // Check if the migration record exists first
+    const existing = await this.getMigration(version);
+
+    if (existing) {
+      // Update existing record
+      await this.client.send(
+        new UpdateCommand({
+          TableName: this.tableName,
+          Key: {
+            PK: this.trackingPrefix,
+            SK: version,
+          },
+          UpdateExpression: 'SET #status = :status, #error = :error, failedAt = :timestamp',
+          ExpressionAttributeNames: {
+            '#status': 'status',
+            '#error': 'error',
+          },
+          ExpressionAttributeValues: {
+            ':status': 'failed',
+            ':error': error,
+            ':timestamp': new Date().toISOString(),
+          },
+        })
+      );
+    } else {
+      // Create new record for failed migration
+      await this.client.send(
+        new PutCommand({
+          TableName: this.tableName,
+          Item: {
+            PK: this.trackingPrefix,
+            SK: version,
+            version,
+            name: 'unknown',
+            status: 'failed',
+            error,
+            failedAt: new Date().toISOString(),
+            timestamp: new Date().toISOString(),
+          },
+        })
+      );
+    }
   }
 
   async recordSchemaChange(change: SchemaChange): Promise<void> {

package/src/index.ts

@@ -9,8 +9,9 @@ export * from './types';
 // Core
 export { DynamoDBMigrationTracker } from './core/tracker';
 export { MigrationLoader } from './core/loader';
-export { MigrationRunner } from './core/runner';
+export { MigrationRunner, type RunOptions } from './core/runner';
 export { ConfigLoader, loadConfig } from './core/config';
+export { createDynamoDBClient } from './core/client';
 
 // Template
 export { generateMigrationTemplate } from './templates/migration';

package/src/types/index.ts

@@ -138,6 +138,16 @@ export interface MigrationTracker {
    */
   getCurrentVersion(): Promise<string | null>;
 
+  /**
+   * Acquire a distributed lock
+   */
+  acquireLock(): Promise<boolean>;
+
+  /**
+   * Release the distributed lock
+   */
+  releaseLock(): Promise<void>;
+
   /**
    * Mark migration as applied
    */
@@ -145,7 +155,8 @@ export interface MigrationTracker {
     version: string,
     name: string,
     schemaDefinition?: Record<string, any>,
-    schemaChanges?: SchemaChange[]
+    schemaChanges?: SchemaChange[],
+    checksum?: string
   ): Promise<void>;
 
   /**
@@ -182,6 +193,7 @@ export interface MigrationFile {
   name: string;
   filePath: string;
   migration: Migration;
+  checksum?: string;
 }
 
 /**