feat(config): add returnFinalSqlQuery option

Author: naorpeled

README.md

@@ -39,6 +39,50 @@ exports.handler = async (event, context) => {
 }
 ```
 
+## Logging SQL Queries
+
+You can enable logging of the final SQL query (with all parameter values substituted) by setting the `returnFinalSqlQuery` option to `true`:
+
+```javascript
+// Require and initialize outside of your main handler
+const mysql = require('serverless-mysql')({
+  config: {
+    host     : process.env.ENDPOINT,
+    database : process.env.DATABASE,
+    user     : process.env.USERNAME,
+    password : process.env.PASSWORD
+  },
+  returnFinalSqlQuery: true // Enable SQL query logging
+})
+
+// Main handler function
+exports.handler = async (event, context) => {
+  // Run your query with parameters
+  const results = await mysql.query('SELECT * FROM users WHERE id = ?', [userId])
+  
+  // Access the SQL query with substituted values
+  console.log('Executed query:', results.sql)
+  
+  // Run clean up function
+  await mysql.end()
+
+  // Return the results
+  return results
+}
+```
+
+When `returnFinalSqlQuery` is enabled, the SQL query with substituted values is also attached to error objects when a query fails, making it easier to debug:
+
+```javascript
+try {
+  const results = await mysql.query('SELECT * FROM nonexistent_table')
+} catch (error) {
+  // The error object will have the SQL property
+  console.error('Failed query:', error.sql)
+  console.error('Error message:', error.message)
+}
+```
+
 ## Installation
 ```
 npm i serverless-mysql
