mysql-orm-lite 2.0.0 → 2.1.0

package/README.md

@@ -872,6 +872,400 @@ if (db.transactionManager.hasActiveTransaction()) {
 
 ---
 
+### Schema Introspection
+
+Query your database structure programmatically to inspect tables, columns, and indexes.
+
+#### `schema.tables(dbConfig?)`
+
+Get a list of all tables in the database.
+
+```javascript
+const tables = await db.schema.tables();
+console.log(tables); // ['users', 'orders', 'products', ...]
+```
+
+#### `schema.columns(tableName, dbConfig?)`
+
+Get detailed column information for a specific table.
+
+```javascript
+const columns = await db.schema.columns('users');
+console.log(columns);
+/*
+[
+  {
+    name: 'id',
+    type: 'int(11)',
+    nullable: false,
+    key: 'PRI',
+    default: null,
+    extra: 'auto_increment'
+  },
+  {
+    name: 'email',
+    type: 'varchar(255)',
+    nullable: false,
+    key: 'UNI',
+    default: null,
+    extra: ''
+  },
+  ...
+]
+*/
+```
+
+#### `schema.indexes(tableName, dbConfig?)`
+
+Get index information for a specific table.
+
+```javascript
+const indexes = await db.schema.indexes('users');
+console.log(indexes);
+/*
+[
+  {
+    name: 'PRIMARY',
+    column: 'id',
+    unique: true,
+    type: 'BTREE'
+  },
+  {
+    name: 'email_idx',
+    column: 'email',
+    unique: true,
+    type: 'BTREE'
+  },
+  ...
+]
+*/
+```
+
+#### Practical Use Cases
+
+**Dynamic Form Generation:**
+```javascript
+const columns = await db.schema.columns('products');
+const formFields = columns
+  .filter(col => !['id', 'created_at', 'updated_at'].includes(col.name))
+  .map(col => ({
+    name: col.name,
+    type: col.type.includes('int') ? 'number' : 'text',
+    required: !col.nullable
+  }));
+```
+
+**Schema Validation:**
+```javascript
+const tables = await db.schema.tables();
+const requiredTables = ['users', 'orders', 'products'];
+const missingTables = requiredTables.filter(t => !tables.includes(t));
+
+if (missingTables.length > 0) {
+  console.error('Missing tables:', missingTables);
+}
+```
+
+#### `schema.foreignKeys(tableName?, dbConfig?)`
+
+Get foreign key relationships for a specific table or all tables.
+
+```javascript
+// Get all foreign keys in the database
+const allForeignKeys = await db.schema.foreignKeys();
+console.log(allForeignKeys);
+/*
+[
+  {
+    childTable: 'orders',
+    parentTable: 'users',
+    constraintName: 'orders_ibfk_1',
+    columnName: 'user_id',
+    referencedColumnName: 'id'
+  },
+  {
+    childTable: 'order_items',
+    parentTable: 'orders',
+    constraintName: 'order_items_ibfk_1',
+    columnName: 'order_id',
+    referencedColumnName: 'id'
+  },
+  ...
+]
+*/
+
+// Get foreign keys for a specific table
+const orderForeignKeys = await db.schema.foreignKeys('orders');
+console.log(orderForeignKeys); // Shows both incoming and outgoing foreign keys
+```
+
+#### `schema.deleteOrder(dbConfig?)`
+
+Get the correct order to delete/truncate tables based on foreign key dependencies. Uses topological sort to ensure child tables are deleted before parent tables, preventing foreign key constraint violations.
+
+```javascript
+const deleteOrder = await db.schema.deleteOrder();
+console.log(deleteOrder);
+// ['order_items', 'orders', 'users', 'products', ...]
+// Child tables come first, so you can safely delete in this order
+
+// Practical use: Truncate all tables in the correct order
+for (const table of deleteOrder) {
+  await db.find(`TRUNCATE TABLE ${table}`);
+  console.log(`Truncated ${table}`);
+}
+```
+
+**Use Cases:**
+- **Database Cleanup**: Safely truncate all tables for testing without foreign key errors
+- **Data Migration**: Understand table dependencies before moving data
+- **Schema Visualization**: Generate dependency graphs for documentation```
+
+---
+
+```
+
+---
+
+### Bulk Operations
+
+Optimized methods for handling large datasets efficiently.
+
+#### `bulkInsert(table, records, options?)`
+
+Insert multiple records in a single query (batching handled automatically).
+
+```javascript
+const users = [
+  { name: 'User 1', email: 'user1@test.com' },
+  { name: 'User 2', email: 'user2@test.com' },
+  // ... 1000s of other users
+];
+
+// Automatically splits into batches (default 1000 per batch)
+const result = await db.bulkInsert('users', users);
+
+console.log(`Inserted ${result.totalInserted} users in ${result.batches} batches`);
+console.log(`First ID: ${result.firstInsertId}, Last ID: ${result.lastInsertId}`);
+
+// Custom batch size
+await db.bulkInsert('users', users, { batchSize: 500 });
+
+// Use INSERT IGNORE to skip duplicates
+await db.bulkInsert('users', users, { ignore: true });
+```
+
+#### `upsert(table, data, options)`
+
+Insert a record, or update specific fields if a duplicate key constraint occurs.
+
+```javascript
+// Updates 'stock' if product with id 101 already exists
+const result = await db.upsert('products', {
+  id: 101,
+  name: 'Laptop',
+  stock: 50
+}, {
+  conflictKey: 'id', // Column(s) that define uniqueness
+  updateFields: ['stock'] // Only update 'stock' on conflict, keep 'name' as is
+  // If updateFields is omitted, ALL fields except conflictKey are updated
+});
+
+if (result.action === 'inserted') {
+  console.log('New product created');
+} else {
+  console.log('Product stock updated');
+}
+```
+
+#### `bulkUpsert(table, records, options)`
+
+Perform upsert operations on a large array of records efficiently.
+
+```javascript
+const products = [
+  { id: 101, stock: 50 },
+  { id: 102, stock: 20 },
+  // ...
+];
+
+const result = await db.bulkUpsert('products', products, {
+  conflictKey: 'id',
+  updateFields: ['stock']
+});
+
+console.log(`Updated stock for ${result.totalAffected} products`);
+```
+
+---
+
+### Performance Monitoring
+
+
+Track query execution metrics, identify slow queries, and monitor database performance in real-time.
+
+#### Enable/Disable Monitoring
+
+```javascript
+// Enable performance monitoring
+db.performanceMonitor.enable();
+
+// Your database operations...
+await db.select({ table: 'users', where: { active: true } });
+
+// Disable monitoring
+db.performanceMonitor.disable();
+```
+
+> [!NOTE]
+> Performance monitoring is **disabled by default** to avoid overhead. Enable it only when needed.
+
+#### Get Performance Statistics
+
+```javascript
+db.performanceMonitor.enable();
+
+// Execute some queries...
+await db.select({ table: 'users' });
+await db.insert('logs', { message: 'test' });
+await db.updateWhere({ table: 'users', data: { status: 'active' }, where: { id: 1 } });
+
+// Get comprehensive stats
+const stats = db.performanceMonitor.getStats();
+console.log(stats);
+/*
+{
+  enabled: true,
+  totalQueries: 3,
+  averageQueryTime: 12.5,
+  slowestQueries: [
+    {
+      query: 'SELECT * FROM users',
+      duration: 25,
+      timestamp: 1234567890,
+      type: 'SELECT',
+      params: []
+    },
+    ...
+  ],
+  queryCountByType: {
+    SELECT: 1,
+    INSERT: 1,
+    UPDATE: 1,
+    DELETE: 0,
+    OTHER: 0
+  },
+  startTime: 1234567800,
+  uptime: 90000
+}
+*/
+```
+
+#### Get Slow Queries
+
+```javascript
+// Get top 10 slowest queries
+const slowQueries = db.performanceMonitor.getSlowQueries(10);
+console.log(slowQueries);
+
+// Each entry contains:
+// - query: SQL query string
+// - duration: Execution time in milliseconds
+// - timestamp: When the query was executed
+// - type: Query type (SELECT, INSERT, UPDATE, DELETE, OTHER)
+// - params: Query parameters (if any)
+```
+
+#### Get Recent Queries
+
+```javascript
+// Get queries from the last 60 seconds (default)
+const recentQueries = db.performanceMonitor.getRecentQueries();
+
+// Get queries from the last 5 minutes
+const last5Min = db.performanceMonitor.getRecentQueries(5 * 60 * 1000);
+```
+
+#### Get Queries Per Second
+
+```javascript
+const qps = db.performanceMonitor.getQueriesPerSecond();
+console.log(`Current QPS: ${qps.toFixed(2)}`);
+```
+
+#### Reset Metrics
+
+```javascript
+// Clear all collected metrics and restart the timer
+db.performanceMonitor.reset();
+```
+
+#### Connection Pool Statistics
+
+```javascript
+// Get current connection pool stats
+const poolStats = await db.connectionManager.getPoolStats();
+console.log(poolStats);
+/*
+{
+  activeConnections: 2,
+  idleConnections: 8,
+  totalConnections: 10,
+  waitingRequests: 0
+}
+*/
+```
+
+#### Practical Use Cases
+
+**1. Identify Performance Bottlenecks:**
+```javascript
+db.performanceMonitor.enable();
+
+// Run your application...
+await runApplicationLogic();
+
+// After some time, check stats
+const slowQueries = db.performanceMonitor.getSlowQueries(5);
+slowQueries.forEach(q => {
+  console.log(`Slow query (${q.duration}ms): ${q.query}`);
+});
+```
+
+**2. Monitor Production Performance:**
+```javascript
+// Enable in production with periodic reporting
+db.performanceMonitor.enable();
+
+setInterval(() => {
+  const stats = db.performanceMonitor.getStats();
+  console.log(`QPS: ${db.performanceMonitor.getQueriesPerSecond().toFixed(2)}`);
+  console.log(`Avg Query Time: ${stats.averageQueryTime}ms`);
+  
+  // Alert if queries are too slow
+  if (stats.averageQueryTime > 100) {
+    console.warn('ALERT: Average query time exceeds 100ms!');
+  }
+}, 60000); // Every minute
+```
+
+**3. Load Testing Analysis:**
+```javascript
+db.performanceMonitor.enable();
+db.performanceMonitor.reset();
+
+// Run load test...
+await runLoadTest();
+
+// Analyze results
+const stats = db.performanceMonitor.getStats();
+console.log(`Total Queries: ${stats.totalQueries}`);
+console.log(`Average Time: ${stats.averageQueryTime}ms`);
+console.log(`QPS: ${db.performanceMonitor.getQueriesPerSecond()}`);
+```
+
+---
+
 ## Advanced Usage
 
 ### Multiple Database Connections

package/dist/index.d.ts

@@ -1,13 +1,40 @@
 import connectionManager from './lib/connectionManager';
 import TransactionCRUD from './lib/TransactionCRUD';
 import transactionManager from './lib/transactionManager';
-export { connectionManager, transactionManager, TransactionCRUD };
+import schema from './lib/schema';
+import performanceMonitor from './lib/performanceMonitor';
+export { connectionManager, transactionManager, TransactionCRUD, schema, performanceMonitor };
 export declare const find: (query: string, params?: any[], dbConfig?: import("./types").DbConfig) => Promise<any[]>;
 export declare const findCount: (query: string, params?: any[], dbConfig?: import("./types").DbConfig) => Promise<number>;
 export declare const insert: (table: string, data: Record<string, any>, dbConfig?: import("./types").DbConfig, debug?: boolean, isIgnore?: boolean) => Promise<any>;
 export declare const update: (table: string, data: Record<string, any>, query: string, dbConfig?: import("./types").DbConfig, debug?: boolean) => Promise<number>;
 export declare const _delete: (query: string, table?: string, dbConfig?: import("./types").DbConfig) => Promise<number>;
 export { _delete as delete };
+export declare const bulkInsert: (table: string, records: Record<string, any>[], options?: {
+    batchSize?: number;
+    ignore?: boolean;
+}, dbConfig?: import("./types").DbConfig) => Promise<{
+    totalInserted: number;
+    batches: number;
+    firstInsertId?: number;
+    lastInsertId?: number;
+}>;
+export declare const upsert: (table: string, data: Record<string, any>, options: {
+    conflictKey: string | string[];
+    updateFields?: string[];
+}, dbConfig?: import("./types").DbConfig) => Promise<{
+    action: "inserted" | "updated";
+    affectedRows: number;
+    insertId?: number;
+}>;
+export declare const bulkUpsert: (table: string, records: Record<string, any>[], options: {
+    conflictKey: string | string[];
+    updateFields?: string[];
+    batchSize?: number;
+}, dbConfig?: import("./types").DbConfig) => Promise<{
+    totalAffected: number;
+    batches: number;
+}>;
 export declare const buildAndExecuteSelectQuery: (options: import("./types").SelectOptions, dbConfig?: import("./types").DbConfig) => Promise<any[]>;
 export declare const buildAndExecuteUpdateQuery: (options: import("./types").UpdateOptions, dbConfig?: import("./types").DbConfig) => Promise<number>;
 export declare const buildAndExecuteDeleteQuery: (options: import("./types").DeleteOptions, dbConfig?: import("./types").DbConfig) => Promise<number>;
@@ -58,6 +85,12 @@ declare const _default: {
         closePool: (config: import("./types").DbConfig) => Promise<void>;
         closeAllPools: () => Promise<void>;
         getLogger: () => import("./types").Logger;
+        getPoolStats: (dbConfig?: import("./types").DbConfig) => Promise<{
+            activeConnections: any;
+            idleConnections: any;
+            totalConnections: any;
+            waitingRequests: any;
+        }>;
     };
     transactionManager: {
         setInstance: (instance: TransactionCRUD) => void;
@@ -66,6 +99,14 @@ declare const _default: {
         hasActiveTransaction: () => boolean;
     };
     TransactionCRUD: typeof TransactionCRUD;
+    schema: {
+        tables(dbConfig?: import("./types").DbConfig): Promise<string[]>;
+        columns(tableName: string, dbConfig?: import("./types").DbConfig): Promise<import("./types").ColumnInfo[]>;
+        indexes(tableName: string, dbConfig?: import("./types").DbConfig): Promise<import("./types").IndexInfo[]>;
+        foreignKeys(tableName?: string, dbConfig?: import("./types").DbConfig): Promise<import("./types").ForeignKeyInfo[]>;
+        deleteOrder(dbConfig?: import("./types").DbConfig): Promise<string[]>;
+    };
+    performanceMonitor: import("./lib/performanceMonitor").PerformanceMonitor;
     find: (query: string, params?: any[], dbConfig?: import("./types").DbConfig) => Promise<any[]>;
     findCount: (query: string, params?: any[], dbConfig?: import("./types").DbConfig) => Promise<number>;
     insert: (table: string, data: Record<string, any>, dbConfig?: import("./types").DbConfig, debug?: boolean, isIgnore?: boolean) => Promise<any>;
@@ -113,5 +154,30 @@ declare const _default: {
         };
     };
     createTransaction: () => TransactionCRUD;
+    bulkInsert: (table: string, records: Record<string, any>[], options?: {
+        batchSize?: number;
+        ignore?: boolean;
+    }, dbConfig?: import("./types").DbConfig) => Promise<{
+        totalInserted: number;
+        batches: number;
+        firstInsertId?: number;
+        lastInsertId?: number;
+    }>;
+    upsert: (table: string, data: Record<string, any>, options: {
+        conflictKey: string | string[];
+        updateFields?: string[];
+    }, dbConfig?: import("./types").DbConfig) => Promise<{
+        action: "inserted" | "updated";
+        affectedRows: number;
+        insertId?: number;
+    }>;
+    bulkUpsert: (table: string, records: Record<string, any>[], options: {
+        conflictKey: string | string[];
+        updateFields?: string[];
+        batchSize?: number;
+    }, dbConfig?: import("./types").DbConfig) => Promise<{
+        totalAffected: number;
+        batches: number;
+    }>;
 };
 export default _default;

