@benjosivo/mysql 1.0.3 → 1.2.2

package/README.md

@@ -4,46 +4,10 @@ Shared MySQL client (pooling, automatic retry on deadlock/lock-timeout, transact
 
 ## Install
 
-This package is published to **GitHub Packages**, not the public npm registry, so every machine needs a one-time setup before `npm install` will work — even though the repo and package are public. GitHub Packages never allows anonymous installs; a valid GitHub token is always required.
-
-### One-time setup (per machine)
-
-1. **Create a GitHub Personal Access Token.**
-   GitHub → click your avatar → **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)** → **Generate new token (classic)**.
-   Scope needed: **`read:packages`**. Copy the token — GitHub only shows it once.
-
-2. **Add two lines to your global npm config.**
-   Find the file path:
-   ```
-   npm config get globalconfig
-   ```
-   It's typically `C:\Users\<you>\AppData\Roaming\npm\etc\npmrc` on Windows. Open that file in a text editor and add:
-   ```
-   @benjosivo:registry=https://npm.pkg.github.com
-   //npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
-   ```
-   Editing the file directly is more reliable than `npm config set` — on some npm versions, `npm config set @benjosivo:registry=... --global` fails with a cryptic `` `` is not a valid npm option `` error. If you'd rather use the CLI, use the space-separated form instead of `=`:
-   ```
-   npm config set @benjosivo:registry https://npm.pkg.github.com --global
-   ```
-
-3. **Verify both lines took effect:**
-   ```
-   npm config list
-   ```
-   You should see both `@benjosivo:registry = "https://npm.pkg.github.com"` and `//npm.pkg.github.com/:_authToken = (protected)` in the output.
-
-### Install
-
 ```
 npm install @benjosivo/mysql
 ```
 
-### Troubleshooting
-
-- **`404 Not Found - GET https://registry.npmjs.org/@benjosivo%2fmysql`** — npm is checking the default npm registry instead of GitHub Packages. This means the `@benjosivo:registry` line from step 2 above isn't set (check with `npm config get @benjosivo:registry`). Add it and retry.
-- **401/403 or `ENEEDAUTH`** — the auth token is missing, expired, or lacks `read:packages` scope. Regenerate a token and re-add it.
-
 ## Usage
 
 ```ts
@@ -87,6 +51,34 @@ executeMySQLQuery(query, values?, returnFieldTypes?, connKey?)
 
 Returns the rows directly on success. On failure it returns `{ error, values, connKey }` instead of throwing (matches `mysql2`'s row-result shape so existing call sites don't need try/catch).
 
+### Statements prepared statements can't run
+
+`executeMySQLQuery` uses `execute()` (MySQL's prepared-statement protocol), and MySQL rejects a
+number of statements there with *"This command is not supported in the prepared statement protocol
+yet"* — `SET GLOBAL ...`, `USE ...`, `LOCK TABLES`, several `SHOW` variants, and so on. For those,
+use `runMySQLQuery`, which goes through `query()` (text protocol) instead:
+
+```ts
+import { runMySQLQuery } from '@benjosivo/mysql';
+
+await runMySQLQuery("SET GLOBAL general_log = 'OFF'");
+
+// placeholders still work — mysql2 escapes and interpolates them client-side
+await runMySQLQuery('SET GLOBAL general_log = ?', ['OFF']);
+
+// optionally run inside an existing transaction
+await runMySQLQuery('SELECT * FROM users WHERE id = ?', [userId], connKey);
+```
+
+```ts
+runMySQLQuery(query, values?, connKey?)
+```
+
+Same result shape as `executeMySQLQuery`: rows on success, `{ error, values, connKey }` on failure.
+It's deliberately simple — no deadlock/lock-timeout retry — so prefer `executeMySQLQuery` for
+regular application queries and keep this one for statements the prepared-statement protocol
+refuses.
+
 ### Transactions
 
 ```ts

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import mysql from 'mysql2/promise';
 export interface MySQLClientConfig {
     host: string;
     user: string;
@@ -24,6 +25,27 @@ export declare function executeMySQLQuery2(opt: {
     returnFieldTypes?: boolean;
     returnListTables?: boolean | string;
 }): Promise<any>;
+/**
+ * Runs a statement through mysql2's `query()` (text protocol) instead of `execute()`
+ * (prepared-statement protocol).
+ *
+ * MySQL refuses a number of statements in the prepared-statement protocol
+ * ("This command is not supported in the prepared statement protocol yet") —
+ * `SET GLOBAL ...`, `USE ...`, `LOCK TABLES`, several `SHOW` variants, etc.
+ * Use this for those; keep using `executeMySQLQuery` for everything else, since
+ * that one adds deadlock/lock-timeout retries and prepared statements.
+ *
+ * Values are escaped and interpolated client-side by mysql2 (`?` placeholders),
+ * so parameters are still safe to pass.
+ *
+ * Returns the rows on success, or `{ error, values, connKey }` on failure —
+ * same shape as `executeMySQLQuery`.
+ */
+export declare function runMySQLQuery(query: string, values?: any[], connKey?: string): Promise<mysql.RowDataPacket[][] | mysql.OkPacket[] | mysql.ResultSetHeader[] | mysql.RowDataPacket[] | mysql.OkPacket | mysql.ResultSetHeader | {
+    error: any;
+    values: any[];
+    connKey: string | null;
+} | [mysql.RowDataPacket[], mysql.ResultSetHeader]>;
 export declare function connectionCommit(keyConn: string): Promise<{
     error?: unknown;
 }>;

package/dist/index.js

@@ -42,6 +42,7 @@ exports.loopKillOpenTRX = loopKillOpenTRX;
 exports.stopLoopKillOpenTRX = stopLoopKillOpenTRX;
 exports.executeMySQLQuery = executeMySQLQuery;
 exports.executeMySQLQuery2 = executeMySQLQuery2;
+exports.runMySQLQuery = runMySQLQuery;
 exports.connectionCommit = connectionCommit;
 exports.connectionRollback = connectionRollback;
 const crypto_1 = require("crypto");
@@ -369,6 +370,49 @@ async function executeMySQLQuery2(opt) {
         return { error: error?.message ?? error, values, connKey: connKey ?? null };
     }
 }
