@forge/sql 2.0.1-next.0 → 2.1.0-next.2

package/README.md

@@ -2,11 +2,20 @@ Library for Forge environment.
 
 Usage example:
 ```typescript
-import sql from "@forge/sql";
+import sql, { migrationRunner } from "@forge/sql";
 
-const result = await sql.executeRaw('SELECT * FROM example');
+const migrationResults = await migrationRunner
+  .enqueue(
+    'v001_create_example_table',
+    `CREATE TABLE IF NOT EXISTS example (id INT PRIMARY KEY AUTOINCREMENT,name TEXT NOT NULL);`
+  )
+  .enqueue('v002_alter_example_table_add_age', `ALTER TABLE example ADD COLUMN age INT NOT NULL;`)
+  .enqueue('v003_alter_example_table_add_index_age', `CREATE INDEX idx_example_age ON example (age);`)
+  .run();
 
-const statement = sql.prepare('INSERT INTO test VALUES (?, ?)');
+const listExamples = await sql.executeRaw('SELECT * FROM example');
 
-const result = await statement.bindParams('John Doe', 42).execute();
+const statement = sql.prepare('INSERT INTO test example(name, age) VALUES (?, ?)');
+
+const insertUserResult = await statement.bindParams('John Doe', 42).execute();
 ```

package/out/__test__/migration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=migration.test.d.ts.map

package/out/__test__/migration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.test.d.ts","sourceRoot":"","sources":["../../src/__test__/migration.test.ts"],"names":[],"mappings":""}

