mysql2 3.19.1 → 3.19.2-canary.c06afc25

package/lib/base/connection.js

@@ -28,6 +28,15 @@ const Packets = require('../packets/index.js');
 const Commands = require('../commands/index.js');
 const ConnectionConfig = require('../connection_config.js');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
+const {
+  traceCallback,
+  tracePromise,
+  getServerContext,
+  shouldTrace,
+  queryChannel,
+  executeChannel,
+  connectChannel,
+} = require('../tracing.js');
 
 let _connectionId = 0;
 
@@ -141,6 +150,41 @@ class BaseConnection extends EventEmitter {
         this._notifyError(err);
       });
       this.addCommand(handshakeCommand);
+
+      // Trace the connection handshake
+      if (shouldTrace(connectChannel)) {
+        const config = this.config;
+        tracePromise(
+          connectChannel,
+          () =>
+            new Promise((resolve, reject) => {
+              /* eslint-disable prefer-const */
+              let onConnect, onError;
+              onConnect = (param) => {
+                this.removeListener('error', onError);
+                resolve(param);
+              };
+              onError = (err) => {
+                this.removeListener('connect', onConnect);
+                reject(err);
+              };
+              /* eslint-enable prefer-const */
+              this.once('connect', onConnect);
+              this.once('error', onError);
+            }),
+          () => {
+            const server = getServerContext(config);
+            return {
+              database: config.database || '',
+              serverAddress: server.serverAddress,
+              serverPort: server.serverPort,
+              user: config.user || '',
+            };
+          }
+        ).catch(() => {
+          // errors are already handled by the handshake error listener
+        });
+      }
     }
     // in case there was no initial handshake but we need to read sting, assume it utf-8
     // most common example: "Too many connections" error ( packet is sent immediately on connection attempt, we don't know server encoding yet)
@@ -601,7 +645,62 @@ class BaseConnection extends EventEmitter {
       cmdQuery.values !== undefined ? cmdQuery.values : []
     );
     cmdQuery.sql = rawSql;
-    return this.addCommand(cmdQuery);
+
+    if (!shouldTrace(queryChannel)) {
+      return this.addCommand(cmdQuery);
+    }
+
+    const config = this.config;
+    const origCb = cmdQuery.onResult;
+
+    if (origCb) {
+      // Callback mode: use traceCallback for synchronous wrapping
+      traceCallback(
+        queryChannel,
+        (wrappedCb) => {
+          cmdQuery.onResult = wrappedCb;
+          this.addCommand(cmdQuery);
+        },
+        0,
+        () => {
+          const server = getServerContext(config);
+          return {
+            query: cmdQuery.sql,
+            values: cmdQuery.values,
+            database: config.database || '',
+            serverAddress: server.serverAddress,
+            serverPort: server.serverPort,
+          };
+        },
+        null,
+        origCb
+      );
+    } else {
+      // Event-emitter mode: use tracePromise since there is no callback
+      tracePromise(
+        queryChannel,
+        () =>
+          new Promise((resolve, reject) => {
+            cmdQuery.once('error', reject);
+            cmdQuery.once('end', () => resolve());
+            this.addCommand(cmdQuery);
+          }),
+        () => {
+          const server = getServerContext(config);
+          return {
+            query: cmdQuery.sql,
+            values: cmdQuery.values,
+            database: config.database || '',
+            serverAddress: server.serverAddress,
+            serverPort: server.serverPort,
+          };
+        }
+      ).catch(() => {
+        // errors are already emitted on the command
+      });
+    }
+
+    return cmdQuery;
   }
 
   pause() {
@@ -702,25 +801,108 @@ class BaseConnection extends EventEmitter {
       });
     }
     const executeCommand = new Commands.Execute(options, cb);
