sqlmorpheus 0.2.6 → 0.2.7

package/README.md

@@ -1,3 +1,124 @@
- Ever wanted to use a migration tool but couldn't because is uses a different stack than your project and would add unnecessary overhead or would simply not work in your setup at all? SQLMorpheus is an automatic migration library that is as unopinionated as it gets:
- 
-- It does not use its own database framework
+# SqlMorpheus
+
+SQLMorpheus is a standalone SQL migration tool that automatically calculates the differences between a database and a defined state and updates the database structure accordingly. It is not bundled with any ORM or limited to a specific SQL dialect or SQL library, making it very flexible and easy to integrate into any (new or preexisting) project.
+
+Its stand-out features are:
+- Database **changes are calculated at runtime**, allowing SqlMorpheus to be used with different database states without expecting any existing structure or having to recompile your app.
+- SQLMorpheus **does not bundle its own SQL library** but allows you to define database access yourself using any library you want. This not only prevents unnecessary overhead, it also makes SQLMorpheus very flexible and easy to migrate between database flavours.
+- While SQLMorpheus can work without (almost) any manual input, it optionally **allows for destructive changes to be confirmed** to prevent possible data loss.
+- It **keeps a history of changes** (and adds an interface for backups before migrations) and allows viewing all changes made and even roll back to a specific version.
+
+
+## How to install?
+To install SqlMorpheus, run
+```bash
+npm install sqlmorpheus
+```
+
+## How to use?
+
+Because SqlMorpheus relies on the framework you choose for database access, it needs a little bit more setup code. But you only need to copy & paste a few simple lines of code:
+
+### 1. Access the database
+For SqlMorpheus to be able to access your database, you need to provide its `runMigration` call (see bellow) with a `dbAccess` object with three callback functions: `runReadStatement()`, `runWriteStatement()` and `runTransaction()`.
+Here is a full example for SQLite using better-sqlite3
+For other SQL types you can copy one of the provided examples (see [MySQL](/examples/DatabaseAccess_for_MySQL.md), [Postgres](/examples/DatabaseAccess_for_Postgres.md), [SQLite](/examples/DatabaseAccess_for_SQLite.md)) 
+
+```typescript
+import {DatabaseAccess, runMigration} from "sqlmorpheus";
+import BetterSqlite3 from "better-sqlite3";
+
+const db = new BetterSqlite3(":memory:");
+const dbAccess: DatabaseAccess = {
+    runReadStatement: async (query: string) => db.prepare(query).all(), 
+    runWriteStatement: async (query: string) => db.prepare(query).run(), 
+    runTransaction: async (query: string) => {
+        const transaction = db.transaction(() => db.exec(query));
+        transaction();
+    }
+}
+```
+<details>
+    <summary>Optional: `createBackup()` in DatabaseAccess.</summary>
+    
+On top of the three mandatory methods, you can also define `createBackup()`. This callback is called whenever the `version` in `DatabaseInstructions` has changed and SqlMorpheus needs to change the database. An example implementation for a backup in SQLite would be:
+
+```typescript
+const dbAccess: DatabaseAccess = {
+    ...,
+    createBackup: async (backupName: string) => {
+        await db.backup(`backups/${backupName}.sqlite`)
+    }
+}
+```
+</details>
+
+
+### 2. Define the database structure
+This part might require the most work from you, but should be familiar to you if you have already used other migration libraries: You need to tell SqlMorpheus what structure it should mold your database into. To make this process as simple as possible, SqlMorpheus provides a convenient `TableObj.create()` builder (see [TableObj example](/examples/database_structure_using_TableObj.md)) or, if you prefer, you can also use decorators (see [decorator example](/examples/database_structure_using_decorators.md)).
+Here is an example using `TableObj.create()`:
+```typescript
+import {DatabaseAccess, runMigration} from "sqlmorpheus";
+const usersTable = TableObj.create("User", {
+    userId: [0, {primaryKey: true}], 
+    name: "Default name", 
+    email: [null, {dataType: "string"}]
+});
+const messagesTable = TableObj.create("Message", {
+    messageId: [0, {primaryKey: true}], 
+    from: 0,
+    to: 0, 
+    content: ""
+})
+    .foreignKey("from", usersTable, "userId", {onDelete: "CASCADE"})
+    .foreignKey("to", usersTable, "userId", {onDelete: "CASCADE"});
+```
+
+### 3. Create the database instructions and run the migration
+Now we combine everything and call `runMigration()`.
+
+Example:
+```typescript
+const instructions: DatabaseInstructions = {
+    dialect: "Sqlite", 
+    tables: [userTable, messagesTable], // usersTable and messagesTable are defined above 
+    version: 1
+};
+
+await runMigration(dbAccess, instructions); // dbAccess is defined above
+```
+<details>
+    <summary>More information about `DatabaseInstructions`.</summary>
+
+#### `dialect`
+This property tells SqlMorpheus which SQL dialect your database uses.
+
+#### `tables`
+This property contains all tables that should be created in the database.
+
+#### `version`
+SqlMorpheus will only compare the database structure when the database version is different to the version property defined in DatabaseInstructions. The version property is also used to decide which manual migrations defined in `preMigration()` should be executed.
+
+#### `preMigration()`
+This method is run before database migrations (and comparisons) are executed. This is also the place where you allow specific destructive migrations or tell SqlMorpheus that you want to rename a table or column (rather than removing and adding it – which would be the default behaviour).
+
+#### `postMigration()`
+This method is run after the migration was finished. You will very rarely need it.
+
+> All properties are documented in [DatabaseInstructions](/src/lib/typings/DatabaseInstructions.ts).
+</details>
+
+## When does SqlMorpheus check for migrations?
+SqlMorpheus will only compare the database when the [version property](#version) is different to the version saved in the database itself (or if the database has no version defined at all).
+
+## How to rename a table or column?
+SqlMorpheus has no way of telling if you want to rename a table / column or want to remove it and add a completely new one. To solve this, it relies on your input to tell it what to do (by default it just removes and adds a table / column).
+To tell it to rename a table / column, you call `migration.renameTable(VERSION, "OLD_TABLENAME", "NEW_TABLENAME");` in `preMigration()` ([example](/examples/example_renaming.md))
+
+## rollback your database
+SqlMorpheus saves its changes into the database (into a table called `__sqlmorpheus_migrations`) which allows you to roll back the database to a previous state with a single command:
+
+```typescript
+// `dbAccess` and `instructions` are defined above
+await rollback(dbAccess, TARGET_VERSION, instructions.dialect);
+```

package/dist/index.d.mts

@@ -1,7 +1,8 @@
 interface DatabaseAccess {
-    createBackup?(backupName: string): Promise<void>;
-    runGetStatement(query: string): Promise<unknown>;
-    runMultipleWriteStatements(query: string): Promise<void>;
+    createBackup?(backupName: string): Promise<any>;
+    runReadStatement(query: string): Promise<unknown>;
+    runWriteStatement(query: string): Promise<any>;
+    runTransaction(query: string): Promise<any>;
 }
 
 type Class<T> = new (...args: never[]) => T;
@@ -12,14 +13,16 @@ type TableClassInterface = {
     [key: string]: any;
 };
 
+declare const ALLOWED = "allowed";
+declare const USED = "allowedAndUsed";
+type AllowedMigrationState = typeof ALLOWED | typeof USED;
 interface AllowedMigrations {
-    recreateTable?: boolean;
-    dropTable?: boolean;
-    dropColumn?: boolean;
-    alterPrimaryKey?: boolean;
-    removeForeignKey?: boolean;
-    alterForeignKey?: boolean;
-    continueWithoutRollback?: boolean;
+    recreateTable?: Record<string, AllowedMigrationState>;
+    dropTable?: Record<string, AllowedMigrationState>;
+    dropColumn?: Record<string, AllowedMigrationState>;
+    alterPrimaryKey?: Record<string, AllowedMigrationState>;
+    removeForeignKey?: Record<string, AllowedMigrationState>;
+    alterForeignKey?: Record<string, AllowedMigrationState>;
 }
 
 interface RenameData {
@@ -34,7 +37,6 @@ interface MigrationInstructions {
      */
     renamedColumns: RenameData[];
     allowedMigrations: AllowedMigrations;
-    usedMigrations: Record<string, boolean>;
 }
 
 interface ColumnInfo {
@@ -81,14 +83,6 @@ declare class Migrations {
      * @param fromVersion - The version of the actual database.
      */
     reset(dbInstructions: DatabaseInstructions, fromVersion: number): void;
-    /**
-     * Retrieves the migration instructions for the specified table.
-     * @see getEntryFromTableName
-     *
-     * @param table - The {@link TableInput} object from which the table name will be retrieved.
-     * @return The migration instructions corresponding to the given table input.
-     */
-    private getEntry;
     /**
      * Retrieves the migration instructions for the specified table.
      *
@@ -96,13 +90,6 @@ declare class Migrations {
      * @return The migration instructions corresponding to the given table input.
      */
     private getEntryFromTableName;
-    /**
-     * Retrieves the table name from the given table input.
-     *
-     * @param table - The {@link TableInput} object.
-     * @return The name of the table derived from either {@link TableObj} or a class.
-     */
-    private getTableName;
     /**
      * Checks whether a provided version is relevant based on database version ({@link fromVersion}) and target version ({@link toVersion}).
      * Also makes sure that version checks happen in order.
@@ -136,8 +123,9 @@ declare class Migrations {
      * @see allowMigration()
      * @param tableName - The name of the table to check the migration against.
      * @param type - The type of destructive migration being checked.
+     * @param column - The column name for which the migration is allowed. Only needed for "dropColumn", "removeForeignKey" and "alterForeignKey".
      */
-    compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations): void;
+    compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations, column?: string): void;
     /**
      * Retrieves the migration data containing instructions for data migration.
      * Only used internally.
@@ -205,10 +193,13 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the specific migration is allowed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table - Either a {@link TableObj} or a class decorated with @TableClass.
-     * @param allowedMigrations - The keys representing the migrations to be allowed. Multiple migrations can be provided
+     * @param tableName - The current table name in the database at the time of the migration version.
+     * @param allowedMigration - The keys representing the migrations to be allowed.
+     * @param column - The column name for which the migration is allowed. Only needed for "dropColumn", "removeForeignKey" and "alterForeignKey".
+     *
+     * @throws Error if the provided column name is not valid for the specified migration.
      */
-    allowMigration(version: number, table: TableInput, ...allowedMigrations: (keyof AllowedMigrations)[]): void;
+    allowMigration(version: number, tableName: string, allowedMigration: keyof AllowedMigrations, column?: string): void;
     /**
      * When you change the name of a table, SqlMorpheus will assume the original table was meant to be dropped
      * and the new table was meant to be added, which would lead to data loss.
@@ -216,10 +207,10 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param oldTableName - The current name in the database at the time of the migration.
-     * @param newTableName - The new table name or its equivalent input format.
+     * @param oldTableName - The current name in the database at the time of the migration version.
+     * @param newTableName - The new table name at the time of the migration version.
      */
-    renameTable(version: number, oldTableName: string, newTableName: TableInput): void;
+    renameTable(version: number, oldTableName: string, newTableName: string): void;
     /**
      * When you change the name of a column, SqlMorpheus will assume the original column was meant to be removed
      * and the new column was meant to be added, which would lead to data loss.
@@ -227,11 +218,11 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table Either a {@link TableObj} or a class decorated with @TableClass containing the column to be renamed.
+     * @param tableName - The current table name in the database at the time of the migration version.
      * @param oldColumn The current name in the database at the time of the migration.
      * @param newColumn The new name to assign to the column.
      */
-    renameColumn(version: number, table: TableInput, oldColumn: string, newColumn: string): void;
+    renameColumn(version: number, tableName: string, oldColumn: string, newColumn: string): void;
     /**
      * Should not be needed most of the time.
      * Marks a table to be recreated
@@ -239,9 +230,9 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table Either a {@link TableObj} or a class decorated with @TableClass.
+     * @param tableName - The current table name in the database at the time of the migration version.
      */
-    recreateTable(version: number, table: TableInput): void;
+    recreateTable(version: number, tableName: string): void;
 }
 type PublicMigrations = Pick<Migrations, "recreateTable" | "renameTable" | "renameColumn" | "allowMigration">;
 
@@ -263,12 +254,17 @@ interface InputTableStructure extends TableStructure {
     columns: Record<string, InputColumnInfo>;
 }
 
-type DataFormat = Record<string, unknown>;
-type GetColumns<T> = T extends TableObjBuilderDefinition<infer Item, any> ? Item : never;
-type TableObjBuilderDefinition<T extends DataFormat, TPick extends keyof TableObj<T>> = Pick<TableObj<T>, TPick>;
-type NewTableObjBuilder<T extends DataFormat> = TableObjBuilderDefinition<T, "primaryKey" | "foreignKey" | "dataType" | "maxCharacterLength">;
-type TableObjBuilder<T extends DataFormat> = TableObjBuilderDefinition<T, "foreignKey" | "dataType" | "maxCharacterLength">;
-type TableObjInput = TableObjBuilderDefinition<any, any>;
+type AllowedTypes = boolean | number | bigint | string | null | Date;
+
+interface ColumnOptions {
+    primaryKey?: boolean;
+    dataType?: DataTypeOptions;
+    maxCharacterLength?: number;
+}
+type DataFormat = Record<string, AllowedTypes | [AllowedTypes, ColumnOptions]>;
+type GetColumns<T> = T extends PublicTableObj<infer Item> ? Item : never;
+type PublicTableObj<T extends DataFormat> = Pick<TableObj<T>, "foreignKey" | "sealType">;
+type TableObjInput = PublicTableObj<DataFormat>;
 /**
  * Use this class to define tables for DatabaseInstructions
  * (as an alternative for Class decorators)
@@ -278,44 +274,68 @@ declare class TableObj<T extends DataFormat> {
     readonly IS_TABLE_OBJ = true;
     readonly tableName: string;
     tableStructure: InputTableStructure;
-    static getEmptyColumnEntry(key: string): InputColumnInfo;
-    static getColumnEntry(key: string, value: unknown): InputColumnInfo | null;
     private constructor();
-    primaryKey(key: keyof T): TableObjBuilder<T>;
-    foreignKey<TOther extends TableObjBuilderDefinition<DataFormat, any>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
+    private applyOptions;
+    /**
+     * Creates a foreign key relationship between the current table and a target table.
+     *
+     * @param fromColumn - The column in the current table that will serve as the foreign key.
+     * @param toTable - The target table object that the foreign key will reference.
+     * @param toColumn - The column in the target table that the foreign key will reference.
+     * @param options - Optional configurations for the foreign key, specifying actions on update or delete.
+     */
+    foreignKey<TOther extends Partial<TableObj<DataFormat>>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
         onUpdate?: ForeignKeyActions;
         onDelete?: ForeignKeyActions;
-    }): TableObjBuilder<T>;
-    dataType(column: keyof T, type: DataTypeOptions): TableObjBuilder<T>;
-    maxCharacterLength(column: keyof T, max: number): TableObjBuilder<T>;
-    static create<T extends Record<string, unknown>>(tableName: string, columns: T): NewTableObjBuilder<T>;
-    static isTableObj(obj: unknown): obj is TableObj<any>;
+    }): PublicTableObj<T>;
+    /**
+     * An optional helper function to deal with `TS2589: Type instantiation is excessively deep and possibly infinite. when used as method parameter`
+     * Does nothing in runtime
+     */
+    sealType(): TableObjInput;
+    static create<T extends DataFormat>(tableName: string, columns: T): PublicTableObj<T>;
 }
 
