@axiosleo/orm-mysql 0.11.12 → 0.12.0

package/README.md

@@ -177,6 +177,53 @@ Hook.post(async (options, result) => {
 
 ### Transaction
 
+#### Method 1: Using Connection Pool (Recommended)
+
+```javascript
+const mysql = require("mysql2");
+const { QueryHandler } = require("@axiosleo/orm-mysql");
+
+// Create connection pool
+const pool = mysql.createPool({
+  host: process.env.MYSQL_HOST,
+  port: process.env.MYSQL_PORT,
+  user: process.env.MYSQL_USER,
+  password: process.env.MYSQL_PASS,
+  database: process.env.MYSQL_DB,
+  connectionLimit: 10
+});
+
+const handler = new QueryHandler(pool);
+
+// Begin transaction - automatically gets a connection from pool
+const transaction = await handler.beginTransaction({ 
+  level: "RC" // READ COMMITTED
+});
+
+try {
+  // Insert user info
+  let row = await transaction.table("users").insert({
+    name: "Joe",
+    age: 18,
+  });
+  const lastInsertId = row.insertId;
+
+  // Insert student info
+  await transaction.table("students").insert({
+    user_id: lastInsertId,
+  });
+  
+  // Commit transaction - connection automatically released back to pool
+  await transaction.commit();
+} catch (e) {
+  // Rollback transaction - connection automatically released back to pool
+  await transaction.rollback();
+  throw e;
+}
+```
+
+#### Method 2: Using TransactionHandler Directly
+
 ```javascript
 const { TransactionHandler, createPromiseClient } = require("@axiosleo/orm-mysql");
 
@@ -190,25 +237,25 @@ const conn = await createPromiseClient({
 
 const transaction = new TransactionHandler(conn, {
   /*
-  level = 'READ UNCOMMITTED' | 'RU'
-        | 'READ COMMITTED' | 'RC'
-        | 'REPEATABLE READ' | 'RR'
-        | 'SERIALIZABLE' | 'S'
+  Transaction Isolation Levels:
+  - 'READ UNCOMMITTED' | 'RU'  : Lowest isolation, may read dirty data
+  - 'READ COMMITTED'   | 'RC'  : Prevents dirty reads
+  - 'REPEATABLE READ'  | 'RR'  : MySQL default, prevents non-repeatable reads
+  - 'SERIALIZABLE'     | 'S'   : Highest isolation, full serialization
   */
   level: "SERIALIZABLE", // 'SERIALIZABLE' as default value
 });
 await transaction.begin();
 
 try {
-  // insert user info
-  // will not really create a record.
+  // Insert user info
   let row = await transaction.table("users").insert({
     name: "Joe",
     age: 18,
   });
   const lastInsertId = row[0].insertId;
 
-  // insert student info
+  // Insert student info
   await transaction.table("students").insert({
     user_id: lastInsertId,
   });
@@ -219,6 +266,95 @@ try {
 }
 ```
 
+#### Row Locking with FOR UPDATE
+
+```javascript
+const transaction = await handler.beginTransaction({ level: "RC" });
+
+try {
+  // Lock rows for update
+  const product = await transaction.table("products")
+    .where("sku", "LAPTOP-001")
+    .append("FOR UPDATE")  // Lock the row
+    .find();
+
+  if (product.stock < 1) {
+    throw new Error("Out of stock");
+  }
+
+  // Update stock
+  await transaction.table("products")
+    .where("sku", "LAPTOP-001")
+    .update({ stock: product.stock - 1 });
+
+  // Create order
+  await transaction.table("orders").insert({
+    product_id: product.id,
+    quantity: 1,
+    total: product.price
+  });
+
+  await transaction.commit();
+} catch (e) {
+  await transaction.rollback();
+  throw e;
+}
+```
+
+#### Concurrent Transactions
+
+When using a connection pool, multiple transactions can run concurrently without blocking each other:
+
+```javascript
+const pool = mysql.createPool({ /* ... */ });
+const handler = new QueryHandler(pool);
+
+// Run 3 transactions concurrently
+await Promise.all([
+  (async () => {
+    const tx = await handler.beginTransaction();
+    try {
+      await tx.table("users").insert({ name: "User1" });
+      await tx.commit();
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  })(),
+  
+  (async () => {
+    const tx = await handler.beginTransaction();
+    try {
+      await tx.table("users").insert({ name: "User2" });
+      await tx.commit();
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  })(),
+  
+  (async () => {
+    const tx = await handler.beginTransaction();
+    try {
+      await tx.table("users").insert({ name: "User3" });
+      await tx.commit();
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  })()
+]);
+```
+
+#### Best Practices
+
+1. **Always use connection pools in production** - Prevents connection exhaustion and enables concurrent transactions
+2. **Choose appropriate isolation level** - Balance between consistency and performance
+3. **Use try-catch-finally** - Ensure transactions are always committed or rolled back
+4. **Keep transactions short** - Avoid long-running operations inside transactions
+5. **Use row locking when needed** - `FOR UPDATE` prevents concurrent modifications
+6. **Handle errors properly** - Always rollback on errors to maintain data consistency
+
 ### Migration
 
 > [Migration examples](./examples/migration/).

package/bin/orm-mysql.js

@@ -9,7 +9,7 @@ const app = new App({
   name: 'MySQL ORM CLI',
   desc: 'migrate, model, seed, etc.',
   bin: 'orm-mysql',
-  version: '0.11.12',
+  version: '0.12.0',
   commands_dir: path.join(__dirname, '../commands'),
 });
 

package/docker-compose.yml

@@ -0,0 +1,18 @@
+version: '3'
+# Settings and configurations that are common for all containers
+services:
+  mysql:
+    image: 'mysql:8.0'
+    container_name: "orm-feature-tests-mysql"
+    command: mysqld --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
+    environment:
+      MYSQL_ROOT_PASSWORD: '3AQqZTfmww=Ftj'
+      MYSQL_DATABASE: 'feature_tests'
+    restart: 'always'
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-p3AQqZTfmww=Ftj"]
+      interval: 5s
+      timeout: 3s
+      retries: 10

package/examples/transaction_example.js

@@ -0,0 +1,228 @@
+/* eslint-disable no-console */
+'use strict';
+
+/**
+ * 事务使用示例
+ * 
+ * 这个示例展示了如何正确使用事务，避免连接阻塞问题
+ */
+
+const mysql = require('mysql2/promise');
+const { QueryHandler } = require('../src/operator');
+
+/**
+ * 示例 1: 使用连接池（推荐）
+ * 优点：自动从池中获取新连接，不会阻塞其他操作
+ */
+async function exampleWithPool() {
+  const pool = mysql.createPool({
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'test_db',
+    connectionLimit: 10
+  });
+
+  const queryHandler = new QueryHandler(pool);
+
+  try {
+    // 方式 1: 使用 QueryHandler.beginTransaction()（推荐）
+    // 这会自动从连接池获取一个新连接用于事务
+    const transaction = await queryHandler.beginTransaction({ level: 'RC' });
+    
+    try {
+      // 执行事务操作
+      await transaction.table('users').insert({ name: 'John', age: 30 });
+      await transaction.table('orders').insert({ user_id: 1, total: 100 });
+      
+      // 提交事务（会自动释放连接回池）
+      await transaction.commit();
+      console.log('Transaction committed successfully');
+    } catch (err) {
+      // 回滚事务（会自动释放连接回池）
+      await transaction.rollback();
+      console.error('Transaction rolled back:', err.message);
+      throw err;
+    }
+
+    // 同时，其他操作不会被阻塞
+    const users = await queryHandler.table('users').select();
+    console.log('Users:', users);
+
+  } finally {
+    await pool.end();
+  }
+}
+
+/**
+ * 示例 2: 使用单一连接（不推荐用于生产环境）
+ * 注意：事务执行期间会阻塞该连接的其他操作
+ */
+async function exampleWithSingleConnection() {
+  const connection = await mysql.createConnection({
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'test_db'
+  });
+
+  const queryHandler = new QueryHandler(connection);
+
+  try {
+    // 使用单一连接创建事务
+    const transaction = await queryHandler.beginTransaction({ level: 'RR' });
+    
+    try {
+      await transaction.table('users').insert({ name: 'Jane', age: 25 });
+      await transaction.commit();
+      console.log('Transaction committed');
+    } catch (err) {
+      await transaction.rollback();
+      console.error('Transaction rolled back:', err);
+      throw err;
+    }
+
+  } finally {
+    await connection.end();
+  }
+}
+
+/**
+ * 示例 3: 直接使用 TransactionHandler
+ * 适用于需要更多控制的场景
+ */
+async function exampleWithTransactionHandler() {
+  const { TransactionHandler } = require('../src/transaction');
+  
+  const connection = await mysql.createConnection({
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'test_db'
+  });
+
+  const transaction = new TransactionHandler(connection, { level: 'SERIALIZABLE' });
+  
+  try {
+    await transaction.begin();
+    
+    // 执行多个操作
+    await transaction.table('users').insert({ name: 'Bob', age: 35 });
+    await transaction.table('user_profiles').insert({ user_id: 1, bio: 'Developer' });
+    
+    // 使用锁
+    const lockedRows = await transaction.table('products')
+      .where('id', [1, 2, 3], 'IN')
+      .append('FOR UPDATE')
+      .select();
+    
+    console.log('Locked rows:', lockedRows);
+    
+    await transaction.commit();
+    console.log('Transaction completed');
+  } catch (err) {
+    await transaction.rollback();
+    console.error('Error:', err);
+    throw err;
+  } finally {
+    await connection.end();
+  }
+}
+
+/**
+ * 示例 4: 并发事务（使用连接池）
+ * 展示多个事务可以同时执行而不相互阻塞
+ */
+async function exampleConcurrentTransactions() {
+  const pool = mysql.createPool({
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'test_db',
+    connectionLimit: 10
+  });
+
+  const queryHandler = new QueryHandler(pool);
+
+  try {
+    // 并发执行多个事务
+    const results = await Promise.all([
+      // 事务 1
+      (async () => {
+        const tx = await queryHandler.beginTransaction();
+        try {
+          await tx.table('users').insert({ name: 'User1', age: 20 });
+          await tx.commit();
+          return 'Transaction 1 completed';
+        } catch (err) {
+          await tx.rollback();
+          throw err;
+        }
+      })(),
+      
+      // 事务 2
+      (async () => {
+        const tx = await queryHandler.beginTransaction();
+        try {
+          await tx.table('users').insert({ name: 'User2', age: 21 });
+          await tx.commit();
+          return 'Transaction 2 completed';
+        } catch (err) {
+          await tx.rollback();
+          throw err;
+        }
+      })(),
+      
+      // 事务 3
+      (async () => {
+        const tx = await queryHandler.beginTransaction();
+        try {
+          await tx.table('users').insert({ name: 'User3', age: 22 });
+          await tx.commit();
+          return 'Transaction 3 completed';
+        } catch (err) {
+          await tx.rollback();
+          throw err;
+        }
+      })()
+    ]);
+
+    console.log('All transactions completed:', results);
+  } finally {
+    await pool.end();
+  }
+}
+
+/**
+ * 最佳实践总结：
+ * 
+ * 1. 生产环境推荐使用连接池（Pool）
+ * 2. 使用 QueryHandler.beginTransaction() 自动管理连接
+ * 3. 始终在 try-catch-finally 中使用事务
+ * 4. 确保调用 commit() 或 rollback()
+ * 5. 连接池会自动释放连接，无需手动管理
+ * 6. 避免在事务中执行长时间运行的操作
+ * 7. 根据需要选择合适的隔离级别：
+ *    - 'RU' / 'READ UNCOMMITTED': 最低隔离级别，性能最好，可能读到脏数据
+ *    - 'RC' / 'READ COMMITTED': 避免脏读
+ *    - 'RR' / 'REPEATABLE READ': MySQL 默认级别，避免不可重复读
+ *    - 'S' / 'SERIALIZABLE': 最高隔离级别，完全串行化，性能最差
+ */
+
+// 运行示例（取消注释以运行）
+// exampleWithPool().catch(console.error);
+// exampleWithSingleConnection().catch(console.error);
+// exampleWithTransactionHandler().catch(console.error);
+// exampleConcurrentTransactions().catch(console.error);
+
+module.exports = {
+  exampleWithPool,
+  exampleWithSingleConnection,
+  exampleWithTransactionHandler,
+  exampleConcurrentTransactions
+};
+

package/index.d.ts

@@ -412,6 +412,32 @@ export declare class QueryHandler {
    * @param attrs 
    */
   getTableFields<T extends Object>(database: string, table: string, ...attrs: TableInfoColumn[]): Promise<T>;
+
+  /**
+   * Begin a transaction and return a TransactionHandler instance
+   * 
+   * Note: If using a Pool, this will automatically get a new connection from the pool
+   * to avoid blocking other operations. The connection will be released back to pool
+   * after commit/rollback.
+   * 
+   * @param options - Transaction options
+   * @param options.level - Transaction isolation level
+   * @param options.useNewConnection - Force create new connection from pool (default: true for Pool, false for Connection)
+   */
+  beginTransaction(options?: {
+    level?: TransactionLevel;
+    useNewConnection?: boolean;
+  }): Promise<TransactionHandler>;
+
+  /**
+   * Commit current connection transaction (if using promise connection directly)
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback current connection transaction (if using promise connection directly)
+   */
+  rollback(): Promise<void>;
 }
 
 export declare class TransactionOperator extends QueryOperator {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiosleo/orm-mysql",
-  "version": "0.11.12",
+  "version": "0.12.0",
   "description": "MySQL ORM tool",
   "keywords": [
     "mysql",
@@ -18,6 +18,9 @@
     "test": "mocha --reporter spec --timeout 3000 tests/*.tests.js",
     "test-cov": "nyc -r=lcov -r=html -r=text -r=json mocha -t 10000 -R spec tests/*.tests.js",
     "test-one": "mocha --reporter spec --timeout 3000 ",
+    "feature-test": "node tests/transaction.ft.js",
+    "setup-feature-db": "node tests/setup-feature-db.js",
+    "feature-test:local": "docker compose up -d && sleep 10 && npm run setup-feature-db && npm run feature-test && docker compose down",
     "ci": "npm run lint && npm run test-cov",
     "clear": "rm -rf ./nyc_output ./coverage && rm -rf ./node_modules && npm cache clean --force"
   },

package/src/operator.js

@@ -259,6 +259,121 @@ class QueryHandler {
       values: [database, table]
     });
   }
+
+  /**
+   * Begin a transaction and return a TransactionHandler instance
+   * 
+   * Note: If using a Pool, this will automatically get a new connection from the pool
+   * to avoid blocking other operations. The connection will be released back to pool
+   * after commit/rollback.
+   * 
+   * @param {object} options - Transaction options
+   * @param {string} options.level - Transaction isolation level (RU, RC, RR, S or full name)
+   * @param {boolean} options.useNewConnection - Force create new connection from pool (default: true for Pool, false for Connection)
+   * @returns {Promise<import('./transaction').TransactionHandler>}
+   */
+  async beginTransaction(options = {}) {
+    const { TransactionHandler } = require('./transaction');
+    const transactionOptions = {
+      ...this.options,
+      level: options.level || 'SERIALIZABLE'
+    };
+
+    let conn = this.conn;
+    let isPoolConnection = false;
+
+    // Check if this.conn is a Pool
+    if (this.conn && typeof this.conn.getConnection === 'function') {
+      // This is a Pool, get a new connection from pool for transaction
+      const useNewConnection = options.useNewConnection !== false; // default true for pool
+      if (useNewConnection) {
+        // Detect pool type by checking constructor name or promise() method
+        // Callback pool (mysql2): has promise() method, constructor name is "Pool"
+        // Promise pool (mysql2/promise): no promise() method, constructor name is "PromisePool"
+        const isCallbackPool = typeof this.conn.promise === 'function';
+
+        if (isCallbackPool) {
+          // Callback-based pool (mysql2) - need to wrap getConnection in Promise
+          conn = await new Promise((resolve, reject) => {
+            this.conn.getConnection((err, connection) => {
+              if (err) {
+                reject(err);
+              } else {
+                resolve(connection);
+              }
+            });
+          });
+          // Convert callback connection to promise-based
+          if (conn && typeof conn.promise === 'function') {
+            conn = conn.promise();
+          }
+        } else {
+          // Promise-based pool (mysql2/promise) - getConnection() already returns a Promise
+          conn = await this.conn.getConnection();
+        }
+        isPoolConnection = true;
+      }
+    } else if (this.conn && typeof this.conn.promise === 'function') {
+      // This is a mysql2 Connection, convert to promise-based
+      conn = this.conn.promise();
+    }
+
+    const transaction = new TransactionHandler(conn, transactionOptions);
+
+    // Store pool connection flag for cleanup
+    if (isPoolConnection) {
+      transaction._poolConnection = conn;
+      transaction._originalCommit = transaction.commit.bind(transaction);
+      transaction._originalRollback = transaction.rollback.bind(transaction);
+
+      // Override commit to release connection back to pool
+      transaction.commit = async function () {
+        try {
+          await this._originalCommit();
+        } finally {
+          if (this._poolConnection && typeof this._poolConnection.release === 'function') {
+            this._poolConnection.release();
+          }
+        }
+      };
+
+      // Override rollback to release connection back to pool
+      transaction.rollback = async function () {
+        try {
+          await this._originalRollback();
+        } finally {
+          if (this._poolConnection && typeof this._poolConnection.release === 'function') {
+            this._poolConnection.release();
+          }
+        }
+      };
+    }
+
+    await transaction.begin();
+    return transaction;
+  }
+
+  /**
+   * Commit current connection transaction (if using promise connection directly)
+   */
+  async commit() {
+    if (this.conn && typeof this.conn.commit === 'function') {
+      await this.conn.commit();
+    } else {
+      throw new Error('Connection does not support commit operation');
+    }
+  }
+
+  /**
+   * Rollback current connection transaction (if using promise connection directly)
+   */
+  async rollback() {
+    if (this.conn && typeof this.conn.rollback === 'function') {
+      await this.conn.rollback();
+    } else {
+      throw new Error('Connection does not support rollback operation');
+    }
+  }
 }
 
 module.exports = {