package/out/__test__/migration.test.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const migration_1 = require("../migration");
+const sql_1 = require("../sql");
+const errorCodes_1 = require("../errorCodes");
+const jest_when_1 = require("jest-when");
+const sql_statement_1 = require("../sql-statement");
+jest.mock('../sql');
+describe('Migration', () => {
+    let migrationRunner;
+    let mockSqlClient;
+    beforeEach(() => {
+        mockSqlClient = new sql_1.SqlClient();
+        migrationRunner = new migration_1.MigrationRunner(mockSqlClient);
+    });
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('enqueueMigration', () => {
+        const versionOne = 'v001_create_table_testtest';
+        it('should store just one migration with the same name already exists', () => {
+            const createTableTest = 'CREATE TABLE test (id INT)';
+            migrationRunner.enqueue(versionOne, createTableTest);
+            migrationRunner.enqueue(versionOne, createTableTest);
+            expect(migrationRunner.getEnqueued().length).toBe(1);
+            expect(migrationRunner.getEnqueued()[0].name).toBe(versionOne);
+            expect(migrationRunner.getEnqueued()[0].statement).toBe(createTableTest);
+        });
+        it('should not throw an error if a migration names are unique, even when sql statements with the same name already exists', () => {
+            const versionTwo = 'v002_alter_table_test_add_column_foo';
+            migrationRunner.enqueue(versionOne, 'CREATE TABLE IF NOT EXISTS test (id INT)');
+            migrationRunner.enqueue(versionTwo, 'ALTER TABLE test ADD COLUMN foo BOOLEAN DEFAULT FALSE;');
+            expect(migrationRunner.getEnqueued().length).toBe(2);
+            expect(migrationRunner.getEnqueued()[0].name).toBe(versionOne);
+            expect(migrationRunner.getEnqueued()[1].name).toBe(versionTwo);
+        });
+    });
+    describe('list', () => {
+        it('should list all previously migrations', async () => {
+            const migratedAtDate = new Date();
+            mockSqlClient.executeRaw.mockResolvedValueOnce({
+                rows: [{ id: 1, name: 'create-table-test', migratedAt: migratedAtDate }]
+            });
+            const migrations = await migrationRunner.list();
+            expect(migrations.length).toBe(1);
+            expect(migrations[0]).toEqual({ id: 1, name: 'create-table-test', migratedAt: migratedAtDate });
+            expect(mockSqlClient.executeRaw).toHaveBeenCalledWith('SELECT id, name, migratedAt FROM __migrations;');
+        });
+        it('should be empty when no previous migrations exist', async () => {
+            mockSqlClient.executeRaw.mockResolvedValueOnce({
+                rows: []
+            });
+            const migrations = await migrationRunner.list();
+            expect(migrations.length).toBe(0);
+            expect(mockSqlClient.executeRaw).toHaveBeenCalledWith('SELECT id, name, migratedAt FROM __migrations;');
+        });
+        it('should raise an error when schema version table does not exist', async () => {
+            const tableDoesNotExistError = new Error(errorCodes_1.errorCodes.SQL_EXECUTION_ERROR);
+            mockSqlClient.executeRaw.mockRejectedValue(tableDoesNotExistError);
+            await expect(migrationRunner.list()).rejects.toThrow(tableDoesNotExistError);
+        });
+    });
+    describe('run', () => {
+        const insertMigrationVersionQueryTemplate = 'INSERT INTO __migrations (name) VALUES (?);';
+        const CREATE_TABLE_FOO_QUERY = 'CREATE TABLE IF NOT EXISTS foo (id INT);';
+        const CREATE_TABLE_BAR_QUERY = 'CREATE TABLE IF NOT EXISTS bar (id INT);';
+        afterEach(() => {
+            (0, jest_when_1.verifyAllWhenMocksCalled)();
+            (0, jest_when_1.resetAllWhenMocks)();
+        });
+        describe('when few migrations have been successfully run in the past', () => {
+            it('should execute migrations that have not been previously run', async () => {
+                migrationRunner.enqueue('v_001_create_table_foo', CREATE_TABLE_FOO_QUERY);
+                migrationRunner.enqueue('v_002_create_table_bar', CREATE_TABLE_BAR_QUERY);
+                (0, jest_when_1.when)(mockSqlClient.executeRaw)
+                    .calledWith((0, jest_when_1.when)((arg) => arg.startsWith('CREATE TABLE IF NOT EXISTS __migrations')))
+                    .mockResolvedValue({ rows: [] });
+                (0, jest_when_1.when)(mockSqlClient.executeRaw)
+                    .calledWith('SELECT id, name, migratedAt FROM __migrations;')
+                    .mockResolvedValue({
+                    rows: [{ name: 'v_001_create_table_foo', statement: CREATE_TABLE_FOO_QUERY, migratedAt: new Date() }]
+                });
+                const mockApiCall = jest.fn();
+                (0, jest_when_1.when)(mockApiCall)
+                    .expectCalledWith(insertMigrationVersionQueryTemplate, (0, jest_when_1.when)((arg) => arg[0] === 'v_002_create_table_bar'))
+                    .mockResolvedValue({});
+                (0, jest_when_1.when)(mockSqlClient.prepare)
+                    .calledWith(insertMigrationVersionQueryTemplate)
+                    .mockReturnValue(new sql_statement_1.SqlStatement(insertMigrationVersionQueryTemplate, mockApiCall));
+                const result = await migrationRunner.run();
+                expect(result).toEqual(['v_002_create_table_bar']);
+                expect(mockSqlClient.prepare).toHaveBeenCalledTimes(1);
+                expect(mockSqlClient.executeRaw).toHaveBeenCalledTimes(3);
+            });
+        });
+        describe('when no migrations have been run in the past', () => {
+            it('should execute migrations that have not been previously run', async () => {
+                const CREATE_TABLE_FOO_QUERY = 'CREATE TABLE IF NOT EXISTS foo (id INT)';
+                migrationRunner.enqueue('v_001_create_table_foo', CREATE_TABLE_FOO_QUERY);
+                migrationRunner.enqueue('v_002_create_table_bar', 'CREATE TABLE IF NOT EXISTS bar (id INT)');
+                (0, jest_when_1.when)(mockSqlClient.executeRaw).calledWith('SELECT id, name, migratedAt FROM __migrations;').mockResolvedValue({
+                    rows: []
+                });
+                (0, jest_when_1.when)(mockSqlClient.executeRaw)
+                    .calledWith((0, jest_when_1.when)((arg) => arg.startsWith('CREATE TABLE IF NOT EXISTS __migrations')))
+                    .mockResolvedValue({ rows: [] });
+                const mockApiCall = jest.fn();
+                (0, jest_when_1.when)(mockApiCall)
+                    .expectCalledWith(insertMigrationVersionQueryTemplate, (0, jest_when_1.when)((arg) => arg[0] === 'v_001_create_table_foo' || arg[0] === 'v_002_create_table_bar'))
+                    .mockResolvedValue({});
+                (0, jest_when_1.when)(mockSqlClient.prepare)
+                    .calledWith(insertMigrationVersionQueryTemplate)
+                    .mockReturnValue(new sql_statement_1.SqlStatement(insertMigrationVersionQueryTemplate, mockApiCall));
+                const result = await migrationRunner.run();
+                expect(result).toEqual(['v_001_create_table_foo', 'v_002_create_table_bar']);
+                expect(mockSqlClient.prepare).toHaveBeenCalledTimes(2);
+                expect(mockSqlClient.executeRaw).toHaveBeenCalledTimes(4);
+            });
+        });
+    });
+});