+type LoggerMode = "silent" | "error" | "warn" | "log" | "debug";
+
 type TableInput = TableObjInput | Class<TableClassInterface>;
 interface DatabaseInstructions {
     dialect: "Sqlite" | "MsSql" | "MySql" | "Postgres";
     tables: TableInput[];
     version: number;
-    configPath: string;
-    throwIfNotAllowed: boolean;
-    loggerMode?: "silent" | "noLog" | "normal" | "debug";
-    alwaysAllowedMigrations?: AllowedMigrations;
+    /**
+     * Usually SqlMorpheus throws an exception if it needs to execute a destructive database change and is not explicitly confirmed in
+     * (using `allowMigration()` in `preMigration()`).
+     * If true, no exception will be thrown and an error message will be logged to the console instead.
+     */
+    doNotThrowIfNotAllowed?: boolean;
+    /**
+     * Defines how much should be logged to the console.
+     */
+    loggerMode?: LoggerMode;
+    /**
+     * Usually SqlMorpheus throws an exception if it needs to execute a destructive database change and is not explicitly allowed to do so
+     * (using `allowMigration()` in `preMigration()`).
+     * if defined, the confirmation will be skipped for each migration type defined in `alwaysAllowedMigrations`.
+     */
+    alwaysAllowedMigrations?: (keyof AllowedMigrations)[];
     /**
      * Custom migrations that will run before any database changes are applied.
-     * @param migrations The migration object that will be validated after this.
-     * @param fromVersion Version of the current database.
-     * @param toVersion Version of the database after update.
+     * @param migrations - The migration object that will be validated after this.
+     * @param dbAccess - The database access object to interact with the database.
+     * @param fromVersion - Version of the current database.
+     * @param toVersion - Version of the database after update.
      * @return custom SQL that should be executed before migrations are executed.
      */
-    preMigration?(migrations: PublicMigrations, fromVersion: number, toVersion: number): SqlChanges | void;
+    preMigration?(migrations: PublicMigrations, dbAccess: DatabaseAccess, fromVersion: number, toVersion: number): SqlChanges | void;
     /**
      * Custom migrations that will run after database changes have been applied (but before the transaction is finished)
-     * @param fromVersion Version of the current database.
-     * @param toVersion Version of the database after update.
-     * @return custom SQL that should be executed before migrations are executed.
+     * @param dbAccess - The database access object to interact with the database.
+     * @param fromVersion - Version of the current database.
+     * @param toVersion - Version of the database after update.
+     * @return custom SQL that should be executed after migrations were executed.
      */
-    postMigration?(fromVersion: number, toVersion: number): SqlChanges;
+    postMigration?(dbAccess: DatabaseAccess, fromVersion: number, toVersion: number): SqlChanges;
 }
 
 /**
@@ -348,6 +368,13 @@ declare function ForeignKey<TOther extends TableClassInterface>(toTable: Class<T
 }): (table: any, context: any) => void;
 
 declare function runMigration(db: DatabaseAccess, dbInstructions: DatabaseInstructions): Promise<void>;
-declare function rollback(db: DatabaseAccess, dbInstructions: DatabaseInstructions, toVersion: number): Promise<number>;
+/**
+ * Rolls back the database to the provided toVersion
+ * @param dbAccess - Access to the database.
+ * @param toVersion - the version to which the database should be upgraded to.
+ * @param dialect - the dialect that should be used for the database. Usually is the value defined in DatabaseInstructions
+ * @param loggerMode - defines how much should be logged to the console.
+ */
+declare function rollback(dbAccess: DatabaseAccess, toVersion: number, dialect: DatabaseInstructions["dialect"], loggerMode?: DatabaseInstructions["loggerMode"]): Promise<number>;
 
 export { DataType, type DatabaseAccess, type DatabaseInstructions, ForeignKey, type PublicMigrations, type SqlChanges, TableClass, TableObj, rollback, runMigration };