-    const prepareCommand = new Commands.Prepare(options, (err, stmt) => {
-      if (err) {
-        // skip execute command if prepare failed, we have main
-        // combined callback here
-        executeCommand.start = function () {
-          return null;
-        };
-        if (cb) {
-          cb(err);
-        } else {
-          executeCommand.emit('error', err);
+
+    if (!shouldTrace(executeChannel)) {
+      const prepareCommand = new Commands.Prepare(options, (err, stmt) => {
+        if (err) {
+          // skip execute command if prepare failed, we have main
+          // combined callback here
+          executeCommand.start = function () {
+            return null;
+          };
+          if (cb) {
+            cb(err);
+          } else {
+            executeCommand.emit('error', err);
+          }
+          executeCommand.emit('end');
+          return;
         }
-        executeCommand.emit('end');
-        return;
-      }
-      executeCommand.statement = stmt;
-    });
-    this.addCommand(prepareCommand);
-    this.addCommand(executeCommand);
+        executeCommand.statement = stmt;
+      });
+      this.addCommand(prepareCommand);
+      this.addCommand(executeCommand);
+      return executeCommand;
+    }
+
+    const config = this.config;
+    const origExecCb = executeCommand.onResult;
+
+    if (origExecCb) {
+      // Callback mode: use traceCallback for synchronous wrapping
+      traceCallback(
+        executeChannel,
+        (wrappedCb) => {
+          const prepareCommand = new Commands.Prepare(options, (err, stmt) => {
+            if (err) {
+              executeCommand.start = function () {
+                return null;
+              };
+              executeCommand.emit('end');
+              wrappedCb(err);
+              return;
+            }
+            executeCommand.statement = stmt;
+          });
+          executeCommand.onResult = wrappedCb;
+          this.addCommand(prepareCommand);
+          this.addCommand(executeCommand);
+        },
+        0,
+        () => {
+          const server = getServerContext(config);
+          return {
+            query: options.sql,
+            values: options.values,
+            database: config.database || '',
+            serverAddress: server.serverAddress,
+            serverPort: server.serverPort,
+          };
+        },
+        null,
+        origExecCb
+      );
+    } else {
+      // Event-emitter mode: use tracePromise since there is no callback
+      tracePromise(
+        executeChannel,
+        () =>
+          new Promise((resolve, reject) => {
+            const prepareCommand = new Commands.Prepare(
+              options,
+              (err, stmt) => {
+                if (err) {
+                  executeCommand.start = function () {
+                    return null;
+                  };
+                  executeCommand.emit('error', err);
+                  executeCommand.emit('end');
+                  reject(err);
+                  return;
+                }
+                executeCommand.statement = stmt;
+              }
+            );
+            executeCommand.once('error', reject);
+            executeCommand.once('end', () => resolve());
+            this.addCommand(prepareCommand);
+            this.addCommand(executeCommand);
+          }),
+        () => {
+          const server = getServerContext(config);
+          return {
+            query: options.sql,
+            values: options.values,
+            database: config.database || '',
+            serverAddress: server.serverAddress,
+            serverPort: server.serverPort,
+          };
+        }
+      ).catch(() => {
+        // errors are already emitted on the command
+      });
+    }
+
     return executeCommand;
   }
 

package/lib/base/pool.js

@@ -7,6 +7,12 @@ const PoolConnection = require('../pool_connection.js');
 const Queue = require('denque');
 const BaseConnection = require('./connection.js');
 const Errors = require('../constants/errors.js');