package/out/index.d.ts

@@ -1,5 +1,6 @@
 import { sql } from './sql';
 import { errorCodes } from './errorCodes';
-export { errorCodes };
+import { migrationRunner } from './migration';
+export { errorCodes, migrationRunner, sql };
 export default sql;
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,eAAe,GAAG,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC;AAC5C,eAAe,GAAG,CAAC"}

package/out/index.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.errorCodes = void 0;
+exports.sql = exports.migrationRunner = exports.errorCodes = void 0;
 const sql_1 = require("./sql");
+Object.defineProperty(exports, "sql", { enumerable: true, get: function () { return sql_1.sql; } });
 const errorCodes_1 = require("./errorCodes");
 Object.defineProperty(exports, "errorCodes", { enumerable: true, get: function () { return errorCodes_1.errorCodes; } });
+const migration_1 = require("./migration");
+Object.defineProperty(exports, "migrationRunner", { enumerable: true, get: function () { return migration_1.migrationRunner; } });
 exports.default = sql_1.sql;

package/out/migration.d.ts

@@ -0,0 +1,23 @@
+import { SqlClient } from './sql';
+declare type MigrationRecord = {
+    name: string;
+    statement: string;
+};
+declare type MigrationVersion = {
+    id: number;
+    name: string;
+    migratedAt: Date;
+};
+export declare class MigrationRunner {
+    private readonly sqlClient;
+    private readonly migrations;
+    constructor(sqlClient: SqlClient);
+    initialize(): Promise<void>;
+    enqueue(name: string, statement: string): MigrationRunner;
+    getEnqueued(): MigrationRecord[];
+    list(): Promise<MigrationVersion[]>;
+    run(): Promise<string[]>;
+}
+export declare const migrationRunner: MigrationRunner;
+export {};
+//# sourceMappingURL=migration.d.ts.map

package/out/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,aAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,aAAK,gBAAgB,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;CAClB,CAAC;AAOF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,SAAS,EAAE,SAAS;IAK1B,UAAU;IAIT,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe;IAQzD,WAAW,IAAI,eAAe,EAAE;IAIjC,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAYnC,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAiC/B;AAED,eAAO,MAAM,eAAe,iBAA2B,CAAC"}

package/out/migration.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrationRunner = exports.MigrationRunner = void 0;
+const sql_1 = require("./sql");
+const response_handler_1 = require("./utils/response-handler");
+const SCHEMA_VERSION_TABLE_CREATE_QUERY = 'CREATE TABLE IF NOT EXISTS __migrations (id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, migratedAt TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP);';
+const INSERT_SCHEMA_VERSION_QUERY = 'INSERT INTO __migrations (name) VALUES (?);';
+const LIST_MIGRATIONS_QUERY = 'SELECT id, name, migratedAt FROM __migrations;';
+class MigrationRunner {
+    sqlClient;
+    migrations;
+    constructor(sqlClient) {
+        this.sqlClient = sqlClient;
+        this.migrations = [];
+    }
+    async initialize() {
+        await this.sqlClient.executeRaw(SCHEMA_VERSION_TABLE_CREATE_QUERY);
+    }
+    enqueue(name, statement) {
+        if (this.migrations.some((migration) => migration.name === name)) {
+            return this;
+        }
+        this.migrations.push({ name, statement });
+        return this;
+    }
+    getEnqueued() {
+        return this.migrations;
+    }
+    async list() {
+        const result = await this.sqlClient.executeRaw(LIST_MIGRATIONS_QUERY);
+        const migrations = new Array();
+        for (const row of result.rows) {
+            const migratedAt = new Date(row.migratedAt);
+            const id = row.id;
+            const name = row.name;
+            migrations.push({ id, name, migratedAt });
+        }
+        return migrations;
+    }
+    async run() {
+        await this.initialize();
+        const previousMigrations = await this.list();
+        const migrationsToRun = this.migrations.filter((migration) => !previousMigrations.some((prev) => prev.name === migration.name));
+        const migrationsSuccessfullyRun = [];
+        for (const migration of migrationsToRun) {
+            try {
+                await this.sqlClient.executeRaw(migration.statement);
+            }
+            catch (error) {
+                throw new response_handler_1.MigrationExecutionError(migration.name, migrationsToRun.map((m) => m.name));
+            }
+            try {
+                await this.sqlClient.prepare(INSERT_SCHEMA_VERSION_QUERY).bindParams(migration.name).execute();
+            }
+            catch (error) {
+                throw new response_handler_1.MigrationCheckPointError(migration.name, migrationsToRun.map((m) => m.name));
+            }
+            migrationsSuccessfullyRun.push(migration.name);
+        }
+        return migrationsSuccessfullyRun;
+    }
+}
+exports.MigrationRunner = MigrationRunner;
+exports.migrationRunner = new MigrationRunner(sql_1.sql);