package/dist/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTransaction = exports.utils = exports.remove = exports.deleteWhere = exports.updateQuery = exports.updateWhere = exports.query = exports.findWhere = exports.select = exports.buildAndExecuteDeleteQuery = exports.buildAndExecuteUpdateQuery = exports.buildAndExecuteSelectQuery = exports.delete = exports._delete = exports.update = exports.insert = exports.findCount = exports.find = exports.TransactionCRUD = exports.transactionManager = exports.connectionManager = void 0;
+exports.createTransaction = exports.utils = exports.remove = exports.deleteWhere = exports.updateQuery = exports.updateWhere = exports.query = exports.findWhere = exports.select = exports.buildAndExecuteDeleteQuery = exports.buildAndExecuteUpdateQuery = exports.buildAndExecuteSelectQuery = exports.bulkUpsert = exports.upsert = exports.bulkInsert = exports.delete = exports._delete = exports.update = exports.insert = exports.findCount = exports.find = exports.performanceMonitor = exports.schema = exports.TransactionCRUD = exports.transactionManager = exports.connectionManager = void 0;
 const connectionManager_1 = __importDefault(require("./lib/connectionManager"));
 exports.connectionManager = connectionManager_1.default;
 const crud = __importStar(require("./lib/crud"));
@@ -44,6 +44,10 @@ const TransactionCRUD_1 = __importDefault(require("./lib/TransactionCRUD"));
 exports.TransactionCRUD = TransactionCRUD_1.default;
 const transactionManager_1 = __importDefault(require("./lib/transactionManager"));
 exports.transactionManager = transactionManager_1.default;