+const {
+  traceCallback,
+  getServerContext,
+  shouldTrace,
+  poolConnectChannel,
+} = require('../tracing.js');
 
 // Source: https://github.com/go-sql-driver/mysql/blob/76c00e35a8d48f8f70f0e7dffe584692bd3fa612/packets.go#L598-L613
 function isReadOnlyError(err) {
@@ -49,6 +55,28 @@ class BasePool extends EventEmitter {
   }
 
   getConnection(cb) {
+    if (!shouldTrace(poolConnectChannel)) {
+      return this._getConnection(cb);
+    }
+    const config = this.config.connectionConfig;
+    traceCallback(
+      poolConnectChannel,
+      this._getConnection.bind(this),
+      0,
+      () => {
+        const server = getServerContext(config);
+        return {
+          database: config.database || '',
+          serverAddress: server.serverAddress,
+          serverPort: server.serverPort,
+        };
+      },
+      null,
+      cb
+    );
+  }
+
+  _getConnection(cb) {
     if (this._closed) {
       return process.nextTick(() => cb(new Error('Pool is closed.')));
     }

package/lib/tracing.d.ts

@@ -0,0 +1,71 @@
+import type { TracingChannel } from 'node:diagnostics_channel';
+
+export interface QueryTraceContext {
+  query: string;
+  values: any;
+  database: string;
+  serverAddress: string;
+  serverPort: number | undefined;
+}
+
+export interface ExecuteTraceContext {
+  query: string;
+  values: any;
+  database: string;
+  serverAddress: string;
+  serverPort: number | undefined;
+}
+
+export interface ConnectTraceContext {
+  database: string;
+  serverAddress: string;
+  serverPort: number | undefined;
+  user: string;
+}
+
+export interface PoolConnectTraceContext {
+  database: string;
+  serverAddress: string;
+  serverPort: number | undefined;
+}
+
+export declare const dc: typeof import('node:diagnostics_channel') | undefined;
+export declare const hasTracingChannel: boolean;
+
+export declare function shouldTrace(
+  channel: TracingChannel<object> | undefined | null
+): boolean;
+
+export declare function traceCallback<T extends object>(
+  channel: TracingChannel<T> | undefined | null,
+  fn: (...args: any[]) => any,
+  position: number,
+  contextFactory: () => T,
+  thisArg: any,
+  ...args: any[]
+): any;
+
+export declare function tracePromise<T extends object, R>(
+  channel: TracingChannel<T> | undefined | null,
+  fn: () => Promise<R>,
+  contextFactory: () => T
+): Promise<R>;
+
+export declare const queryChannel:
+  | TracingChannel<QueryTraceContext>
+  | undefined;
+export declare const executeChannel:
+  | TracingChannel<ExecuteTraceContext>
+  | undefined;
+export declare const connectChannel:
+  | TracingChannel<ConnectTraceContext>
+  | undefined;
+export declare const poolConnectChannel:
+  | TracingChannel<PoolConnectTraceContext>
+  | undefined;
+
+export declare function getServerContext(config: {
+  socketPath?: string;
+  host?: string;
+  port?: number;
+}): { serverAddress: string; serverPort: number | undefined };

package/lib/tracing.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const process = require('process');
+
+// Safe load: use getBuiltinModule if available, fallback to require, catch if unavailable
+const dc = (() => {
+  try {
+    return 'getBuiltinModule' in process
+      ? process.getBuiltinModule('node:diagnostics_channel')
+      : require('node:diagnostics_channel');
+  } catch {
+    return undefined;
+  }
+})();
+
+const hasTracingChannel = typeof dc?.tracingChannel === 'function';
+
+const queryChannel = hasTracingChannel
+  ? dc.tracingChannel('mysql2:query')
+  : undefined;
+
+const executeChannel = hasTracingChannel
+  ? dc.tracingChannel('mysql2:execute')
+  : undefined;
+
+const connectChannel = hasTracingChannel
+  ? dc.tracingChannel('mysql2:connect')
+  : undefined;
+
+const poolConnectChannel = hasTracingChannel
+  ? dc.tracingChannel('mysql2:pool:connect')
+  : undefined;
+
+function getServerContext(config) {
+  if (config.socketPath) {
+    return { serverAddress: config.socketPath, serverPort: undefined };
+  }
+  return {
+    serverAddress: config.host || 'localhost',
+    serverPort: config.port || 3306,
+  };
+}
+
+// Node 20+: TracingChannel has an aggregated hasSubscribers getter.
+// Node 18.x: that getter is missing (undefined), fall back to start sub-channel.
+function shouldTrace(channel) {
+  if (channel === undefined || channel === null) {
+    return false;
+  }
+  return channel.hasSubscribers ?? channel.start?.hasSubscribers ?? false;
+}
+
+// Generic traceCallback wrapper — calls fn synchronously, wraps the callback
+// at args[position] to emit asyncStart/asyncEnd/error. No promises involved.
+function traceCallback(channel, fn, position, context, thisArg, ...args) {
+  if (shouldTrace(channel)) {
+    return channel.traceCallback(fn, position, context(), thisArg, ...args);
+  }
+  return fn.apply(thisArg, args);
+}
+
+// tracePromise for operations that are inherently async (connection handshake)
+function tracePromise(channel, fn, contextFactory) {
+  if (shouldTrace(channel)) {
+    return channel.tracePromise(fn, contextFactory());
+  }
+  return fn();
+}
+
+module.exports = {
+  dc,
+  hasTracingChannel,
+  shouldTrace,
+  queryChannel,
+  executeChannel,
+  connectChannel,
+  poolConnectChannel,
+  getServerContext,
+  traceCallback,
+  tracePromise,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mysql2",
-  "version": "3.19.1",
+  "version": "3.19.2-canary.c06afc25",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS",
   "main": "index.js",
   "typings": "typings/mysql/index",
@@ -8,15 +8,9 @@
   "scripts": {
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint . --fix && prettier --write .",
-    "test": "npm run test:parallel && npm run test:global",
-    "test:parallel": "poku -c=\"poku.config.mjs\" test",
-    "test:global": "cross-env SUITE=global poku -c=\"poku.config.mjs\" test/global",
-    "test:bun": "npm run test:bun:parallel && npm run test:bun:global",
-    "test:bun:parallel": "bun poku -c=\"poku.config.mjs\" test",
-    "test:bun:global": "cross-env SUITE=global bun poku -c=\"poku.config.mjs\" test/global",
-    "test:deno": "npm run test:deno:parallel && npm run test:deno:global",
-    "test:deno:parallel": "deno run --allow-read --allow-env --allow-run npm:poku -c=\"poku.config.mjs\" test",
-    "test:deno:global": "cross-env SUITE=global deno run --allow-read --allow-env --allow-run npm:poku -c=\"poku.config.mjs\" test/global",
+    "test": "poku",
+    "test:bun": "bun poku",
+    "test:deno": "deno run -A npm:poku",
     "test:docker:up": "docker compose -f test/docker-compose.yml up --abort-on-container-exit --remove-orphans",
     "test:docker:down": "docker compose -f test/docker-compose.yml down",
     "test:docker:node": "npm run test:docker:up -- node && npm run test:docker:down",
@@ -75,19 +69,19 @@
     "@eslint/js": "^9.39.2",
     "@eslint/markdown": "^7.5.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@pokujs/multi-suite": "^1.0.0",
     "@types/node": "^25.3.0",
     "@typescript-eslint/eslint-plugin": "^8.56.0",
     "@typescript-eslint/parser": "^8.56.0",
     "assert-diff": "^3.0.4",
     "benchmark": "^2.1.4",
     "c8": "^11.0.0",
-    "cross-env": "^10.1.0",
     "error-stack-parser": "^2.1.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-async-await": "^0.0.0",
     "eslint-plugin-prettier": "^5.5.5",
     "globals": "^17.3.0",
-    "poku": "^4.0.0",
+    "poku": "^4.1.0",
     "portfinder": "^1.0.38",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",

package/typings/mysql/index.d.ts

@@ -82,3 +82,10 @@ export interface ConnectionConfig extends ConnectionOptions {
 }
 
 export function createServer(handler: (conn: BaseConnection) => any): Server;
+
+export type {
+  QueryTraceContext,
+  ExecuteTraceContext,
+  ConnectTraceContext,
+  PoolConnectTraceContext,
+} from '../../lib/tracing.js';