package/out/utils/response-handler.d.ts

@@ -6,5 +6,15 @@ export declare class ApiError extends Error {
     readonly debug?: any;
     constructor(status: number, code: string, message: string, suggestion?: string | undefined, debug?: any);
 }
+export declare class MigrationExecutionError extends Error {
+    readonly migrationName: string;
+    readonly migrationsYetToRun: string[];
+    constructor(migrationName: string, migrationsYetToRun: string[]);
+}
+export declare class MigrationCheckPointError extends Error {
+    readonly migrationName: string;
+    readonly migrationsYetToRun: string[];
+    constructor(migrationName: string, migrationsYetToRun: string[]);
+}
 export declare function getResponseBody(response: Response): Promise<Result>;
 //# sourceMappingURL=response-handler.d.ts.map

package/out/utils/response-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-handler.d.ts","sourceRoot":"","sources":["../../src/utils/response-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3C,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,UAAU,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC;gBAJN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,UAAU,CAAC,oBAAQ,EACnB,KAAK,CAAC,KAAK;CAIvB;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzE"}
+{"version":3,"file":"response-handler.d.ts","sourceRoot":"","sources":["../../src/utils/response-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3C,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,UAAU,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC;gBAJN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,UAAU,CAAC,oBAAQ,EACnB,KAAK,CAAC,KAAK;CAIvB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;gBAD5B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAAE;CAIxC;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzE"}

package/out/utils/response-handler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getResponseBody = exports.ApiError = void 0;
+exports.getResponseBody = exports.MigrationCheckPointError = exports.MigrationExecutionError = exports.ApiError = void 0;
 class ApiError extends Error {
     status;
     code;
@@ -15,6 +15,26 @@ class ApiError extends Error {
     }
 }
 exports.ApiError = ApiError;
+class MigrationExecutionError extends Error {
+    migrationName;
+    migrationsYetToRun;
+    constructor(migrationName, migrationsYetToRun) {
+        super(`Failed to execute migration with name ${migrationName}`);
+        this.migrationName = migrationName;
+        this.migrationsYetToRun = migrationsYetToRun;
+    }
+}
+exports.MigrationExecutionError = MigrationExecutionError;
+class MigrationCheckPointError extends Error {
+    migrationName;
+    migrationsYetToRun;
+    constructor(migrationName, migrationsYetToRun) {
+        super(`Failed to checkpoint after running migration with name ${migrationName}`);
+        this.migrationName = migrationName;
+        this.migrationsYetToRun = migrationsYetToRun;
+    }
+}
+exports.MigrationCheckPointError = MigrationCheckPointError;
 async function getResponseBody(response) {
     const responseText = await response.text();
     if (!response.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge/sql",
-  "version": "2.0.1-next.0",
+  "version": "2.1.0-next.2",
   "description": "Forge SQL sdk",
   "author": "Atlassian",
   "license": "UNLICENSED",
@@ -18,9 +18,10 @@
     "@types/node": "14.18.63",
     "@types/node-fetch": "^2.6.11",
     "expect-type": "^0.17.3",
-    "node-fetch": "2.7.0"
+    "node-fetch": "2.7.0",
+    "jest-when": "^3.6.0"
   },
   "dependencies": {
-    "@forge/api": "^3.10.0-next.0"
+    "@forge/api": "^4.0.0-next.1"
   }
 }