forge-sql-orm 1.0.30 → 1.1.31

package/README.md

@@ -2,17 +2,17 @@
 
 [![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.
+**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 [Drizzle ORM](https://orm.drizzle.team) and provides advanced capabilities for working with relational databases inside Forge.
 
 ## Key Features
-
-- ✅ **Supports foreign keys** at the entity level.
-- ✅ **Supports complex SQL queries** with joins and filtering.
-- ✅ **Batch insert support** with duplicate key handling.
-- ✅ **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.
+- ✅ **Supports complex SQL queries** with joins and filtering using Drizzle ORM
+- ✅ **Batch insert support** with duplicate key handling
+- ✅ **Schema migration support**, allowing automatic schema evolution
+- ✅ **Automatic entity generation** from MySQL/tidb databases
+- ✅ **Automatic migration generation** from MySQL/tidb databases
+- ✅ **Drop Migrations** Generate a migration to drop all tables and clear migrations history for subsequent schema recreation
+- ✅ **Optimistic Locking** Ensures data consistency by preventing conflicts when multiple users update the same record
+- ✅ **Type Safety** Full TypeScript support with proper type inference
 
 ## Installation
 
@@ -23,51 +23,22 @@ Forge-SQL-ORM is designed to work with @forge/sql and requires some additional s
 ```sh
 npm install forge-sql-orm -S
 npm install @forge/sql -S
-npm i @mikro-orm/entity-generator -D
-npm i mysql -D
+npm install drizzle-orm mysql2
+npm install mysql2 @types/mysql2 -D
 ```
 
 This will:
-
-Install Forge-SQL-ORM (the ORM for @forge/sql).
-Install @forge/sql, the Forge database layer.
-
-✅ Step 2: Configure Post-Installation Patch
-By default, MikroORM and Knex include some features that are not compatible with Forge's restricted runtime.
-To fix this, we need to patch these libraries after installation.
-
-Run:
-
-```sh
-npm pkg set scripts.postinstall="forge-sql-orm patch:mikroorm"
-```
-
-✅ Step 3: Apply the Patch
-After setting up the postinstall script, run:
-
-```sh
-npm i
-```
-
-This will:
-
-Trigger the postinstall hook, which applies the necessary patches to MikroORM and Knex.
-Ensure everything is correctly configured for running inside Forge.
-
-🔧 Why is the Patch Required?
-Atlassian Forge has a restricted execution environment, which does not allow:
-
-- Dynamic import(id) calls, commonly used in MikroORM.
-- Direct file system access, which MikroORM sometimes relies on.
-- Unsupported database dialects, such as PostgreSQL or SQLite.
-- The patch removes these unsupported features to ensure full compatibility.
+- Install Forge-SQL-ORM (the ORM for @forge/sql)
+- Install @forge/sql, the Forge database layer
+- Install Drizzle ORM and its MySQL driver
+- Install TypeScript types for MySQL
 
 ## Step-by-Step Migration Workflow
 
-1. **Generate initial entity models from an existing database**
+1. **Generate initial schema from an existing database**
 
    ```sh
-   npx forge-sql-orm generate:model --dbName testDb --output ./database/entities
+   npx forge-sql-orm generate:model --dbName testDb --output ./database/schema
    ```
 
    _(This is done only once when setting up the project)_
@@ -75,7 +46,7 @@ Atlassian Forge has a restricted execution environment, which does not allow:
 2. **Create the first migration**
 
    ```sh
-   npx forge-sql-orm migrations:create --dbName testDb --entitiesPath ./database/entities --output ./database/migration
+   npx forge-sql-orm migrations:create --dbName testDb --entitiesPath ./database/schema --output ./database/migration
    ```
 
    _(This initializes the database migration structure, also done once)_
@@ -92,575 +63,312 @@ Atlassian Forge has a restricted execution environment, which does not allow:
 5. **Update the migration**
 
    ```sh
-   npx forge-sql-orm migrations:update --dbName testDb --entitiesPath ./database/entities --output ./database/migration
+   npx forge-sql-orm migrations:update --dbName testDb --entitiesPath ./database/schema --output ./database/migration
    ```
 
-   - ⚠️ **Do NOT update entities before this step!**
-   - If entities are updated first, the migration will be empty!
+   - ⚠️ **Do NOT update schema before this step!**
+   - If schema is updated first, the migration will be empty!
 
 6. **Deploy to Forge and verify that the migration runs without issues**
 
    - Run the updated migration on Forge.
 
-7. **Update the entity models**
+7. **Update the schema**
 
    ```sh
-   npx forge-sql-orm generate:model --dbName testDb --output ./database/entities
+   npx forge-sql-orm generate:model --dbName testDb --output ./database/schema
    ```
 
 8. **Repeat steps 4-7 as needed**
 
 **⚠️ WARNING:**
 
-- **Do NOT swap steps 7 and 5!** If you update models before generating a migration, the migration will be empty!
-- Always generate the **migration first**, then update the **entities**.
-
----
-
-# Connection to ORM
-
-```js
-import ForgeSQL from "forge-sql-orm";
-import { Orders } from "./entities/Orders";
-import { Users } from "./entities/Users";
-import ENTITIES from "./entities";
-
-const forgeSQL = new ForgeSQL(ENTITIES);
-```
-
-- Fetch Data:
-
-```js
-const formattedQuery = forgeSQL
-  .createQueryBuilder(Users)
-  .select("*")
-  .limit(limit)
-  .offset(offset)
-  .getFormattedQuery();
-//select `u0`.* from `users` as `u0` limit 10 offset 1
-return await forgeSQL.fetch().executeSchemaSQL(formattedQuery, UsersSchema);
-```
-
-- Raw Fetch Data
-
-```js
-const users = (await forgeSQL.fetch().executeRawSQL) < Users > "SELECT * FROM users";
-```
-
-- Complex Query
-
-```js
-// Define schema for join result
-const innerJoinSchema = forgeSQL.fetch().createComplexQuerySchema();
-schemaBuilder.addField(Users.meta.properties.name);
-schemaBuilder.addField(Orders.meta.properties.product);
-
-// Execute query
-const query = forgeSQL.createQueryBuilder(Orders, "order")
-    .limit(10).offset(10)
-    .innerJoin("user", "user")
-    .select(["user.name", "order.product"])
-    .getFormattedQuery();
-// select `user`.`name`, `order`.`product` from `orders` as `order` inner join `users` as `user` on `order`.`user_id` = `user`.`id` limit 10 offset 10
-const results = await forgeSQL.fetch().executeSchemaSQL(query, innerJoinSchema);
-console.log(results);
-```
-
-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:
-
----
-
-🛠 **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**
+- **Do NOT swap steps 7 and 5!** If you update schema before generating a migration, the migration will be empty!
+- Always generate the **migration first**, then update the **schema**.
 
-  ```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
-
-### 1. Designing the Database
-
-You can start by designing a **MySQL/tidb database** using tools like [DbSchema](https://dbschema.com/) or by using an existing MySQL/tidb database.
+## Drop Migrations
 
-**Schema visualization:**
-![](https://github.com/vzakharchenko/forge-sql-orm/blob/master/img/joinSchema.png?raw=true)
+The Drop Migrations feature allows you to completely reset your database schema in Atlassian Forge SQL. This is useful when you need to:
+- Start fresh with a new schema
+- Reset all tables and their data
+- Clear migration history
+- Ensure your local schema matches the deployed database
 
-#### DDL Scripts
+### Important Requirements
 
-```sql
-CREATE DATABASE testDb;
-CREATE  TABLE testDb.users (
-                              id                   INT    NOT NULL AUTO_INCREMENT   PRIMARY KEY,
-                              name                 VARCHAR(200)
-) engine=InnoDB;
+Before using Drop Migrations, ensure that:
+1. Your local schema exactly matches the current database schema deployed in Atlassian Forge SQL
+2. You have a backup of your data if needed
+3. You understand that this operation will delete all tables and data
 
-CREATE  TABLE testDb.orders (
-                               id                   INT    NOT NULL   PRIMARY KEY,
-                               user_id              INT    NOT NULL   ,
-                               product              VARCHAR(200)
-) engine=InnoDB;
+### Usage
 
-ALTER TABLE testDb.orders ADD CONSTRAINT fk_orders_users FOREIGN KEY ( user_id ) REFERENCES testDb.users( id ) ON DELETE NO ACTION ON UPDATE NO ACTION;
-```
-
-### 2. Generate Models
-
-Run the following command to generate entity models based on your database:
-
-```sh
-npx forge-sql-orm generate:model --host localhost --port 3306 --user root --password secret --dbName testDb --output ./database/entities
-```
-
-This will generate **entity schemas** in the `./database/entities` directory.
-Users Model and Schema:
-
-```js
-import { EntitySchema } from 'forge-sql-orm';
-
-export class Users {
-  id!: number;
-  name?: string;
-}
-
-export const UsersSchema = new EntitySchema({
-  class: Users,
-  properties: {
-    id: { primary: true, type: 'integer', unsigned: false },
-    name: { type: 'string', length: 200, nullable: true },
-  },
-});
-
-```
-
-Orders Model and Schema:
-
-```js
-import { EntitySchema } from 'forge-sql-orm';
-import { Users } from './Users';
-
-export class Orders {
-  id!: number;
-  user!: Users;
-  userId!: number;
-  product?: string;
-}
-
-export const OrdersSchema = new EntitySchema({
-  class: Orders,
-  properties: {
-    id: { primary: true, type: 'integer', unsigned: false, autoincrement: false },
-    user: {
-      kind: 'm:1',
-      entity: () => Users,
-      fieldName: 'user_id',
-      index: 'fk_orders_users',
-    },
-    userId: {
-      type: 'integer',
-      fieldName: 'user_id',
-      persist: false,
-      index: 'fk_orders_users',
-    },
-    product: { type: 'string', length: 200, nullable: true },
-  },
-});
-```
-
-index.ts
-
-```js
-import { Orders } from "./Orders";
-import { Users } from "./Users";
+1. First, ensure your local schema matches the deployed database:
+   ```bash
+   npx forge-sql-orm generate:model --output ./database/schema
+   ```
 
-export default [Orders, Users];
-```
+2. Generate the drop migration:
+   ```bash
+   npx forge-sql-orm migrations:drop --entitiesPath ./database/schema --output ./database/migration
+   ```
 
-### 3. Create the First Migration
+3. Deploy and run the migration in your Forge app:
+   ```js
+   import migrationRunner from "./database/migration";
+   import { MigrationRunner } from "@forge/sql/out/migration";
 
-After generating the models, create the first migration file that represents the current database state:
+   const runner = new MigrationRunner();
+   await migrationRunner(runner);
+   await runner.run();
+   ```
 
-```sh
-npx forge-sql-orm migrations:create --dbName testDb --entitiesPath ./database/entities --output ./database/migration
-```
+4. After dropping all tables, you can create a new migration to recreate the schema:
+   ```bash
+   npx forge-sql-orm migrations:create --entitiesPath ./database/schema --output ./database/migration --force
+   ```
+   The `--force` parameter is required here because we're creating a new migration after dropping all tables.
 
-Generated migration:
+### Example Migration Output
 
+The generated drop migration will look like this:
 ```js
 import { MigrationRunner } from "@forge/sql/out/migration";
 
 export default (migrationRunner: MigrationRunner): MigrationRunner => {
     return migrationRunner
-        .enqueue("v1_MIGRATION0", "create table `users` (`id` int not null auto_increment primary key, `name` varchar(200) null)")
-        .enqueue("v1_MIGRATION1", "create table `orders` (`id` int not null, `user_id` int not null, `product` varchar(200) null, primary key (`id`))")
-        .enqueue("v1_MIGRATION2", "alter table `orders` add index `fk_orders_users`(`user_id`)");
+        .enqueue("v1_MIGRATION0", "ALTER TABLE `orders` DROP FOREIGN KEY `fk_orders_users`")
+        .enqueue("v1_MIGRATION1", "DROP INDEX `idx_orders_user_id` ON `orders`")
+        .enqueue("v1_MIGRATION2", "DROP TABLE IF EXISTS `orders`")
+        .enqueue("v1_MIGRATION3", "DROP TABLE IF EXISTS `users`")
+        .enqueue("MIGRATION_V1_1234567890", "DELETE FROM __migrations");
 };
 ```
 
-### 4. Deploy and Run Migrations
+### ⚠️ Important Notes
 
-```js
-import migration from "./database/migration";
-import sql, { migrationRunner } from "@forge/sql";
-
-export const trigger = async () => {
-  console.log("Provisioning the database");
-  await sql._provision();
-
-  console.log("Running schema migrations");
-  const migrations = await migration(migrationRunner);
-  const successfulMigrations = await migrations.run();
-  console.log("Migrations applied:", successfulMigrations);
-
-  const migrationHistory = (await migrationRunner.list())
-    .map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`)
-    .join("\n");
-
-  console.log("Migrations history:\nid, name, migrated_at\n", migrationHistory);
-
-  return {
-    headers: { "Content-Type": ["application/json"] },
-    statusCode: 200,
-    statusText: "OK",
-    body: "Migrations successfully executed",
-  };
-};
-```
+- This operation is **irreversible** - all data will be lost
+- Make sure your local schema is up-to-date with the deployed database
+- Consider backing up your data before running drop migrations
+- The migration will clear the `__migrations` table to allow for fresh migration history
+- Drop operations are performed in the correct order: first foreign keys, then indexes, then tables
 
-### 5. Running Queries
+---
 
-Once the migrations are applied, you can start working with the ORM:
+# Connection to ORM
 
 ```js
-import Entities from "./entities";
 import ForgeSQL from "forge-sql-orm";
-import { UsersSchema, Users } from "./entities/Users";
-
-const forgeSQL = new ForgeSQL(ENTITIES);
-
-// Insert Data
-const user = new Users();
-user.name = "John Doe";
-const userId = await forgeSQL.crud().insert(UsersSchema, [user]);
-console.log("Inserted User ID:", userId);
 
-// Fetch Users
-const users = await forgeSQL.fetch().executeSchemaSQL("SELECT * FROM users", UsersSchema);
-console.log(users);
+const forgeSQL = new ForgeSQL();
 ```
 
-### 6. Updating Database Schema
+## Fetch Data
 
-If you modify the database schema, you can generate an update migration:
-
-Modify the schema in DbSchema
-![](https://github.com/vzakharchenko/forge-sql-orm/blob/master/img/joinSchema2.png?raw=true)
-or manually run:
-
-```sh
-ALTER TABLE `users` ADD email VARCHAR(255);
-```
-
-Then, generate a new migration:
-
-```sh
-npx forge-sql-orm migrations:update --dbName testDb --entitiesPath ./database/entities --output ./database/migration
-```
-
-Generated migration:
+### Basic Fetch Operations
 
 ```js
-import { MigrationRunner } from "@forge/sql/out/migration";
-
-export default (migrationRunner: MigrationRunner): MigrationRunner => {
-    return migrationRunner.enqueue("v2_MIGRATION0", "alter table `users` add `email` varchar(255) null");
-};
-```
+// Using executeQuery for single result
+const user = await forgeSQL
+  .fetch()
+  .executeQuery(
+    forgeSQL.getDrizzleQueryBuilder()
+      .select("*").from(Users)
+      .where(eq(Users.id, 1))
+  );
+// Returns: { id: 1, name: "John Doe" }
 
-### 7. Updating Entities
+// Using executeQueryOnlyOne for single result with error handling
+const user = await forgeSQL
+  .fetch()
+  .executeQueryOnlyOne(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select("*").from(Users)
+      .where(eq(Users.id, 1))
+  );
+// Returns: { id: 1, name: "John Doe" }
+// Throws error if multiple records found
+// Returns undefined if no records found
 
-After applying the migration, update your entity models:
+// Using executeQuery with aliases
+const usersAlias = alias(Users, "u");
+const result = await forgeSQL
+  .fetch()
+  .executeQuery(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select({
+        userId: rawSql`${usersAlias.id} as \`userId\``,
+        userName: rawSql`${usersAlias.name} as \`userName\``
+      }).from(usersAlias)
+  );
+// Returns: { userId: 1, userName: "John Doe" }
 
-```sh
-npx forge-sql-orm generate:model --dbName testDb --output ./database/entities
+// Using executeQuery with joins
+const orderWithUser = await forgeSQL
+  .fetch()
+  .executeQuery(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select({
+        orderId: rawSql`${Orders.id} as \`orderId\``,
+        product: Orders.product,
+        userName: rawSql`${Users.name} as \`userName\``
+      }).from(Orders)
+      .innerJoin(Users, eq(Orders.userId, Users.id))
+      .where(eq(Orders.id, 1))
+  );
+// Returns: { orderId: 1, product: "Product 1", userName: "John Doe" }
 ```
 
-Updated Users Model and Schema:
+### Complex Queries with Aggregations
 
 ```js
-import { EntitySchema } from 'forge-sql-orm';
-
-export class Users {
-  id!: number;
-  name?: string;
-  email?: string;
-}
-
-export const UsersSchema = new EntitySchema({
-  class: Users,
-  properties: {
-    id: { primary: true, type: 'integer', unsigned: false },
-    name: { type: 'string', length: 200, nullable: true },
-    email: { type: 'string', nullable: true },
-  },
-});
+// Finding duplicates
+const duplicates = await forgeSQL
+  .fetch()
+  .executeQuery(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select({
+        name: Users.name,
+        count: rawSql`COUNT(*) as \`count\``
+      }).from(Users)
+      .groupBy(Users.name)
+      .having(rawSql`COUNT(*) > 1`)
+  );
+// Returns: { name: "John Doe", count: 2 }
 
+// Using executeQueryOnlyOne for unique results
+const userStats = await forgeSQL
+  .fetch()
+  .executeQueryOnlyOne(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select({
+        totalUsers: rawSql`COUNT(*) as \`totalUsers\``,
+        uniqueNames: rawSql`COUNT(DISTINCT name) as \`uniqueNames\``
+      }).from(Users)
+  );
+// Returns: { totalUsers: 100, uniqueNames: 80 }
+// Throws error if multiple records found
 ```
 
----
+### Raw SQL Queries
 
-## Complex Queries
-
-### INNER JOIN Example
-
-Using **ForgeSQLORM**, you can perform complex queries with joins.  
-For example, fetching **users and their purchased products**:
-
-```ts
-import ForgeSQL, { EntitySchema } from "forge-sql-orm";
-import { Orders } from "./entities/Orders";
-import { Users } from "./entities/Users";
-import ENTITIES from "./entities";
-
-const forgeSQL = new ForgeSQL(ENTITIES);
-
-// Define schema for join result
-class InnerJoinResult {
-  name!: string;
-  product!: string;
-}
-
-export const innerJoinSchema = new EntitySchema<InnerJoinResult>({
-  class: InnerJoinResult,
-  properties: {
-    name: { type: "string", fieldName: "name" },
-    product: { type: "string", fieldName: "product" },
-  },
-});
-innerJoinSchema.init();
-
-// Execute query
-const query = forgeSQL
-  .createQueryBuilder(Orders, "order")
-  .limit(10)
-  .offset(0)
-  .innerJoin("user", "user")
-  .select(["user.name", "order.product"])
-  .getFormattedQuery();
-
-const results = await forgeSQL.fetch().executeSchemaSQL(query, innerJoinSchema);
-console.log(results);
+```js
+// Using executeRawSQL for direct SQL queries
+const users = await forgeSQL
+  .fetch()
+  .executeRawSQL<Users>("SELECT * FROM users");
 ```
 
----
+## CRUD Operations
 
-## ForgeSqlOrmOptions
+### Insert Operations
 
-The `ForgeSqlOrmOptions` object allows customization of ORM behavior. Currently, it supports the following options:
+  ```js
+// Single insert
+const userId = await forgeSQL.crud().insert(Users, [{ id: 1, name: "Smith" }]);
 
-| 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. |
+// Bulk insert
+await forgeSQL.crud().insert(Users, [
+    { id: 2, name: "Smith" },
+    { id: 3, name: "Vasyl" },
+  ]);
 
----
+// Insert with duplicate handling
+  await forgeSQL.crud().insert(
+  Users,
+    [
+      { id: 4, name: "Smith" },
+      { id: 4, name: "Vasyl" },
+    ],
+  true
+  );
+  ```
 
-### Example: Initializing `ForgeSQL` with Options
+### Update Operations
 
-```typescript
-import ForgeSQL from "forge-sql-orm";
-import { Orders } from "./entities/Orders";
-import { Users } from "./entities/Users";
-import ENTITIES from "./entities";
+  ```js
+// Update by ID with optimistic locking
+await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, Users);
 
-const options = {
-  logRawSqlQuery: true, // Enable query logging for debugging purposes
-};
+// Update specific fields
+await forgeSQL.crud().updateById(
+  { id: 1,  age: 35 },
+  Users
+);
 
-const forgeSQL = new ForgeSQL(ENTITIES, options);
+// Update with custom WHERE condition
+await forgeSQL.crud().updateFields(
+    { name: "New Name", age: 35 },
+  Users,
+  eq(Users.email, "smith@example.com")
+);
 ```
 
-## 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.
+### Delete Operations
 
-### 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);
+```js
+// Delete by ID
+await forgeSQL.crud().deleteById(1, Users);
 ```
 
-🔹 **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.
-
----
-
 ## 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.
+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.
 
-### How It Works
+### Supported Version Field Types
 
-- **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`.
+- `datetime` - Timestamp-based versioning
+- `timestamp` - Timestamp-based versioning
+- `integer` - Numeric version increment
+- `decimal` - Numeric version increment
 
-- **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.
+### Configuration
 
-- **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:
+```typescript
+const options = {
+  additionalMetadata: {
+    users: {
+      tableName: "users",
+      versionField: {
+        fieldName: "updatedAt",
+      }
+    }
+  }
+};
 
-```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 },
-  },
-});
+const forgeSQL = new ForgeSQL(options);
 ```
 
-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
+### Example Usage
 
-If you prefer to use MikroORM's default entity generator, then manually import your entities:
-
-```ts
-import { UserEntity, TaskEntity } from "./entities";
+```typescript
+// The version field will be automatically handled
+await forgeSQL.crud().updateById(
+  { 
+    id: 1, 
+    name: "Updated Name",
+    updatedAt: new Date() // Will be automatically set if not provided
+  }, 
+  Users
+);
 ```
 
