Run a range of migrations

Author: Tomas Winkler

README.md

@@ -112,7 +112,7 @@ The supported commands are divided into groups according to their target, at thi
     export default migration;
     ```
 
-* `migration run` - Runs a migration script specified by file name (option `--name <file name>`), or runs multiple migration scripts in the order specified in the migration files (option `--all`).
+* `migration run` - Runs a migration script specified by file name (option `--name <file name>`), or runs multiple migration scripts in the order specified in the migration files (options `--all` or `--range`).
   * You can execute a migration against a specific project (options `--project <YOUR_PROJECT_ID> --api-key <YOUR_MANAGEMENT_API_KEY>`) or environment stored in the local configuration file (option `--environment <YOUR_ENVIRONMENT_NAME>`).
   * After each run of a migration script, the CLI logs the execution into a status file. This file holds data for the next run to prevent running the same migration script more than once. You can choose to override this behavior, for example for debugging purposes, by using the `--force` parameter.
   * You can choose whether you want to keep executing the migration scripts even if one migration script fails (option `--continue-on-error`) or whether you want to run in the debug mode (option `--debug`) and get additional information for certain issues logged into the console.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentico/kontent-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Command line interface tool that can be used for generating and running Kontent migration scripts",
   "main": "./lib/index.js",
   "types": "./lib/types/index.d.ts",

src/cmds/migration/run.ts

@@ -1,6 +1,6 @@
 import yargs from 'yargs';
 import chalk from 'chalk';
-import { getDuplicates, getSuccessfullyExecutedMigrations, getMigrationFilepath, loadMigrationFiles, loadModule, runMigration } from '../../utils/migrationUtils';
+import { getDuplicates, getSuccessfullyExecutedMigrations, getMigrationFilepath, loadMigrationFiles, loadModule, runMigration, getMigrationsWithInvalidOrder } from '../../utils/migrationUtils';
 import { fileExists, getFileWithExtension, isAllowedExtension } from '../../utils/fileUtils';
 import { environmentConfigExists, getEnvironmentsConfig } from '../../utils/environmentUtils';
 import { createManagementClient } from '../../managementClientFactory';
@@ -38,6 +38,11 @@ const runMigrationCommand: yargs.CommandModule = {
                     describe: 'Run all migration scripts in the specified order',
                     type: 'boolean',
                 },
+                range: {
+                    alias: 'r',
+                    describe: 'Run all migration scripts in the specified range, eg.: 3:5 will run migrations with the "order" property set to 3, 4 and 5',
+                    type: 'string',
+                },
                 force: {
                     alias: 'f',
                     describe: 'Enforces run of already executed scripts.',
@@ -58,6 +63,8 @@ const runMigrationCommand: yargs.CommandModule = {
                 },
             })
             .conflicts('all', 'name')
+            .conflicts('range', 'name')
+            .conflicts('all', 'range')
             .conflicts('environment', 'api-key')
             .conflicts('environment', 'project-id')
             .check((args: any) => {
@@ -66,7 +73,11 @@ const runMigrationCommand: yargs.CommandModule = {
                 }
 
                 if (!args.all) {
-                    if (args.name) {
+                    if (args.range) {
+                        if (!getRange(args.range)) {
+                            throw new Error(chalk.red(`The range has to be a string of a format "number:number" where the first number is less or equal to the second, eg.: "2:5".`));
+                        }
+                    } else if (args.name) {
                         if (!isAllowedExtension(args.name)) {
                             throw new Error(chalk.red(`File ${args.name} has not supported extension.`));
                         }
@@ -76,7 +87,7 @@ const runMigrationCommand: yargs.CommandModule = {
                             throw new Error(chalk.red(`Cannot find the specified migration script: ${migrationFilePath}.`));
                         }
                     } else {
-                        throw new Error(chalk.red('Either the migration script name or all migration options needs to be specified.'));
+                        throw new Error(chalk.red('Either the migration script name, range or all migration options needs to be specified.'));
                     }
                 }
 
@@ -99,6 +110,7 @@ const runMigrationCommand: yargs.CommandModule = {
         let apiKey = argv.apiKey;
         const migrationName = argv.name;
         const runAll = argv.all;
+        const runRange = getRange(argv.range);
         const debugMode = argv.debug;
         const continueOnError = argv.continueOnError;
         let migrationsResults: number = 0;
@@ -119,10 +131,15 @@ const runMigrationCommand: yargs.CommandModule = {
 
         loadMigrationsExecutionStatus();
 
-        if (runAll) {
+        if (runAll || runRange) {
             let migrationsToRun = await loadMigrationFiles();
 
             checkForDuplicates(migrationsToRun);
+            checkForInvalidOrder(migrationsToRun);
+
+            if (runRange) {
+                migrationsToRun = getMigrationsByRange(migrationsToRun, runRange);
+            }
 
             if (runForce) {
                 console.log('Skipping to check already executed migrations');
@@ -165,6 +182,17 @@ const runMigrationCommand: yargs.CommandModule = {
     },
 };
 
+export const getRange = (range: string): [number, number] | null => {
+    const match = range.match(/^([0-9]+):([0-9]+)$/);
+    if (!match) {
+        return null;
+    }
+    const from = Number(match[1]);
+    const to = Number(match[2]);
+
+    return from <= to ? [from, to] : null;
+};
+
 const checkForDuplicates = (migrationsToRun: IMigration[]): void => {
     const duplicateMigrationsOrder = getDuplicates(migrationsToRun, (migration) => migration.module.order);
 
@@ -176,6 +204,29 @@ const checkForDuplicates = (migrationsToRun: IMigration[]): void => {
     }
 };
 
+const getMigrationsByRange = (migrationsToRun: IMigration[], range: [number, number]): IMigration[] => {
+    const migrations: IMigration[] = [];
+
+    for (const migration of migrationsToRun) {
+        if (migration.module.order >= range[0] && migration.module.order <= range[1]) {
+            migrations.push(migration);
+        }
+    }
+
+    return migrations.filter(String);
+};
+
+const checkForInvalidOrder = (migrationsToRun: IMigration[]): void => {
+    const migrationsWithInvalidOrder: IMigration[] = getMigrationsWithInvalidOrder(migrationsToRun);
+
+    if (migrationsWithInvalidOrder.length > 0) {
+        console.log('Migration order has to be positive integer or zero:');
+        migrationsWithInvalidOrder.map((migration) => console.error(chalk.red(`Migration: ${migration.name} order: ${migration.module.order}`)));
+
+        process.exit(1);
+    }
+};
+
 const skipExecutedMigrations = (migrations: IMigration[], projectId: string): IMigration[] => {
     const executedMigrations = getSuccessfullyExecutedMigrations(migrations, projectId);
     const result: IMigration[] = [];

src/index.ts

@@ -16,6 +16,7 @@ const createMigrationTool = (): number => {
         .example('kontent', 'migration run --name migration01 --project-id <YOUR_PROJECT_ID> --api-key <YOUR_MANAGEMENT_API_KEY>')
         .example('kontent', 'migration run --name migration01 --environment DEV --debug true')
         .example('kontent', 'migration run --all --environment DEV')
+        .example('kontent', 'migration run --range 1:4 --environment DEV')
 
         .example('kontent', 'backup --action backup --project-id <YOUR_PROJECT_ID> --api-key <YOUR_MANAGEMENT_API_KEY>')
         .example('kontent', 'backup --action backup --environment <YOUR_ENVIRONMENT>')

src/tests/invalidOrderMigration.test.ts

@@ -0,0 +1,66 @@
+import { getMigrationsWithInvalidOrder } from '../utils/migrationUtils';
+
+describe('Detection of invalid orders', () => {
+    it('Finds migrations with invalid order', () => {
+        const migrations = [
+            {
+                module: {
+                    order: -1,
+                },
+                name: 'test',
+            },
+            {
+                module: {
+                    order: 1.1,
+                },
+                name: 'test',
+            },
+            {
+                module: {
+                    order: 2,
+                },
+                name: 'test',
+            },
+            {
+                module: {
+                    order: 'aaa',
+                },
+                name: 'test',
+            },
+        ];
+
+        const result = getMigrationsWithInvalidOrder(migrations);
+
+        expect(result.length).toBe(3);
+        expect(result[0].module.order).toBe(-1);
+        expect(result[1].module.order).toBe(1.1);
+        expect(result[2].module.order).toBe('aaa');
+    });
+
+    it('No invalid order is found', () => {
+        const migrations = [
+            {
+                module: {
+                    order: 1,
+                    name: 'test',
+                },
+            },
+            {
+                module: {
+                    order: 2,
+                    name: 'test',
+                },
+            },
+            {
+                module: {
+                    order: 3,
+                    name: 'test',
+                },
+            },
+        ];
+
+        const result = getMigrationsWithInvalidOrder(migrations);
+
+        expect(result.length).toBe(0);
+    });
+});

src/utils/migrationUtils.ts

@@ -139,6 +139,18 @@ export const getDuplicates = <T extends any>(array: T[], key: (obj: T) => number
     return duplicates;
 };
 
+export const getMigrationsWithInvalidOrder = <T extends any>(array: T[]): T[] => {
+    const migrationsWithInvalidOrder: T[] = [];
+
+    for (const migration of array) {
+        if (!Number.isInteger(migration.module.order) || Number(migration.module.order) < 0) {
+            migrationsWithInvalidOrder.push(migration);
+        }
+    }
+
+    return migrationsWithInvalidOrder;
+};
+
 export const loadModule = async (migrationFile: string): Promise<MigrationModule> => {
     const migrationPath = getMigrationFilepath(migrationFile);
 
@@ -158,9 +170,7 @@ export const loadMigrationFiles = async (): Promise<IMigration[]> => {
     const files = listFiles('.js');
 
     for (const file of files) {
-        const migrationModule = await loadModule(file.name);
-
-        migrations.push({ name: file.name, module: migrationModule });
+        migrations.push({ name: file.name, module: await loadModule(file.name) });
     }
 
     return migrations.filter(String);

tsconfig.json

@@ -3,7 +3,8 @@
     "target": "es6",
     "module": "commonjs",
     "lib": [
-      "esnext"
+      "esnext",
+      "DOM"
     ],
     "sourceMap": true,
     "allowJs": true,