dynalitics-mysql 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynalitics contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# dynalitics-mysql
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **MySQL adapter** for [dynalitics](https://www.npmjs.com/package/dynalitics). `dynalitics` itself never loads a database driver; this package is the piece that connects it to MySQL through [`mysql2`](https://sidorares.github.io/node-mysql2/docs). It depends on `mysql2` (pinned to `3.24.6`) and nothing else, so installing it brings in exactly one driver.
+
+```sh
+npm install dynalitics dynalitics-mysql     # Node 22+, ESM only
+```
+
+## Usage
+
+Pass the exported `mysql` adapter as `adapter` when you create an instance. Everything else (table, consent, IP mode, the read API) is configured on `dynalitics`; see its README.
+
+```ts
+import { createDynalitics } from 'dynalitics';
+import { mysql } from 'dynalitics-mysql';
+
+const dyn = await createDynalitics({
+  adapter: mysql,
+  connection: {
+    writer: { connectionString: process.env.ANALYTICS_WRITER_URL! }, // mysql://user:pass@host/db, INSERT only
+    reader: { connectionString: process.env.ANALYTICS_READER_URL! }, // SELECT only
+  },
+  table: 'analytics.dynalitics_events', // on MySQL the "schema" part is the database
+});
+```
+
+Create the table first with `npx dynalitics sql --dialect mysql --table analytics.dynalitics_events --grants` (prints SQL, never connects).
+
+## What the adapter does
+
+**Connection strings.** For each credential it creates a `mysql2/promise` pool with:
+
+| Setting                 | Value                                      | Why                                                                     |
+| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
+| `connectionLimit`       | `poolSize` (writer 4, reader 2 by default) |                                                                         |
+| `connectTimeout`        | `connectTimeoutMs` (10 s by default)       |                                                                         |
+| `timezone`              | `'Z'`                                      | timestamps are written and read as UTC                                  |
+| `dateStrings`           | `true`                                     | no time-zone conversion on the way back                                 |
+| `multipleStatements`    | `false`                                    | one statement per call, always                                          |
+| `maxPreparedStatements` | 64                                         | prepared statements are counted server-wide (`max_prepared_stmt_count`) |
+
+Every statement that carries values runs as a real prepared statement (`execute`), so values are bound by the server; only the parameterless `SHOW` statements of the startup check use a plain query. Booleans are sent as `1`/`0`. Use the `ssl` options of your connection string for anything that is not on localhost.
+
+**Your own pool.** Pass `{ pool: yourPool }` instead of a connection string. It must be a **promise** pool (`mysql2/promise`). dynalitics never closes it on `close()`.
+
+**Deadlines.** Each `SELECT` carries a `MAX_EXECUTION_TIME` hint, so MySQL stops a slow read by itself when the read handler's deadline passes (`limits.timeoutMs`, 10 s by default). As a backstop, the adapter destroys the connection 500 ms later if the server has not answered. A pool without `getConnection()` only gets a client-side timeout; in that case set `max_execution_time` on the reader account yourself.
+
+**Errors.** The adapter never passes a raw `mysql2` error on. Data and constraint errors (duplicate key, truncation, bad value, NULL in a NOT NULL column and similar) forward no message text at all, because MySQL prints the offending value. Table and column permission errors become a fixed sentence. Connection, authentication and timeout errors keep their message, redacted and with quoted values removed. Lost connections, deadlocks, lock wait timeouts and "too many connections" are marked transient, so the writer retries them.
+
+## Versions
+
+`dynalitics-mysql` and `dynalitics` are released together with the same version number, and the adapter declares `dynalitics` as a peer dependency at exactly that version. If the two ever disagree on the adapter contract, `createDynalitics` refuses to start and names both versions.
+
+Tested against MySQL 8.4 (integration tests, local Docker). The explorer's number filters use `CAST(... AS DOUBLE)`, which needs MySQL 8.0.17 or newer (untested on older versions). MariaDB is not supported.
+
+MIT licensed.

package/dist/driver.d.ts

@@ -0,0 +1,6 @@
+import { type Classification, type Driver, type DriverOptions } from 'dynalitics/adapter';
+export declare function classifyMysql(err: unknown): Classification;
+/** MySQL kills a SELECT on its own once it exceeds the hint, so a stuck query cannot outlive the deadline. */
+export declare function withExecutionHint(sql: string, timeoutMs: number): string;
+export declare function createMysqlDriver(o: DriverOptions): Promise<Driver>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.js

@@ -0,0 +1,142 @@
+import mysqlModule from 'mysql2/promise';
+import { errCode, isTransientError, toDriverError, } from 'dynalitics/adapter';
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    'PROTOCOL_CONNECTION_LOST',
+    'ER_LOCK_DEADLOCK',
+    'ER_LOCK_WAIT_TIMEOUT',
+    'ER_CON_COUNT_ERROR',
+    'PROTOCOL_SEQUENCE_TIMEOUT',
+    'ER_QUERY_TIMEOUT',
+]);
+const TIMEOUT_CODES = new Set([
+    'PROTOCOL_SEQUENCE_TIMEOUT',
+    'ER_QUERY_TIMEOUT',
+    'ETIMEDOUT',
+]);
+const DATA_CODES = new Set([
+    'ER_DUP_ENTRY',
+    'ER_TRUNCATED_WRONG_VALUE',
+    'ER_TRUNCATED_WRONG_VALUE_FOR_FIELD',
+    'ER_DATA_TOO_LONG',
+    'ER_BAD_NULL_ERROR',
+    'ER_WARN_DATA_OUT_OF_RANGE',
+    'ER_NO_REFERENCED_ROW_2',
+    'ER_ROW_IS_REFERENCED_2',
+    'ER_CHECK_CONSTRAINT_VIOLATED',
+    'ER_INVALID_CHARACTER_STRING',
+    'ER_WRONG_VALUE_COUNT_ON_ROW',
+]);
+const DATA_ERRNOS = new Set([
+    1048, 1062, 1264, 1292, 1300, 1366, 1406, 1451, 1452, 3819,
+]);
+const PERMISSION_CODES = new Set([
+    'ER_TABLEACCESS_DENIED_ERROR',
+    'ER_COLUMNACCESS_DENIED_ERROR',
+]);
+const AUTH_CODES = new Set([
+    'ER_ACCESS_DENIED_ERROR',
+    'ER_DBACCESS_DENIED_ERROR',
+    'ENOTFOUND',
+]);
+/** The server stops a SELECT at the hint's deadline; the client destroys the connection this long afterwards. */
+const BACKSTOP_MS = 500;
+const MAX_PREPARED_STATEMENTS = 64;
+export function classifyMysql(err) {
+    const code = errCode(err);
+    const errno = err?.errno;
+    const transient = TRANSIENT_CODES.has(code);
+    return {
+        transient,
+        timeout: TIMEOUT_CODES.has(code),
+        data: DATA_CODES.has(code) || (typeof errno === 'number' && DATA_ERRNOS.has(errno)),
+        permission: PERMISSION_CODES.has(code),
+        forward: transient || AUTH_CODES.has(code),
+    };
+}
+// mysql2 prepared statements want 1/0 for booleans.
+const toParam = (v) => (typeof v === 'boolean' ? (v ? 1 : 0) : v);
+/** MySQL kills a SELECT on its own once it exceeds the hint, so a stuck query cannot outlive the deadline. */
+export function withExecutionHint(sql, timeoutMs) {
+    return /^\s*SELECT\b/i.test(sql)
+        ? sql.replace(/^\s*SELECT\b/i, (m) => `${m} /*+ MAX_EXECUTION_TIME(${Math.max(1, Math.trunc(timeoutMs))}) */`)
+        : sql;
+}
+// async on purpose: a throwing pool constructor must become a rejection, not a synchronous throw.
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function createMysqlDriver(o) {
+    let pool;
+    let owned = false;
+    if ('pool' in o.credential) {
+        pool = o.credential.pool;
+    }
+    else {
+        const mysql = mysqlModule;
+        pool = mysql.createPool({
+            uri: o.credential.connectionString,
+            connectionLimit: o.max,
+            connectTimeout: o.connectTimeoutMs,
+            timezone: 'Z',
+            dateStrings: true,
+            multipleStatements: false,
+            // Prepared statements are cached per connection and counted globally by the server (max_prepared_stmt_count).
+            maxPreparedStatements: MAX_PREPARED_STATEMENTS,
+        });
+        owned = true;
+    }
+    async function viaConnection(conn, sql, params, timeoutMs) {
+        let destroyed = false;
+        try {
+            // SHOW statements cannot be prepared; they take no parameters, so plain query() is safe.
+            const running = sql.startsWith('SHOW ')
+                ? conn.query(sql)
+                : conn.execute({ sql: withExecutionHint(sql, timeoutMs) }, params.map(toParam));
+            running.catch(() => undefined);
+            const [rows] = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    destroyed = true;
+                    conn.destroy();
+                    reject(Object.assign(new Error('Query execution was interrupted: deadline exceeded'), {
+                        code: 'ER_QUERY_TIMEOUT',
+                    }));
+                }, timeoutMs + BACKSTOP_MS);
+                running.then((r) => (clearTimeout(timer), resolve(r)), (e) => (clearTimeout(timer), reject(e)));
+            });
+            return rows;
+        }
+        finally {
+            if (!destroyed)
+                conn.release(); // never hand a destroyed connection back to the pool
+        }
+    }
+    return {
+        async query(q, { timeoutMs }) {
+            try {
+                let rows;
+                if (pool.getConnection === undefined) {
+                    // Host pools without getConnection(): client-side deadline only (the host must set max_execution_time).
+                    [rows] =
+                        q.sql.startsWith('SHOW ') && pool.query !== undefined
+                            ? await pool.query(q.sql)
+                            : await pool.execute({ sql: withExecutionHint(q.sql, timeoutMs), timeout: timeoutMs }, q.params.map(toParam));
+                }
+                else {
+                    rows = await viaConnection(await pool.getConnection(), q.sql, q.params, timeoutMs);
+                }
+                return Array.isArray(rows) ? rows : [];
+            }
+            catch (err) {
+                throw toDriverError(err, o.redact, classifyMysql);
+            }
+        },
+        isTransient: isTransientError,
+        async close() {
+            if (owned)
+                await pool.end?.();
+        },
+    };
+}
+//# sourceMappingURL=driver.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { DriverAdapter } from 'dynalitics/adapter';
+/**
+ * The MySQL adapter for dynalitics: `createDynalitics({ adapter: mysql, ... })`.
+ * apiVersion is a literal on purpose: it states the contract THIS package was built for (spec 5.2).
+ */
+export declare const mysql: DriverAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+import { createMysqlDriver } from './driver.js';
+/**
+ * The MySQL adapter for dynalitics: `createDynalitics({ adapter: mysql, ... })`.
+ * apiVersion is a literal on purpose: it states the contract THIS package was built for (spec 5.2).
+ */
+export const mysql = Object.freeze({
+    apiVersion: 1,
+    dialect: 'mysql',
+    packageName: 'dynalitics-mysql',
+    createDriver: createMysqlDriver,
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "dynalitics-mysql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MySQL adapter for dynalitics: brings in the mysql2 driver and nothing else.",
+  "keywords": [
+    "analytics",
+    "dynalitics",
+    "mysql",
+    "mysql2",
+    "adapter"
+  ],
+  "license": "MIT",
+  "author": "dynalitics contributors",
+  "homepage": "https://github.com/lucsoftsl/dynalitics/tree/main/packages/dynalitics-mysql#readme",
+  "bugs": {
+    "url": "https://github.com/lucsoftsl/dynalitics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucsoftsl/dynalitics.git",
+    "directory": "packages/dynalitics-mysql"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "mysql2": "3.24.6"
+  },
+  "peerDependencies": {
+    "dynalitics": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}