+const schema_1 = __importDefault(require("./lib/schema"));
+exports.schema = schema_1.default;
+const performanceMonitor_1 = __importDefault(require("./lib/performanceMonitor"));
+exports.performanceMonitor = performanceMonitor_1.default;
 // CRUD Operations (Non-transactional)
 exports.find = crud.find;
 exports.findCount = crud.findCount;
@@ -51,6 +55,10 @@ exports.insert = crud.insert;
 exports.update = crud.update;
 exports._delete = crud.delete;
 exports.delete = exports._delete;
+// Bulk Operations
+exports.bulkInsert = crud.bulkInsert;
+exports.upsert = crud.upsert;
+exports.bulkUpsert = crud.bulkUpsert;
 // Query Builder - Full names
 exports.buildAndExecuteSelectQuery = crud.buildAndExecuteSelectQuery;
 exports.buildAndExecuteUpdateQuery = crud.buildAndExecuteUpdateQuery;
@@ -73,6 +81,8 @@ exports.default = {
     connectionManager: connectionManager_1.default,
     transactionManager: transactionManager_1.default,
     TransactionCRUD: TransactionCRUD_1.default,
+    schema: schema_1.default,
+    performanceMonitor: performanceMonitor_1.default,
     find: exports.find,
     findCount: exports.findCount,
     insert: exports.insert,
@@ -89,5 +99,8 @@ exports.default = {
     deleteWhere: exports.deleteWhere,
     remove: exports.remove,
     utils: exports.utils,
-    createTransaction: exports.createTransaction
+    createTransaction: exports.createTransaction,
+    bulkInsert: exports.bulkInsert,
+    upsert: exports.upsert,
+    bulkUpsert: exports.bulkUpsert
 };

package/dist/lib/connectionManager.d.ts

@@ -31,6 +31,17 @@ declare const connectionManager: {
      * Get logger instance
      */
     getLogger: () => Logger;
+    /**
+     * Get connection pool statistics
+     * @param dbConfig - Optional database configuration
+     * @returns Connection pool stats
+     */
+    getPoolStats: (dbConfig?: DbConfig) => Promise<{
+        activeConnections: any;
+        idleConnections: any;
+        totalConnections: any;
+        waitingRequests: any;
+    }>;
 };
 export default connectionManager;
 export { connectionManager };

package/dist/lib/connectionManager.js

@@ -137,7 +137,36 @@ const connectionManager = {
     /**
      * Get logger instance
      */
-    getLogger: () => logger
+    getLogger: () => logger,
+    /**
+     * Get connection pool statistics
+     * @param dbConfig - Optional database configuration
+     * @returns Connection pool stats
+     */
+    getPoolStats: async (dbConfig) => {
+        const conf = dbConfig || defaultConfig;
+        if (!conf || !conf.database) {
+            throw new Error('Database configuration missing');
+        }
+        const key = getPoolKey(conf);
+        const pool = pools.get(key);
+        if (!pool) {
+            return {
+                activeConnections: 0,
+                idleConnections: 0,
+                totalConnections: 0,
+                waitingRequests: 0
+            };
+        }
+        // Access pool internals (mysql2 specific)
+        const poolInfo = pool.pool;
+        return {
+            activeConnections: poolInfo?._acquiringConnections?.length || 0,
+            idleConnections: poolInfo?._freeConnections?.length || 0,
+            totalConnections: poolInfo?._allConnections?.length || 0,
+            waitingRequests: poolInfo?._connectionQueue?.length || 0
+        };
+    }
 };
 exports.connectionManager = connectionManager;
 exports.default = connectionManager;

package/dist/lib/crud.d.ts

@@ -36,6 +36,31 @@ export declare const insert: (table: string, data: Record<string, any>, dbConfig
 export declare const update: (table: string, data: Record<string, any>, query: string, dbConfig?: DbConfig, debug?: boolean) => Promise<number>;
 export declare const _delete: (query: string, table?: string, dbConfig?: DbConfig) => Promise<number>;
 export { _delete as delete };
+export declare const bulkInsert: (table: string, records: Record<string, any>[], options?: {
+    batchSize?: number;
+    ignore?: boolean;
+}, dbConfig?: DbConfig) => Promise<{
+    totalInserted: number;
+    batches: number;
+    firstInsertId?: number;
+    lastInsertId?: number;
+}>;
+export declare const upsert: (table: string, data: Record<string, any>, options: {
+    conflictKey: string | string[];
+    updateFields?: string[];
+}, dbConfig?: DbConfig) => Promise<{
+    action: "inserted" | "updated";
+    affectedRows: number;
+    insertId?: number;
+}>;
+export declare const bulkUpsert: (table: string, records: Record<string, any>[], options: {
+    conflictKey: string | string[];
+    updateFields?: string[];
+    batchSize?: number;
+}, dbConfig?: DbConfig) => Promise<{
+    totalAffected: number;
+    batches: number;
+}>;
 export declare const buildAndExecuteSelectQuery: (options: SelectOptions, dbConfig?: DbConfig) => Promise<any[]>;
 export declare const buildAndExecuteUpdateQuery: (options: UpdateOptions, dbConfig?: DbConfig) => Promise<number>;
 export declare const buildAndExecuteDeleteQuery: (options: DeleteOptions, dbConfig?: DbConfig) => Promise<number>;