sqlmorpheus 0.2.7 → 1.0.0

package/README.md

@@ -1,124 +1,124 @@
-# 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);
+# 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))
+
+## Roll back 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.js

@@ -1719,7 +1719,7 @@ async function rollback(dbAccess, toVersion, dialect, loggerMode) {
   while (version > toVersion) {
     const changes = await sql.getChanges(version);
     if (!changes) {
-      throw new Error(`No changes found for version ${version}`);
+      throw new Error(`Unexpected error! No changes were found from version ${version} (fromVersion: ${fromVersion}, toVersion: ${toVersion})`);
     } else if (changes.fromVersion == version) {
       throw new Error(`Saved changes do not change the database version (${version})`);
     }

package/dist/index.mjs

@@ -1678,7 +1678,7 @@ async function rollback(dbAccess, toVersion, dialect, loggerMode) {
   while (version > toVersion) {
     const changes = await sql.getChanges(version);
     if (!changes) {
-      throw new Error(`No changes found for version ${version}`);
+      throw new Error(`Unexpected error! No changes were found from version ${version} (fromVersion: ${fromVersion}, toVersion: ${toVersion})`);
     } else if (changes.fromVersion == version) {
       throw new Error(`Saved changes do not change the database version (${version})`);
     }

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "sqlmorpheus",
-  "version": "0.2.7",
-  "author": "JodliDev",
-  "keywords": [],
-  "license": "MIT",
-  "description": "",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/JodliDev/SqlMorpheus.git"
-  },
-  "bugs": {
-    "url": "https://github.com/JodliDev/SqlMorpheus/issues"
-  },
-  "homepage": "https://github.com/JodliDev/SqlMorpheus#readme",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "/dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build_and_publish": "npm run build && npm publish"
-  },
-  "devDependencies": {
-    "@testcontainers/mysql": "^11.7.1",
-    "@testcontainers/postgresql": "^11.10.0",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^24.0.13",
-    "@types/pg": "^8.16.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "better-sqlite3": "^12.2.0",
-    "mysql2": "^3.15.2",
-    "pg": "^8.16.3",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
-  },
-  "dependencies": {
-    "escape-sql-string": "^1.2.2",
-    "polyfill-symbol-metadata": "^0.0.2"
-  }
-}
+{
+  "name": "sqlmorpheus",
+  "version": "1.0.0",
+  "author": "JodliDev",
+  "keywords": [],
+  "license": "MIT",
+  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/JodliDev/SqlMorpheus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JodliDev/SqlMorpheus/issues"
+  },
+  "homepage": "https://github.com/JodliDev/SqlMorpheus#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build_and_publish": "npm run build && npm publish"
+  },
+  "devDependencies": {
+    "@testcontainers/mysql": "^11.7.1",
+    "@testcontainers/postgresql": "^11.10.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.0.13",
+    "@types/pg": "^8.16.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "better-sqlite3": "^12.2.0",
+    "mysql2": "^3.15.2",
+    "pg": "^8.16.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "escape-sql-string": "^1.2.2",
+    "polyfill-symbol-metadata": "^0.0.2"
+  }
+}