@@ -169,6 +213,7 @@ Below is a table containing all of the possible configuration options for `serve
 | usedConnsFreq | `Integer` | The number of milliseconds to cache lookups of current connection usage. | `0` |
 | zombieMaxTimeout | `Integer` | The maximum number of seconds that a connection can stay idle before being recycled. | `900` |
 | zombieMinTimeout | `Integer` | The minimum number of *seconds* that a connection must be idle before the module will recycle it. | `3` |
+| returnFinalSqlQuery | `Boolean` | Flag indicating whether to attach the final SQL query (with substituted values) to the results. When enabled, the SQL query will be available as a non-enumerable `sql` property on array results or as a regular property on object results. | `false` |
 
 ### Connection Backoff
 If `manageConns` is not set to `false`, then this module will automatically kill idle connections or disconnect the current connection if the `connUtilization` limit is reached. Even with this aggressive strategy, it is possible that multiple functions will be competing for available connections. The `backoff` setting uses the strategy outlined [here](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) to use *Jitter* instead of *Exponential Backoff* when attempting connection retries.

docker-compose.yml

@@ -9,6 +9,7 @@ services:
       MYSQL_PASSWORD: testpassword
       # Allow connections from any host
       MYSQL_ROOT_HOST: "%"
+      TZ: UTC
     ports:
       - "3306:3306"
     command: >

index.d.ts

@@ -87,6 +87,11 @@ declare namespace serverlessMysql {
      * Integer  The minimum number of seconds that a connection must be idle before the module will recycle it.  3
      */
     zombieMinTimeout?: number;
+    /**
+     * Boolean  Flag indicating whether to attach the final SQL query with substituted values to the results. When enabled, the SQL query will be available as a non-enumerable `sql` property on array results or as a regular property on object results.
+     * This also attaches the SQL query to error objects when a query fails, making it easier to debug.  false
+     */
+    returnFinalSqlQuery?: boolean;
   };
 
   class Transaction {

index.js

@@ -36,7 +36,7 @@ module.exports = (params) => {
   // Init setting values
   let MYSQL, manageConns, cap, base, maxRetries, connUtilization, backoff,
     zombieMinTimeout, zombieMaxTimeout, maxConnsFreq, usedConnsFreq,
-    onConnect, onConnectError, onRetry, onClose, onError, onKill, onKillError, PromiseLibrary
+    onConnect, onConnectError, onRetry, onClose, onError, onKill, onKillError, PromiseLibrary, returnFinalSqlQuery
 
   /********************************************************************/
   /**  HELPER/CONVENIENCE FUNCTIONS                                  **/
@@ -219,7 +219,11 @@ module.exports = (params) => {
         // If no args are passed in a transaction, ignore query
         if (this && this.rollback && args.length === 0) { return resolve([]) }
 
-        client.query(...args, async (err, results) => {
+        const queryObj = client.query(...args, async (err, results) => {
+          if (returnFinalSqlQuery && queryObj.sql && err) {
+            err.sql = queryObj.sql
+          }
+
           if (err && err.code === 'PROTOCOL_SEQUENCE_TIMEOUT') {
             client.destroy() // destroy connection on timeout
             resetClient() // reset the client
@@ -239,6 +243,18 @@ module.exports = (params) => {
             }
             reject(err)
           }
+
+          if (returnFinalSqlQuery && queryObj.sql) {
+            if (Array.isArray(results)) {
+              Object.defineProperty(results, 'sql', {
+                enumerable: false,
+                value: queryObj.sql
+              })
+            } else if (results && typeof results === 'object') {
+              results.sql = queryObj.sql
+            }
+          }
+
           return resolve(results)
         })
       }
@@ -399,6 +415,7 @@ module.exports = (params) => {
   zombieMaxTimeout = Number.isInteger(cfg.zombieMaxTimeout) ? cfg.zombieMaxTimeout : 60 * 15 // default to 15 minutes
   maxConnsFreq = Number.isInteger(cfg.maxConnsFreq) ? cfg.maxConnsFreq : 15 * 1000 // default to 15 seconds
   usedConnsFreq = Number.isInteger(cfg.usedConnsFreq) ? cfg.usedConnsFreq : 0 // default to 0 ms
+  returnFinalSqlQuery = cfg.returnFinalSqlQuery === true // default to false
 
   // Event handlers
   onConnect = typeof cfg.onConnect === 'function' ? cfg.onConnect : () => { }

package.json

@@ -5,18 +5,18 @@
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
-    "test:unit": "mocha --check-leaks --recursive test/unit/*.spec.js",
-    "test:unit:debug": "NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/unit/*.spec.js",
-    "test:integration": "mocha --check-leaks --recursive test/integration/*.spec.js",
-    "test:integration:debug": "NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/integration/*.spec.js",
+    "test:unit": "TZ=UTC mocha --check-leaks --recursive test/unit/*.spec.js",
+    "test:unit:debug": "TZ=UTC NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/unit/*.spec.js",
+    "test:integration": "TZ=UTC mocha --check-leaks --recursive test/integration/*.spec.js",
+    "test:integration:debug": "TZ=UTC NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/integration/*.spec.js",
     "test:integration:docker": "./scripts/run-integration-tests.sh",
     "test:integration:docker:debug": "./scripts/run-integration-tests.sh debug",
     "test:docker": "./scripts/run-all-tests.sh",
     "test:docker:debug": "./scripts/run-all-tests.sh debug",
-    "test": "mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
-    "test:debug": "NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
-    "test-cov": "nyc --reporter=html mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
-    "test-cov:debug": "NODE_DEBUG=mysql,net,stream nyc --reporter=html mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
+    "test": "TZ=UTC mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
+    "test:debug": "TZ=UTC NODE_DEBUG=mysql,net,stream mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
+    "test-cov": "TZ=UTC nyc --reporter=html mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
+    "test-cov:debug": "TZ=UTC NODE_DEBUG=mysql,net,stream nyc --reporter=html mocha --check-leaks --recursive test/{unit,integration}/*.spec.js",
     "lint": "eslint .",
     "prepublishOnly": "npm run lint && npm run test:docker"
   },

scripts/run-integration-tests.sh

@@ -99,6 +99,7 @@ echo "Running integration tests..."
     fi
 
     # Add connection retry parameters to MySQL connection
+    TZ=UTC \
     MYSQL_HOST=127.0.0.1 \
     MYSQL_PORT=3306 \
     MYSQL_DATABASE=serverless_mysql_test \

test/integration/return-final-sql-query.spec.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const { expect } = require('chai');
+const {
+    createTestConnection,
+    setupTestTable,
+    cleanupTestTable,
+    closeConnection
+} = require('./helpers/setup');
+
+describe('Return Final SQL Query Integration Tests', function () {
+    this.timeout(15000);
+
+    let db, dbWithoutLogging;
+    const TEST_TABLE = 'final_sql_query_test_table';
+    const TABLE_SCHEMA = `
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    active BOOLEAN DEFAULT true,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+  `;
+
+    before(async function () {
+        try {
+            db = createTestConnection({ returnFinalSqlQuery: true });
+            dbWithoutLogging = createTestConnection({ returnFinalSqlQuery: false });
+            await setupTestTable(db, TEST_TABLE, TABLE_SCHEMA);
+        } catch (err) {
+            this.skip();
+        }
+    });
+
+    after(async function () {
+        try {
+            await cleanupTestTable(db, TEST_TABLE);
+
+            if (db) {
+                await db.end();
+                await closeConnection(db);
+            }
+            if (dbWithoutLogging) {
+                await dbWithoutLogging.end();
+                await closeConnection(dbWithoutLogging);
+            }
+        } catch (err) {
+        }
+    });
+
+    it('should include SQL with substituted parameters when returnFinalSqlQuery is enabled', async function () {
+        const insertResult = await db.query(
+            'INSERT INTO ?? (name, active) VALUES (?, ?)',
+            [TEST_TABLE, 'Test User', true]
+        );
+
+        expect(insertResult).to.have.property('sql');
+        const expectedInsertSql = `INSERT INTO \`${TEST_TABLE}\` (name, active) VALUES ('Test User', true)`;
+        expect(insertResult.sql).to.equal(expectedInsertSql);
+
+        const selectResult = await db.query(
+            'SELECT * FROM ?? WHERE name = ? AND active = ?',
+            [TEST_TABLE, 'Test User', true]
+        );
+
+        expect(selectResult).to.have.property('sql');
+        const expectedSelectSql = `SELECT * FROM \`${TEST_TABLE}\` WHERE name = 'Test User' AND active = true`;
+        expect(selectResult.sql).to.equal(expectedSelectSql);
+    });
+
+    it('should not include SQL when returnFinalSqlQuery is disabled', async function () {
+        const insertResult = await dbWithoutLogging.query(
+            'INSERT INTO ?? (name, active) VALUES (?, ?)',
+            [TEST_TABLE, 'No Log User', true]
+        );
+
+        expect(insertResult).to.not.have.property('sql');
+
+        const selectResult = await dbWithoutLogging.query(
+            'SELECT * FROM ?? WHERE name = ? AND active = ?',
+            [TEST_TABLE, 'No Log User', true]
+        );
+
+        expect(selectResult).to.not.have.property('sql');
+    });
+
+    it('should include SQL with complex parameter types correctly', async function () {
+        const testDate = new Date('2020-01-01T00:00:00Z');
+
+        const insertResult = await db.query(
+            'INSERT INTO ?? (name, active, created_at) VALUES (?, ?, ?)',
+            [TEST_TABLE, 'Date User', true, testDate]
+        );
+
+        expect(insertResult).to.have.property('sql');
+        const expectedInsertSql = `INSERT INTO \`${TEST_TABLE}\` (name, active, created_at) VALUES ('Date User', true, '2020-01-01 00:00:00.000')`;
+        expect(insertResult.sql).to.equal(expectedInsertSql);
+
+        const selectResult = await db.query(
+            'SELECT * FROM ?? WHERE name = ?',
+            [TEST_TABLE, 'Date User']
+        );
+
+        expect(selectResult).to.have.property('sql');
+        const expectedSelectSql = `SELECT * FROM \`${TEST_TABLE}\` WHERE name = 'Date User'`;
+        expect(selectResult.sql).to.equal(expectedSelectSql);
+    });
+
+    it('should include SQL with object parameters correctly', async function () {
+        const userData = {
+            name: 'Object User',
+            active: false
+        };
+
+        const insertResult = await db.query(
+            'INSERT INTO ?? SET ?',
+            [TEST_TABLE, userData]
+        );
+
+        expect(insertResult).to.have.property('sql');
+        const expectedInsertSql = `INSERT INTO \`${TEST_TABLE}\` SET \`name\` = 'Object User', \`active\` = false`;
+        expect(insertResult.sql).to.equal(expectedInsertSql);
+
+        const selectResult = await db.query(
+            'SELECT * FROM ?? WHERE name = ? AND active = ?',
+            [TEST_TABLE, 'Object User', false]
+        );
+
+        expect(selectResult).to.have.property('sql');
+        const expectedSelectSql = `SELECT * FROM \`${TEST_TABLE}\` WHERE name = 'Object User' AND active = false`;
+        expect(selectResult.sql).to.equal(expectedSelectSql);
+    });
+
+    it('should include SQL in error objects when a query fails', async function () {
+        try {
+            await db.query(
+                'SELECT * FROM ?? WHERE nonexistent_column = ?',
+                [TEST_TABLE, 'Test Value']
+            );
+
+            expect.fail('Query should have thrown an error');
+        } catch (error) {
+            expect(error).to.have.property('sql');
+            const expectedSql = `SELECT * FROM \`${TEST_TABLE}\` WHERE nonexistent_column = 'Test Value'`;
+            expect(error.sql).to.equal(expectedSql);
+            expect(error).to.have.property('code');
+            expect(error.code).to.match(/^ER_/);
+        }
+    });
+});