forge-sql-orm 2.0.6 → 2.0.8

package/README.md

@@ -23,14 +23,53 @@ import { drizzle } from "drizzle-orm/mysql-core";
 import { forgeDriver } from "forge-sql-orm";
 const db = drizzle(forgeDriver);
 ```
-Best for: Simple CRUD operations without optimistic locking
+Best for: Simple CRUD operations without optimistic locking. Note that you need to manually set `mapSelectFieldsWithAlias` for select fields to prevent field name collisions in Atlassian Forge SQL.
 
 ### 2. Full Forge-SQL-ORM Usage
 ```typescript
 import ForgeSQL from "forge-sql-orm";
 const forgeSQL = new ForgeSQL();
 ```
-Best for: Advanced features like optimistic locking and automatic versioning
+Best for: Advanced features like optimistic locking, automatic versioning, and automatic field name collision prevention in complex queries.
+
+## Field Name Collision Prevention in Complex Queries
+
+When working with complex queries involving multiple tables (joins, inner joins, etc.), Atlassian Forge SQL has a specific behavior where fields with the same name from different tables get collapsed into a single field with a null value. This is not a Drizzle ORM issue but rather a characteristic of Atlassian Forge SQL's behavior.
+
+Forge-SQL-ORM provides two ways to handle this:
+
+### Using Forge-SQL-ORM
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+// Automatic field name collision prevention
+await forgeSQL
+  .select({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+```
+
+### Using Direct Drizzle
+```typescript
+import { drizzle } from "drizzle-orm/mysql-core";
+import { forgeDriver, mapSelectFieldsWithAlias } from "forge-sql-orm";
+
+const db = drizzle(forgeDriver);
+
+// Manual field name collision prevention
+await db
+  .select(mapSelectFieldsWithAlias({user: users, order: orders}))
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+```
+
+### Important Notes
+- This is a specific behavior of Atlassian Forge SQL, not Drizzle ORM
+- For complex queries involving multiple tables, it's recommended to always specify select fields and avoid using `select()` without field selection
+- The solution automatically creates unique aliases for each field by prefixing them with the table name
+- This ensures that fields with the same name from different tables remain distinct in the query results
 
 ## Installation
 
@@ -40,7 +79,7 @@ Forge-SQL-ORM is designed to work with @forge/sql and requires some additional s
 
 ```sh
 npm install forge-sql-orm @forge/sql drizzle-orm momment -S
-npm install mysql2 @types/mysql2 drizzle-kit -D
+npm install mysql2 drizzle-kit inquirer@8.0.0  -D
 ```
 
 This will:
@@ -293,13 +332,13 @@ const users = await db.select().from(users);
 // Using forgeSQL.getDrizzleQueryBuilder()
 const user = await forgeSQL
   .getDrizzleQueryBuilder()
-  .select("*").from(Users)
+  .select().from(Users)
   .where(eq(Users.id, 1));
 
 // OR using direct drizzle with custom driver
 const db = drizzle(forgeDriver);
 const user = await db
-  .select("*").from(Users)
+  .select().from(Users)
   .where(eq(Users.id, 1));
 // Returns: { id: 1, name: "John Doe" }
 
@@ -309,7 +348,7 @@ const user = await forgeSQL
   .executeQueryOnlyOne(
     forgeSQL
       .getDrizzleQueryBuilder()
-      .select("*").from(Users)
+      .select().from(Users)
       .where(eq(Users.id, 1))
   );
 // Returns: { id: 1, name: "John Doe" }
@@ -322,24 +361,306 @@ const usersAlias = alias(Users, "u");
 const result = await forgeSQL
   .getDrizzleQueryBuilder()
   .select({
-    userId: rawSql`${usersAlias.id} as \`userId\``,
-    userName: rawSql`${usersAlias.name} as \`userName\``
+    userId: sql<string>`${usersAlias.id} as \`userId\``,
+    userName: sql<string>`${usersAlias.name} as \`userName\``
   }).from(usersAlias);
 
 // OR with direct drizzle
 const db = drizzle(forgeDriver);
 const result = await db
   .select({
-    userId: rawSql`${usersAlias.id} as \`userId\``,
-    userName: rawSql`${usersAlias.name} as \`userName\``
+    userId: sql<string>`${usersAlias.id} as \`userId\``,
+    userName: sql<string>`${usersAlias.name} as \`userName\``
   }).from(usersAlias);
 // Returns: { userId: 1, userName: "John Doe" }
+```
 
-// Using joins
+### Complex Queries
+```js
+
+// Using joins with automatic field name collision prevention
 // With forgeSQL
 const orderWithUser = await forgeSQL
