forge-sql-orm 1.0.23 → 1.0.25

package/README.md

@@ -1,5 +1,7 @@
 # Forge SQL ORM
 
+[![forge-sql-orm CI](https://github.com/vzakharchenko/forge-sql-orm/actions/workflows/node.js.yml/badge.svg)](https://github.com/vzakharchenko/forge-sql-orm/actions/workflows/node.js.yml)
+
 **Forge-SQL-ORM** is an ORM designed for working with [@forge/sql](https://developer.atlassian.com/platform/forge/storage-reference/sql-tutorial/) in **Atlassian Forge**. It is built on top of [MikroORM](https://mikro-orm.io/docs/query-builder) and provides advanced capabilities for working with relational databases inside Forge.
 
 ## Key Features
@@ -10,6 +12,13 @@
 - ✅ **Schema migration support**, allowing automatic schema evolution.
 - ✅ **Automatic entity generation** from MySQL/tidb databases.
 - ✅ **Automatic migration generation** from MySQL/tidb databases.
+- ✅ **Optimistic Locking** Ensures data consistency by preventing conflicts when multiple users update the same record.
+
+🚀 **Development in Progress** 🚀
+I am currently working on implementing the following features:
+- 🗑️ **Soft Deletion Support** – Allows marking records as deleted without actually removing them from the database, enabling easy recovery.
+- 🏗️ **Complex Query Handling** _(JOIN, GROUP BY, etc.) without requiring an EntitySchema_ – Simplifies the execution of advanced SQL queries without the need to define additional schemas.
+---
 
 ## Installation
 
@@ -173,50 +182,86 @@ const results = await forgeSQL.fetch().executeSchemaSQL(query, innerJoinSchema);
 console.log(results);
 ```
 
-🛠 CRUD Operations
-
-- Insert Data
-
-```js
-// INSERT INTO users (id, name) VALUES (1,'Smith')
-const userId = await forgeSQL.crud().insert(UsersSchema, [{ id: 1, name: "Smith" }]);
-```
-
-- Insert Bulk Data
-
-```js
-// INSERT INTO users (id,name) VALUES (2,'Smith'), (3,'Vasyl')
-await forgeSQL.crud().insert(UsersSchema, [
-  { id: 2, name: "Smith" },
-  { id: 3, name: "Vasyl" },
-]);
-```
-
-- Insert Data with duplicates
-
-```js
-// INSERT INTO users (id,name) VALUES (4,'Smith'), (4, 'Vasyl') ON DUPLICATE KEY UPDATE name = VALUES(name)
-await forgeSQL.crud().insert(
-  UsersSchema,
-  [
-    { id: 4, name: "Smith" },
-    { id: 4, name: "Vasyl" },
-  ],
-  true,
-);
-```
-
-- Update Data
-
-```js
-await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, UsersSchema);
-```
+Below is an example of how you can extend your README's CRUD Operations section with information and examples for both `updateFieldById` and `updateFields` methods:
 
-- Delete Data
+---
 
-```js
-await forgeSQL.crud().deleteById(1, UsersSchema);
-```
+🛠 **CRUD Operations**
+
+- **Insert Data**
+
+  ```js
+  // INSERT INTO users (id, name) VALUES (1, 'Smith')
+  const userId = await forgeSQL.crud().insert(UsersSchema, [{ id: 1, name: "Smith" }]);
+  ```
+
+- **Insert Bulk Data**
+
+  ```js
+  // INSERT INTO users (id, name) VALUES (2, 'Smith'), (3, 'Vasyl')
+  await forgeSQL.crud().insert(UsersSchema, [
+    { id: 2, name: "Smith" },
+    { id: 3, name: "Vasyl" },
+  ]);
+  ```
+
+- **Insert Data with Duplicates**
+
+  ```js
+  // INSERT INTO users (id, name) VALUES (4, 'Smith'), (4, 'Vasyl') 
+  // ON DUPLICATE KEY UPDATE name = VALUES(name)
+  await forgeSQL.crud().insert(
+    UsersSchema,
+    [
+      { id: 4, name: "Smith" },
+      { id: 4, name: "Vasyl" },
+    ],
+    true,
+  );
+  ```
+
+- **Update Data by Primary Key**
+
+  ```js
+  // This uses the updateById method which wraps updateFieldById (with optimistic locking if configured)
+  await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, UsersSchema);
+  ```
+
+- **Update Specific Fields by Primary Key**
+
+  ```js
+  // Updates specific fields of a record identified by its primary key.
+  // Note: The primary key field (e.g. id) must be included in the fields array.
+  await forgeSQL.crud().updateFieldById({ id: 1, name: "Updated Name" }, ["id", "name"], UsersSchema);
+  ```
+
+- **Update Fields Without Primary Key and Versioning**
+
+  ```js
+  // Updates specified fields for records matching the given conditions.
+  // In this example, the "name" and "age" fields are updated for users where the email is 'smith@example.com'.
+  const affectedRows = await forgeSQL.crud().updateFields(
+    { name: "New Name", age: 35, email: "smith@example.com" },
+    ["name", "age"],
+    UsersSchema
+  );
+  console.log(`Rows affected: ${affectedRows}`);
+
+  // Alternatively, you can provide an explicit WHERE condition:
+  const affectedRowsWithWhere = await forgeSQL.crud().updateFields(
+    { name: "New Name", age: 35 },
+    ["name", "age"],
+    UsersSchema,
+    { email: "smith@example.com" }
+  );
+  console.log(`Rows affected: ${affectedRowsWithWhere}`);
+  ```
+
+- **Delete Data**
+
+  ```js
+  await forgeSQL.crud().deleteById(1, UsersSchema);
+  ```
 
 ## Quick Start
 
@@ -495,6 +540,130 @@ console.log(results);
 
 ---
 
+## ForgeSqlOrmOptions
+
+The `ForgeSqlOrmOptions` object allows customization of ORM behavior. Currently, it supports the following options:
+
+| Option                     | Type      | Description                                                                                                                                                                                                                     |
+| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logRawSqlQuery`           | `boolean` | Enables logging of raw SQL queries in the Atlassian Forge Developer Console. Useful for debugging and monitoring. Defaults to `false`.                                                                                         |
+| `disableOptimisticLocking` | `boolean` | Disables optimistic locking. When set to `true`, no additional condition (e.g., a version check) is added during record updates, which can improve performance. However, this may lead to conflicts when multiple transactions attempt to update the same record concurrently. |
+
+---
+
+### Example: Initializing `ForgeSQL` with Options
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+import { Orders } from "./entities/Orders";
+import { Users } from "./entities/Users";
+import ENTITIES from "./entities";
+
+const options = {
+  logRawSqlQuery: true, // Enable query logging for debugging purposes
+};
+
+const forgeSQL = new ForgeSQL(ENTITIES, options);
+```
+
+## Using `getKnex()` for Advanced SQL Queries
+
+The `getKnex()` method allows direct interaction with Knex.js, enabling execution of raw SQL queries and complex query building.
+
+### Example: Finding Duplicate Records in `UsersSchema`
+
+```typescript
+const fields: string[] = ["name", "email"];
+
+// Define selected fields, including a count of duplicate occurrences
+const selectFields: Array<string | Knex.Raw> = [
+  ...fields,
+  forgeSQL.getKnex().raw("COUNT(*) as count"),
+];
+
+// Create a QueryBuilder with grouping and filtering for duplicates
+let selectQueryBuilder = forgeSQL
+  .createQueryBuilder(UsersSchema)
+  .select(selectFields as unknown as string[])
+  .groupBy(fields)
+  .having("COUNT(*) > 1");
+
+// Generate the final SQL query with ordering by count
+const query = selectQueryBuilder.getKnexQuery().orderByRaw("count ASC").toSQL().sql;
+
+/* 
+  SQL Query:
+  SELECT `u0`.`name`, `u0`.`email`, COUNT(*) as count 
+  FROM `users` AS `u0` 
+  GROUP BY `u0`.`name`, `u0`.`email` 
+  HAVING COUNT(*) > 1 
+  ORDER BY count ASC;
+*/
+
+// Execute the SQL query and retrieve results
+const duplicateResult = await forgeSQL
+  .fetch()
+  .executeSchemaSQL<DuplicateResult>(query, DuplicateSchema);
+```
+
+🔹 **What does this example do?**
+
+1. Selects `name` and `email`, along with the count of duplicate occurrences (`COUNT(*) as count`).
+2. Groups the data by `name` and `email` to identify duplicates.
+3. Filters the results to include only groups with more than one record (`HAVING COUNT(*) > 1`).
+4. Sorts the final results in ascending order by count (`ORDER BY count ASC`).
+5. Executes the SQL query and returns the duplicate records.
+
+---
+
+Below is the plain text version of the additional section for Optimistic Locking. You can copy and paste it directly into your README:
+
+---
+
+## Optimistic Locking
+
+Optimistic locking is a concurrency control mechanism that prevents data conflicts when multiple transactions attempt to update the same record concurrently. Instead of using locks, this technique relies on a version field in your entity models. Each time an update occurs, the current version is checked, and if it doesn't match the stored version, the update is rejected. This ensures data consistency and helps avoid accidental overwrites.
+
+### How It Works
+
+- **Version Field:**  
+  A specific field in your entity schema is designated to track the version of the record. This field is marked with the flag `version: true`.
+
+- **Supported Types:**  
+  The version field must be of type `datetime`, `timestamp`, `integer`, or `decimal` and must be non-nullable. If the field's type does not meet these requirements, a warning message will be logged to the console during model generation.
+
+- **Automatic Configuration:**  
+  When generating models, you can specify a field (e.g., `updatedAt`) that automatically becomes the version field by using the `--versionField` flag. For example:
+  ```sh
+  npx forge-sql-orm generate:model --versionField updatedAt
+  ```
+  In this case, any model that includes a field named `updatedAt` meeting the required conditions will have it configured for optimistic locking.
+
+### Example
+
+Here’s how you can define an entity with optimistic locking using MikroORM:
+
+```js
+export class TestEntityVersion {
+  id!: number;
+  name?: string;
+  version!: number;
+}
+
+export const TestEntityVersionSchema = new EntitySchema({
+  class: TestEntityVersion,
+  properties: {
+    id: { primary: true, type: "integer", unsigned: false, autoincrement: false },
+    name: { type: "string", nullable: true },
+    version: { type: "integer", nullable: false, version: true },
+  },
+});
+```
+
+In this example, the `version` field is used to track changes. Every update will check the current version to ensure that no conflicting modifications occur.
+
+---
+
 ## Usage with MikroORM Generator
 
 If you prefer to use MikroORM's default entity generator, then manually import your entities:
@@ -505,9 +674,13 @@ import { UserEntity, TaskEntity } from "./entities";
 
 ---
 
-## The CLI provides commands to generate models and manage migrations.
+## Forge SQL ORM CLI Documentation
 
-🔹 Available Commands
+The CLI provides commands to generate models and manage migrations for MikroORM in Forge.
+
+---
+
+### 📌 Available Commands
 
 ```sh
 $ npx forge-sql-orm --help
@@ -515,58 +688,79 @@ $ npx forge-sql-orm --help
 Usage: forge-sql-orm [options] [command]
 
 Options:
-  -V, --version                output the version number
-  -h, --help                   display help for command
+  -V, --version                Output the version number
+  -h, --help                   Display help for command
 
 Commands:
   generate:model [options]     Generate MikroORM models from the database.
   migrations:create [options]  Generate an initial migration for the entire database.
   migrations:update [options]  Generate a migration to update the database schema.
-  patch:mikroorm               Patch MikroORM and Knex dependencies to work properly with Forge
-  help [command]               display help for command
+  patch:mikroorm               Patch MikroORM and Knex dependencies to work properly with Forge.
+  help [command]               Display help for a specific command.
 ```
 
-📌 Entity Generation
+---
+
+### 📌 Entity Generation
 
 ```sh
-npx forge-sql-orm generate:model --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/entities
+npx forge-sql-orm generate:model --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/entities --versionField updatedAt --saveEnv
 ```
 
 This command will:
 
-- Connect to mydb on localhost:3306
-- Generate MikroORM entity classes
-- Save them in ./src/database/entities
-- Create an index.ts file with all entities
+- Connect to `mydb` on `localhost:3306`.
+- Generate MikroORM entity classes.
+- Save them in `./src/database/entities`.
+- Create an `index.ts` file with all entities.
+- **`--versionField updatedAt`**: Specifies the field used for entity versioning.
+- **`--saveEnv`**: Saves configuration settings to `.env` for future use.
+
+#### 🔹 VersionField Explanation
+
+The `--versionField` option is crucial for handling entity versioning. It should be a field of type `datetime`, `integer`, or `decimal`. This field is used to track changes to entities, ensuring that updates follow proper versioning strategies.
+
+**Example:**
 
-📌 Database Migrations
+- `updatedAt` (datetime) - Commonly used for timestamp-based versioning.
+- `versionNumber` (integer) - Can be used for numeric version increments.
+
+If the specified field does not meet the required criteria, warnings will be logged.
+
+---
+
+### 📌 Database Migrations
 
 ```sh
-npx forge-sql-orm migrations:create --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/migration --entitiesPath ./src/database/entities
+npx forge-sql-orm migrations:create --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/migration --entitiesPath ./src/database/entities --saveEnv
 ```
 
 This command will:
 
-- Create initial migration from all detected entities
-- Save migration files in ./src/database/migration
-- Create migrationCount.ts to track versions
-- Create index.ts for automatic migration execution
+- Create the initial migration based on all detected entities.
+- Save migration files in `./src/database/migration`.
+- Create `index.ts` for automatic migration execution.
+- **`--saveEnv`**: Saves configuration settings to `.env` for future use.
 
-📌 Update Schema Migration
+---
+
+### 📌 Update Schema Migration
 
 ```sh
-npx forge-sql-orm migrations:update --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/migration --entitiesPath ./src/database/entities
+npx forge-sql-orm migrations:update --host localhost --port 3306 --user root --password secret --dbName mydb --output ./src/database/migration --entitiesPath ./src/database/entities --saveEnv
 ```
 
 This command will:
 
-Detect schema changes (new tables, columns, indexes)
+- Detect schema changes (new tables, columns, indexes).
+- Generate only the required migrations.
+- Update `index.ts` to include new migrations.
+- **`--saveEnv`**: Saves configuration settings to `.env` for future use.
+
+---
 
-- Generate only required migrations
-- Increment migrationCount.ts
-- Update index.ts to include new migrations
+### 📌 Using the patch:mikroorm Command
 
-📌 Using the patch:mikroorm Command
 If needed, you can manually apply the patch at any time using:
 
 ```sh
@@ -579,23 +773,19 @@ This command:
 - Fixes dynamic imports to work in Forge.
 - Ensures Knex and MikroORM work properly inside Forge.
 
-📌 Manual Migration Execution
-To manually execute migrations in your application:
+---
 
-```js
-import migrationRunner from "./src/database/migration";
-import { MigrationRunner } from "@forge/sql/out/migration";
+### 📌 Configuration Methods
 
-const runner = new MigrationRunner();
-await migrationRunner(runner);
-await runner.run(); // ✅ Apply migrations
-```
-
-🔧 Configuration
 You can define database credentials using:
 
-1.  Command-line arguments: --host, --port, etc.
-    2️. Environment variables:
+1️⃣ **Command-line arguments**:
+
+```sh
+--host, --port, --user, --password, --dbName, --output, --versionField, --saveEnv
+```
+
+2️⃣ **Environment variables**:
 
 ```bash
 export FORGE_SQL_ORM_HOST=localhost
@@ -605,7 +795,7 @@ export FORGE_SQL_ORM_PASSWORD=secret
 export FORGE_SQL_ORM_DBNAME=mydb
 ```
 
-3. use .env
+3️⃣ **Using a `.env` file**:
 
 ```sh
 FORGE_SQL_ORM_HOST=localhost
@@ -615,7 +805,24 @@ FORGE_SQL_ORM_PASSWORD=secret
 FORGE_SQL_ORM_DBNAME=mydb
 ```
 
-4. Interactive prompts (if missing parameters)
+4️⃣ **Interactive prompts** (if missing parameters, the CLI will ask for input).
+
+---
+
+### 📌 Manual Migration Execution
+
+To manually execute migrations in your application:
+
+```js
+import migrationRunner from "./src/database/migration";
+import { MigrationRunner } from "@forge/sql/out/migration";
+
+const runner = new MigrationRunner();
+await migrationRunner(runner);
+await runner.run(); // ✅ Apply migrations
+```
+
+This approach allows you to apply migrations programmatically in a Forge application.
 
 ---