knex-transactional

Transaction Management with Node.js

Knex ORM with Transactional decorator

knex-transactional

A TypeScript decorator-based transaction management library for Knex.js that simplifies database transactions using the decorator pattern and AsyncLocalStorage.

Features

• 🎯 Simple decorator-based transaction management
• 🔄 Automatic transaction handling (commit/rollback)
• 🔒 Transaction isolation level support
• 🎭 Proxy-based query interception
• 📦 Zero external dependencies (except Knex.js)
• 💪 TypeScript support out of the box
• Support for readonly transactions (requires Knex.js >= 2.5.0)

Installation

npm install knex-transactional

Options

• isolationLevel: Transaction isolation level ('read uncommitted' | 'read committed' | 'repeatable read' | 'serializable')
• readOnly
• Other Knex.TransactionConfig options

Usage

const knex = require("knex")({
  client: "mysql",
  connection: {
    host: "127.0.0.1",
    port: 3306,
    user: "your_database_user",
    password: "your_database_password",
    database: "myapp_test",
  },
});

const db = initializeTransactions(knex);

export default db;

Performance Test Results

Test Environment

• Testing Tool: Artillery
• Load Configuration:
  • Warm-up: 10 requests per second for 5 seconds
  • Peak Load: 100 requests per second for 120 seconds

API Response Time Comparison

Decorator Approach (/decorator)

@Transactional()
async insertUserWithTransaction(userId: number) {
    const result = await db("user")
    .insert({
        userId
    })
    .returning("*");

    await db("user")
      .update({
        userId
      })
      .where("id", result[0].id);
}

Metric	Response Time (ms)
Minimum	2ms
Median	6ms
Mean	11.6ms
p90	18ms
p95	40.9ms
p99	98.5ms
Maximum	355ms

Manual Transaction Approach (/manual)

async insertUserManually(userId: number) {
    const trx = await db.transaction();
    try {
        const result = await trx("user")
            .insert({
                userId
            })
            .returning("*");

        await trx("user")
            .update({
                userId
            })
            .where("id", result[0].id);

        await trx.commit();
    } catch (error) {
        await trx.rollback();
        throw error;
    }
}

Metric	Response Time (ms)
Minimum	2ms
Median	7ms
Mean	11.8ms
p90	18ms
p95	40ms
p99	115.6ms
Maximum	356ms

Key Findings

1. General Performance: Both approaches show similar performance in normal conditions (p50-p90), with differences of less than 1ms.
2. High Load Stability: The decorator approach shows slightly better stability under high load (p95-p99).
3. Production Readiness: Both methods demonstrate stable performance suitable for production environments.

Test Statistics

• Total Requests: 12,050
• Success Rate: 100% (No Errors)
• Average RPS: 100
• Average Session Duration: 18.2ms

Note: p95 indicates the response time for the 95th percentile of requests, meaning 95% of requests were processed within this time.

Detailed Comparison

Metric	Decorator	Manual	Difference
Minimum	2ms	2ms	0ms
Median	6ms	7ms	-1ms
p90	18ms	18ms	0ms
p95	40.9ms	40ms	+0.9ms
p99	98.5ms	115.6ms	-17.1ms