+  .select({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+
+// OR with direct drizzle
+const db = drizzle(forgeDriver);
+const orderWithUser = await db
+  .select(mapSelectFieldsWithAlias({user: users, order: orders}))
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+// Returns: { 
+//   user_id: 1, 
+//   user_name: "John Doe",
+//   order_id: 1,
+//   order_product: "Product 1"
+// }
+
+// Using distinct select with automatic field name collision prevention
+const uniqueOrdersWithUsers = await forgeSQL
+  .selectDistinct({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+
+// Finding duplicates
+// With forgeSQL
+const duplicates = await forgeSQL
   .getDrizzleQueryBuilder()
   .select({
-    orderId: rawSql`${Orders.id} as \`orderId\``,
-    product: Orders.product,
-    userName: rawSql`${Users.name} as \`
+    name: Users.name,
+    count: sql<number>`COUNT(*) as \`count\``
+  }).from(Users)
+  .groupBy(Users.name)
+  .having(sql`COUNT(*) > 1`);
+
+// OR with direct drizzle
+const db = drizzle(forgeDriver);
+const duplicates = await db
+  .select({
+    name: Users.name,
+    count: sql<number>`COUNT(*) as \`count\``
+  }).from(Users)
+  .groupBy(Users.name)
+  .having(sql`COUNT(*) > 1`);
+// Returns: { name: "John Doe", count: 2 }
+
+// Using executeQueryOnlyOne for unique results
+const userStats = await forgeSQL
+  .fetch()
+  .executeQueryOnlyOne(
+    forgeSQL
+      .getDrizzleQueryBuilder()
+      .select({
+        totalUsers: sql`COUNT(*) as \`totalUsers\``,
+        uniqueNames: sql`COUNT(DISTINCT name) as \`uniqueNames\``
+      }).from(Users)
+  );
+// Returns: { totalUsers: 100, uniqueNames: 80 }
+// Throws error if multiple records found
+```
+
+### Raw SQL Queries
+
+```js
+// Using executeRawSQL for direct SQL queries
+const users = await forgeSQL
+  .fetch()
+  .executeRawSQL<Users>("SELECT * FROM users");
+```
+
+## CRUD Operations
+
+### Insert Operations
+
+  ```js
+// Single insert
+const userId = await forgeSQL.crud().insert(Users, [{ id: 1, name: "Smith" }]);
+
+// 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
+  );
+  ```
+
+### Update Operations
+
+  ```js
+// Update by ID with optimistic locking
+await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, Users);
+
+// Update specific fields
+await forgeSQL.crud().updateById(
+  { id: 1,  age: 35 },
+  Users
+);
+
+// Update with custom WHERE condition
+await forgeSQL.crud().updateFields(
+    { name: "New Name", age: 35 },
+  Users,
+  eq(Users.email, "smith@example.com")
+);
+```
+
+### Delete Operations
+
+```js
+// Delete by ID
+await forgeSQL.crud().deleteById(1, Users);
+```
+
+## 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.
+
+### Supported Version Field Types
+
+- `datetime` - Timestamp-based versioning
+- `timestamp` - Timestamp-based versioning
+- `integer` - Numeric version increment
+- `decimal` - Numeric version increment
+
+### Configuration
+
+```typescript
+const options = {
+  additionalMetadata: {
+    users: {
+      tableName: "users",
+      versionField: {
+        fieldName: "updatedAt",
+      }
+    }
+  }
+};
+
+const forgeSQL = new ForgeSQL(options);
+```
+
+### Example Usage
+
+```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
+);
+```
+
+## ForgeSqlOrmOptions
+
+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. |
+
+## CLI Commands
+
+```sh
+$ npx forge-sql-orm --help
+
+Usage: forge-sql-orm [options] [command]
+
+Options:
+  -V, --version                Output the version number
+  -h, --help                   Display help for command
+
+Commands:
+  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
+```
+
+## Web Triggers for Migrations
+
+Forge-SQL-ORM provides two web triggers for managing database migrations in Atlassian Forge:
+
+### 1. Apply Migrations Trigger
+
+This trigger allows you to apply database migrations through a web endpoint. It's useful for:
+- Manually triggering migrations 
+- Running migrations as part of your deployment process
+- Testing migrations in different environments
+
+```typescript
+// Example usage in your Forge app
+import { applySchemaMigrations } from "forge-sql-orm";
+import migration from "./migration";
+
+export const handlerMigration = async () => {
+  return applySchemaMigrations(migration);
+};
+```
+
+Configure in `manifest.yml`:
+```yaml
+  webtrigger:
+     - key: invoke-schema-migration
+       function: runSchemaMigration
+       security:
+          egress:
+             allowDataEgress: false
+             allowedResponses:
+                - statusCode: 200
+                  body: '{"body": "Migrations successfully executed"}'
+  sql:
+     - key: main
+       engine: mysql
+  function:
+     - key: runSchemaMigration
+       handler: index.handlerMigration
+```
+
+### 2. Drop Migrations Trigger
+
+⚠️ **WARNING**: This trigger will permanently delete all data in the specified tables and clear the migrations history. This operation cannot be undone!
+
+This trigger allows you to completely reset your database schema. It's useful for:
+- Development environments where you need to start fresh
+- Testing scenarios requiring a clean database
+- Resetting the database before applying new migrations
+
+**Important**: The trigger will only drop tables that are defined in your models. Any tables that exist in the database but are not defined in your models will remain untouched.
+
+```typescript
+// Example usage in your Forge app
+import { dropSchemaMigrations } from "forge-sql-orm";
+import * as schema from "./entities/schema";
+
+export const dropMigrations = () => {
+  return dropSchemaMigrations(Object.values(schema));
+};
+```
+
+Configure in `manifest.yml`:
+```yaml
+  webtrigger:
+     - key: drop-schema-migration
+       function: dropMigrations
+  sql:
+     - key: main
+       engine: mysql
+  function:
+     - key: dropMigrations
+       handler: index.dropMigrations
+```
+
+### Important Notes
+
+**Security Considerations**:
+   - The drop migrations trigger should be restricted to development environments
+   - Consider implementing additional authentication for these endpoints
+   - Use the `security` section in `manifest.yml` to control access
+
+**Best Practices**:
+   - Always backup your data before using the drop migrations trigger
+   - Test migrations in a development environment first
+   - Use these triggers as part of your deployment pipeline
+   - Monitor the execution logs in the Forge Developer Console
+
+
+## License
+This project is licensed under the **MIT License**.  
+Feel free to use it for commercial and personal projects.