+/**
+ * Runs a statement through mysql2's `query()` (text protocol) instead of `execute()`
+ * (prepared-statement protocol).
+ *
+ * MySQL refuses a number of statements in the prepared-statement protocol
+ * ("This command is not supported in the prepared statement protocol yet") —
+ * `SET GLOBAL ...`, `USE ...`, `LOCK TABLES`, several `SHOW` variants, etc.
+ * Use this for those; keep using `executeMySQLQuery` for everything else, since
+ * that one adds deadlock/lock-timeout retries and prepared statements.
+ *
+ * Values are escaped and interpolated client-side by mysql2 (`?` placeholders),
+ * so parameters are still safe to pass.
+ *
+ * Returns the rows on success, or `{ error, values, connKey }` on failure —
+ * same shape as `executeMySQLQuery`.
+ */
+async function runMySQLQuery(query, values = [], connKey) {
+    requireConfig();
+    let conn;
+    try {
+        if (connKey) {
+            const tr = listTransaction.get(connKey);
+            if (!tr) {
+                const msg = `Transaction key not found: ${connKey}`;
+                handleError(msg, 'MySQL: runMySQLQuery');
+                return { error: msg, values, connKey };
+            }
+            tr.lastUpdate = Date.now();
+            conn = tr.conn;
+        }
+        else if (lastConnectionCheck + 5 * 60000 <= Date.now()) {
+            await ensurePool();
+        }
+        const [rows] = await (conn ?? requirePool()).query(query, values);
+        return rows;
+    }
+    catch (error) {
+        const errorMsg = String(error?.message ?? error);
+        const queryStr = query.length > 200 ? `${query.substring(0, 200)}...` : query;
+        handleError(error, `MySQL${error?.code ? ` [${error.code}]` : ''}${connKey ? ' (using connection)' : ''}\n${errorMsg}\n\nparams: ${values}\n\nquery: ${queryStr}`);
+        return { error: error?.message ?? error, values, connKey: connKey ?? null };
+    }
+}
 async function createTransaction() {
     const keyConn = (0, crypto_1.randomUUID)();
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@benjosivo/mysql",
-    "version": "1.0.3",
+    "version": "1.2.2",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "files": [
@@ -18,5 +18,9 @@
         "@types/node": "^26.1.2",
         "typescript": "^7.0.2"
     },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/benjosivo/mysql.git"
+    },
     "license": "MIT"
 }