----
-
-## Forge SQL ORM CLI Documentation
+## ForgeSqlOrmOptions
 
-The CLI provides commands to generate models and manage migrations for MikroORM in Forge.
+The `ForgeSqlOrmOptions` object allows customization of ORM behavior:
 
----
+| 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. |
+| `additionalMetadata`       | `object`  | Allows adding custom metadata to all entities. This is useful for tracking common fields across all tables (e.g., `createdAt`, `updatedAt`, `createdBy`, etc.). The metadata will be automatically added to all generated entities. |
 
-### 📌 Available Commands
+## CLI Commands
 
 ```sh
 $ npx forge-sql-orm --help
@@ -672,140 +380,13 @@ Options:
   -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 a specific command.
+  generate:model [options]     Generate Drizzle 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
+  migrations:drop [options]    Generate a migration to drop all tables
+  help [command]               Display help for a specific command
 ```
 
----
-
-### 📌 Entity Generation
-
-```sh
-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.
-- **`--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:**
-
-- `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 --saveEnv
-```
-
-This command will:
-
-- 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
-
-```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 --saveEnv
-```
-
-This command will:
-
-- 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.
-
----
-
-### 📌 Using the patch:mikroorm Command
-
-If needed, you can manually apply the patch at any time using:
-
-```sh
-npx forge-sql-orm patch:mikroorm
-```
-
-This command:
-
-- Removes unsupported database dialects (e.g., PostgreSQL, SQLite).
-- Fixes dynamic imports to work in Forge.
-- Ensures Knex and MikroORM work properly inside Forge.
-
----
-
-### 📌 Configuration Methods
-
-You can define database credentials using:
-
-1️⃣ **Command-line arguments**:
-
-```sh
---host, --port, --user, --password, --dbName, --output, --versionField, --saveEnv
-```
-
-2️⃣ **Environment variables**:
-
-```bash
-export FORGE_SQL_ORM_HOST=localhost
-export FORGE_SQL_ORM_PORT=3306
-export FORGE_SQL_ORM_USER=root
-export FORGE_SQL_ORM_PASSWORD=secret
-export FORGE_SQL_ORM_DBNAME=mydb
-```
-
-3️⃣ **Using a `.env` file**:
-
-```sh
-FORGE_SQL_ORM_HOST=localhost
-FORGE_SQL_ORM_PORT=3306
-FORGE_SQL_ORM_USER=root
-FORGE_SQL_ORM_PASSWORD=secret
-FORGE_SQL_ORM_DBNAME=mydb
-```
-
-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.
-
----
-
-📜 **License**
+## License
 This project is licensed under the **MIT License**.  
 Feel free to use it for commercial and personal projects.