forge-sql-orm 2.0.8 → 2.0.10

package/src/core/ForgeSQLQueryBuilder.ts

@@ -1,6 +1,5 @@
 import { UpdateQueryResponse } from "@forge/sql";
 import { SqlParameters } from "@forge/sql/out/sql-statement";
-import { MySql2Database } from "drizzle-orm/mysql2/driver";
 import {
   AnyMySqlSelectQueryBuilder,
   AnyMySqlTable,
@@ -14,7 +13,7 @@ import {
 import { InferInsertModel, SQL } from "drizzle-orm";
 import moment from "moment/moment";
 import { parseDateTime } from "../utils/sqlUtils";
-import { MySql2PreparedQueryHKT } from "drizzle-orm/mysql2/index";
+import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT } from "drizzle-orm/mysql-proxy/index";
 
 // ============= Core Types =============
 
@@ -45,15 +44,47 @@ export interface QueryBuilderForgeSql {
    * Creates a new query builder for the given entity.
    * @returns {MySql2Database<Record<string, unknown>>} The Drizzle database instance for building queries
    */
-  getDrizzleQueryBuilder(): MySql2Database<Record<string, unknown>>;
+  getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>>;
 
+  /**
+   * Creates a select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   *
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>} A select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .select({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
   select<TSelection extends SelectedFields>(
     fields: TSelection,
-  ): MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>;
+  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
 
+  /**
+   * Creates a distinct select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   *
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>} A distinct select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .selectDistinct({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
   selectDistinct<TSelection extends SelectedFields>(
     fields: TSelection,
-  ): MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>;
+  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
 }
 
 // ============= CRUD Operations =============

package/src/core/SystemTables.ts

@@ -1,7 +1,10 @@
-import { int, mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core/index";
+import { bigint, mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
+import { Table } from "drizzle-orm";
 
 export const migrations = mysqlTable("__migrations", {
-  id: int("id").primaryKey().autoincrement(),
+  id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
   name: varchar("name", { length: 255 }).notNull(),
-  created_at: timestamp("created_at").defaultNow().notNull(),
+  migratedAt: timestamp("migratedAt").defaultNow().notNull(),
 });
+
+export const forgeSystemTables: Table[] = [migrations];

package/src/utils/forgeDriver.ts

@@ -1,28 +1,39 @@
-import { sql } from "@forge/sql";
-import { AnyMySql2Connection } from "drizzle-orm/mysql2/driver";
+import { sql, UpdateQueryResponse } from "@forge/sql";
 
 interface ForgeSQLResult {
   rows: Record<string, unknown>[] | Record<string, unknown>;
 }
 
-export const forgeDriver = {
-  query: async (query: { sql: string }, params?: unknown[]) => {
-    try {
-      const sqlStatement = await sql.prepare<unknown>(query.sql);
+export const forgeDriver = async (
+  query: string,
+  params: any[],
+  method: "all" | "execute",
+): Promise<{
+  rows: any[];
+  insertId?: number;
+  affectedRows?: number;
+}> => {
+  try {
+    if (method == "execute") {
+      const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+      if (params) {
+        sqlStatement.bindParams(...params);
+      }
+      const updateQueryResponseResults = await sqlStatement.execute();
+      let result = updateQueryResponseResults.rows as any;
+      return { ...result, rows: [result] };
+    } else {
+      const sqlStatement = await sql.prepare<unknown>(query);
       if (params) {
         await sqlStatement.bindParams(...params);
       }
       const result = (await sqlStatement.execute()) as ForgeSQLResult;
       let rows;
-      if (Array.isArray(result.rows)) {
-        rows = [result.rows.map((r) => Object.values(r as Record<string, unknown>))];
-      } else {
-        rows = [result.rows as Record<string, unknown>];
-      }
-      return rows;
-    } catch (error) {
-      console.error("SQL Error:", JSON.stringify(error));
-      throw error;
+      rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+      return { rows: rows };
     }
-  },
-} as unknown as AnyMySql2Connection;
+  } catch (error) {
+    console.error("SQL Error:", JSON.stringify(error));
+    throw error;
+  }
+};

package/src/webtriggers/applyMigrationsWebTrigger.ts

@@ -1,6 +1,29 @@
 import { migrationRunner, sql } from "@forge/sql";
 import { MigrationRunner } from "@forge/sql/out/migration";
 
+/**
+ * Web trigger for applying database schema migrations in Atlassian Forge SQL.
+ * This function handles the complete migration process including:
+ * - Database provisioning
+ * - Migration execution
+ * - Migration history tracking
+ *
+ * @param migration - A function that takes a MigrationRunner instance and returns a Promise of MigrationRunner
+ *                     This function should define the sequence of migrations to be applied
+ * @returns {Promise<{
+ *   headers: { "Content-Type": ["application/json"] },
+ *   statusCode: number,
+ *   statusText: string,
+ *   body: string
+ * }>} A response object containing:
+ * - headers: Content-Type header set to application/json
+ * - statusCode: 200 on success
+ * - statusText: "OK" on success
+ * - body: Success message or error details
+ *
+ * @throws {Error} If database provisioning fails
+ * @throws {Error} If migration execution fails
+ */
 export const applySchemaMigrations = async (
   migration: (migrationRunner: MigrationRunner) => Promise<MigrationRunner>,
 ) => {

package/src/webtriggers/dropMigrationWebTrigger.ts

@@ -4,12 +4,28 @@ import { generateDropTableStatements as generateStatements } from "../utils/sqlU
 import { getHttpResponse, TriggerResponse } from "./index";
 
 /**
- * ⚠️ WARNING: This web trigger will permanently delete all data in the specified tables.
- * DO NOT use this in production environment as it will cause irreversible data loss.
+ * ⚠️ DEVELOPMENT ONLY WEB TRIGGER ⚠️
+ *
+ * This web trigger is designed for development environments only and will permanently delete all data in the specified tables.
+ * It generates and executes SQL statements to drop tables and their associated constraints.
+ *
+ * @warning This trigger should NEVER be used in production environments because:
+ * - It permanently deletes all data in the specified tables
+ * - The operation cannot be undone
+ * - It may affect application functionality
+ * - It could lead to data loss and system instability
  *
- * Generates SQL statements to drop tables and executes them
  * @param tables - Array of table schemas to drop
- * @returns Trigger response with execution status and list of dropped tables
+ * @returns {Promise<TriggerResponse<string>>} A response containing:
+ * - On success: 200 status with warning message about permanent deletion
+ * - On failure: 500 status with error message
+ *
+ * @example
+ * ```typescript
+ * // Example usage in development only
+ * await dropSchemaMigrations([users, orders]);
+ * // ⚠️ Warning: This will permanently delete all data in users and orders tables
+ * ```
  */
 export async function dropSchemaMigrations(
   tables: AnyMySqlTable[],

package/src/webtriggers/fetchSchemaWebTrigger.ts

@@ -0,0 +1,96 @@
+import { sql } from "@forge/sql";
+import { getHttpResponse, TriggerResponse } from "./index";
+import { forgeSystemTables } from "../core/SystemTables";
+import { getTableName } from "drizzle-orm/table";
+
+interface CreateTableRow {
+  Table: string;
+  "Create Table": string;
+}
+
+/**
+ * ⚠️ DEVELOPMENT ONLY WEB TRIGGER ⚠️
+ *
+ * This web trigger retrieves the current database schema from Atlassian Forge SQL.
+ * It generates SQL statements that can be used to recreate the database structure.
+ *
+ * @warning This trigger should ONLY be used in development environments. It:
+ * - Exposes your database structure
+ * - Disables foreign key checks temporarily
+ * - Generates SQL that could potentially be used maliciously
+ * - May expose sensitive table names and structures
+ *
+ * @returns {Promise<TriggerResponse<string>>} A response containing SQL statements to recreate the database schema
+ * - On success: Returns 200 status with SQL statements
+ * - On failure: Returns 500 status with error message
+ *
+ * @example
+ * ```typescript
+ * // The response will contain SQL statements like:
+ * // SET foreign_key_checks = 0;
+ * // CREATE TABLE IF NOT EXISTS users (...);
+ * // CREATE TABLE IF NOT EXISTS orders (...);
+ * // SET foreign_key_checks = 1;
+ * ```
+ */
+export async function fetchSchemaWebTrigger(): Promise<TriggerResponse<string>> {
+  try {
+    const tables = await getTables();
+    const createTableStatements = await generateCreateTableStatements(tables);
+    const sqlStatements = wrapWithForeignKeyChecks(createTableStatements);
+
+    return getHttpResponse<string>(200, sqlStatements.join(";\n"));
+  } catch (error: unknown) {
+    console.error(JSON.stringify(error));
+    const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+    return getHttpResponse<string>(500, errorMessage);
+  }
+}
+
+/**
+ * Retrieves all tables from the database
+ */
+async function getTables(): Promise<string[]> {
+  const tables = await sql.executeDDL<string>("SHOW TABLES");
+  return tables.rows.flatMap((tableInfo) => Object.values(tableInfo));
+}
+
+/**
+ * Generates CREATE TABLE statements for each table
+ */
+async function generateCreateTableStatements(tables: string[]): Promise<string[]> {
+  const statements: string[] = [];
+
+  for (const table of tables) {
+    const createTableResult = await sql.executeDDL<CreateTableRow>(`SHOW CREATE TABLE ${table}`);
+
+    const createTableStatements = createTableResult.rows
+      .filter((row) => !isSystemTable(row.Table))
+      .map((row) => formatCreateTableStatement(row["Create Table"]));
+
+    statements.push(...createTableStatements);
+  }
+
+  return statements;
+}
+
+/**
+ * Checks if the table is a system table
+ */
+function isSystemTable(tableName: string): boolean {
+  return forgeSystemTables.some((st) => getTableName(st) === tableName);
+}
+
+/**
+ * Formats the CREATE TABLE statement
+ */
+function formatCreateTableStatement(statement: string): string {
+  return statement.replace(/"/g, "").replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS");
+}
+
+/**
+ * Wraps the SQL statements with foreign key check controls
+ */
+function wrapWithForeignKeyChecks(statements: string[]): string[] {
+  return ["SET foreign_key_checks = 0", ...statements, "SET foreign_key_checks = 1"];
+}

package/src/webtriggers/index.ts

@@ -1,5 +1,6 @@
 export * from "./dropMigrationWebTrigger";
 export * from "./applyMigrationsWebTrigger";
+export * from "./fetchSchemaWebTrigger";
 
 export interface TriggerResponse<BODY> {
   body?: BODY;