Moduletrace/bun-mariadb
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add tests, schema sync safeguards, and query/handler improvements

Browse Source 
- Add bun test suite: SQL generator and value unit tests, plus MariaDB
  integration tests gated on BUN_MARIADB_TEST_DB
- schema: add --dry-run and require confirmation (or --yes) before
  dropping tables/columns; block unapproved destructive statements
- Always AND targetId with the query, regardless of searchOperator
- Initialize lazily on first call; init throws instead of exiting
- Generate IN (?, ?, ...) lists for IN / NOT IN
- Share value binding between insert and update (booleans, embeddings,
  function values, "" -> NULL for non-text columns)
- Keep Buffers and convert BigInt/Date without a JSON round-trip
- DbSQL: report success for empty SELECT results
- Run update() in a transaction with row locking
- Key the client cache on the full connection config
- Consolidate identifier quoting, drop dead code, merge column lookup
- Read CLI version from package.json, pin @types/bun, chmod CLI on compile
- Rebuild dist

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
tben
2026-10-14 02:27:59 +01:00
co-authored by Claude Opus 5.5
parent b81b09324a
commit ddf431e866
82 changed files with 2140 additions and 1403 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lib/db-handler.ts
+53 -27
View File
@@ -1,38 +1,78 @@
import grabMariaDBClient from "../functions/grab-mariadb-client";
import grabMariaDBClient, {
mariadbClientCacheKey,
} from "../functions/grab-mariadb-client";
import type {
BunMariaDBConfig,
DBInsertReturn,
DBResponseObject,
} from "../types";
/** Anything that can run a raw query: a client or a transaction handle */
export type DBQueryRunner = {
unsafe: (query: string, values?: any[]) => Promise<any>;
};
type Param = {
query: string;
values?: any[];
config?: BunMariaDBConfig;
/** Run on this client / transaction instead of the shared client */
client?: DBQueryRunner;
};
/**
* Resolve a shared MariaDB client. Prefer the global client so schema sync
* and CRUD do not open a new connection per query.
*/
function resolveClient(config?: BunMariaDBConfig): Bun.SQL | undefined {
const resolvedConfig = config || global.CONFIG;
export function resolveClient(config?: BunMariaDBConfig): Bun.SQL | undefined {
if (!config) {
return global.MARIADB_CLIENT;
}
// Same database as the global client → reuse it
// Same connection config as the global client → reuse it
if (
global.MARIADB_CLIENT &&
(!resolvedConfig?.db_name ||
!global.CONFIG?.db_name ||
resolvedConfig.db_name === global.CONFIG.db_name)
(!global.CONFIG ||
mariadbClientCacheKey(config) ===
mariadbClientCacheKey(global.CONFIG))
) {
return global.MARIADB_CLIENT;
}
if (resolvedConfig) {
return grabMariaDBClient({ config: resolvedConfig });
return grabMariaDBClient({ config });
}
/**
* Convert driver rows to plain objects.
* - BigInt -> number (or string when outside the safe integer range)
* - Date -> ISO string (matches the generated `string` typedefs)
* - Buffers / typed arrays (BLOB, VECTOR) are kept as-is
*/
function normalizeValue(value: unknown): unknown {
if (typeof value == "bigint") {
const num = Number(value);
return Number.isSafeInteger(num) ? num : value.toString();
}
return global.MARIADB_CLIENT;
if (value instanceof Date) {
return Number.isNaN(value.getTime()) ? null : value.toISOString();
}
return value;
}
function normalizeRows<T>(res: unknown): T[] | undefined {
if (!Array.isArray(res)) return undefined;
return res.map((row) => {
if (!row || typeof row != "object") return row;
const normalized: Record<string, unknown> = {};
for (const [key, value] of Object.entries(row)) {
normalized[key] = normalizeValue(value);
}
return normalized;
}) as T[];
}
/**
@@ -40,9 +80,9 @@ function resolveClient(config?: BunMariaDBConfig): Bun.SQL | undefined {
*/
export default async function dbHandler<
T extends { [k: string]: any } = { [k: string]: any },
>({ query, values, config }: Param): Promise<DBResponseObject<T>> {
>({ query, values, config, client }: Param): Promise<DBResponseObject<T>> {
try {
const CLIENT = resolveClient(config);
const CLIENT = client || resolveClient(config);
if (!CLIENT) {
throw new Error(`Couldn't grab MariaDB Client.`);
@@ -52,21 +92,7 @@ export default async function dbHandler<
const count = res.count;
const res_array = (() => {
try {
return JSON.parse(
JSON.stringify(res, (_key, value) =>
typeof value == "bigint"
? Number.isSafeInteger(Number(value))
? Number(value)
: value.toString()
: value,
),
) as T[];
} catch (error) {
return undefined;
}
})();
const res_array = normalizeRows<T>(res);
const last_insert_id = res_array?.[0] ? res_array[0]?.id : undefined;
const affected_rows = res_array?.[0] ? res_array.length : undefined;
src/lib/grab-duplicate-safe-insert-sql.ts
+1 -3
View File
@@ -4,9 +4,7 @@ type Params = {
data: any | any[];
};
function quoteIdentifier(identifier: string): string {
return `\`${identifier.replace(/`/g, "``")}\``;
}
import { quoteIdentifier } from "../utils/sql-identifier";
export default async function ({ sql: passedSql, table, data }: Params) {
const config = global.CONFIG;
src/lib/mariadb/db-delete.ts
+2 -14
View File
@@ -30,24 +30,12 @@ export default async function DbDelete<
let sqlObj: ReturnType<typeof sqlGenerator> | null = null;
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge<ServerQueryParam<any>, ServerQueryParam<any>>(
finalQuery,
{
query: {
id: {
value: Number(targetId),
},
},
},
);
}
const finalQuery = query || {};
sqlObj = sqlGenerator({
tableName: table,
genObject: finalQuery,
targetId,
});
const whereClause = sqlObj.where;
src/lib/mariadb/db-select.ts
+3 -15
View File
@@ -1,5 +1,4 @@
import dbHandler from "../db-handler";
import _ from "lodash";
import type {
BunMariaDBConfig,
DBResponseObject,
@@ -31,24 +30,12 @@ export default async function DbSelect<
let sqlObj: ReturnType<typeof sqlGenerator> | null = null;
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge<ServerQueryParam<any>, ServerQueryParam<any>>(
finalQuery,
{
query: {
id: {
value: Number(targetId),
},
},
},
);
}
const finalQuery = query || {};
sqlObj = sqlGenerator({
tableName: table,
genObject: finalQuery,
targetId,
});
const res = await dbHandler<Schema>({
@@ -85,6 +72,7 @@ export default async function DbSelect<
const countSqlObject = sqlGenerator({
tableName: table,
genObject: finalQuery,
targetId,
count,
});
src/lib/mariadb/db-sql.ts
+1 -4
View File
@@ -41,13 +41,10 @@ export default async function DbSQL<
const payload = isSelect ? ((res.payload || []) as T[]) : undefined;
const single_res = isSelect ? payload?.[0] : (res.single_res as T);
const singleRaw = res.single_res as any;
return {
...res,
success: isSelect
? Boolean(single_res) || Boolean(payload?.[0])
: true,
success: true,
payload,
single_res,
debug: {
src/lib/mariadb/db-update.ts
+96 -91
View File
@@ -1,5 +1,4 @@
import dbHandler from "../db-handler";
import _ from "lodash";
import dbHandler, { resolveClient } from "../db-handler";
import type {
BunMariaDBConfig,
DBResponseObject,
@@ -9,6 +8,8 @@ import type {
import sqlGenerator from "../../utils/sql-generator";
import sanitizeHtmlFields from "../../utils/sanitize-html-fields";
import { quoteIdentifier } from "../../utils/sql-identifier";
import sqlValuePlaceholder from "../../utils/sql-value-placeholder";
import grabTableFields from "../../utils/grab-table-fields";
type Params<
Schema extends { [k: string]: any } = { [k: string]: any },
@@ -21,6 +22,13 @@ type Params<
config?: BunMariaDBConfig;
};
/** Thrown inside the transaction to roll back and return a response */
class UpdateAbort extends Error {
constructor(public response: DBResponseObject) {
super(response.msg || response.error || "Update aborted");
}
}
export default async function DbUpdate<
Schema extends { [k: string]: any } = { [k: string]: any },
Table extends string = string,
@@ -39,24 +47,12 @@ export default async function DbUpdate<
};
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge<ServerQueryParam<any>, ServerQueryParam<any>>(
finalQuery,
{
query: {
id: {
value: Number(targetId),
},
},
},
);
}
const finalQuery = query || {};
const sqlQueryObj = sqlGenerator({
tableName: table,
genObject: finalQuery,
targetId,
});
const whereClause = sqlQueryObj.where;
@@ -68,101 +64,110 @@ export default async function DbUpdate<
};
}
/**
* Capture the matching row ids first, so the updated rows can be
* re-fetched even if the update changes a column used in the WHERE
* clause.
*/
const matched_res = await dbHandler<{ id: number }>({
query: `SELECT id FROM ${quoteIdentifier(table)} ${whereClause}`,
values: sqlQueryObj.whereValues as any,
config,
});
if (!matched_res.success) {
return {
...matched_res,
success: false,
debug: { sqlObj: sqlQueryObj },
};
}
const matched_ids = (matched_res.payload || [])
.map((row) => row.id)
.filter((id) => id !== undefined && id !== null);
if (matched_ids.length === 0) {
return {
success: false,
msg: "No rows matched the update query",
payload: [],
debug: { sqlObj: sqlQueryObj },
};
}
let values: SQLInsertGenValueType[] = [];
let sql = ``;
sql += `UPDATE ${quoteIdentifier(table)} SET`;
const sanitizedData = sanitizeHtmlFields({
table,
data,
config,
});
const finalData: { [k: string]: SQLInsertGenValueType } = {
const finalData: { [k: string]: any } = {
updated_at: Date.now(),
...sanitizedData,
};
const keys = Object.keys(finalData);
const fieldsMap = new Map(
grabTableFields(table).map((f) => [f.fieldName, f]),
);
for (let i = 0; i < keys.length; i++) {
const key = keys[i];
if (!key) continue;
const setParts: string[] = [];
const setValues: SQLInsertGenValueType[] = [];
const isLast = i == keys.length - 1;
for (const key of Object.keys(finalData)) {
const { placeholder, value } = sqlValuePlaceholder({
value: finalData[key],
field: fieldsMap.get(key),
});
sql += ` ${quoteIdentifier(key)}=?`;
values.push(finalData[key] ?? null);
setParts.push(`${quoteIdentifier(key)}=${placeholder}`);
setValues.push(value);
}
if (!isLast) {
sql += `,`;
const CLIENT = resolveClient(config);
if (!CLIENT) {
throw new Error(`Couldn't grab MariaDB Client.`);
}
/**
* Lock the matching rows, update them by id, and re-fetch them by id,
* all in one transaction. Re-fetching by id still works when the update
* changes a column used in the WHERE clause.
*/
return await CLIENT.begin(async (tx) => {
const matched_res = await dbHandler<{ id: number }>({
query: `SELECT id FROM ${quoteIdentifier(table)} ${whereClause} FOR UPDATE`,
values: sqlQueryObj.whereValues as any,
client: tx,
});
if (!matched_res.success) {
throw new UpdateAbort({
...matched_res,
success: false,
debug: { sqlObj: sqlQueryObj },
});
}
}
const idPlaceholders = matched_ids.map(() => "?").join(",");
const matched_ids = (matched_res.payload || [])
.map((row) => row.id)
.filter((id) => id !== undefined && id !== null);
sql += ` WHERE id IN (${idPlaceholders})`;
values = [...values, ...matched_ids];
if (matched_ids.length === 0) {
throw new UpdateAbort({
success: false,
msg: "No rows matched the update query",
payload: [],
debug: { sqlObj: sqlQueryObj },
});
}
const res = await dbHandler({
query: sql,
values: values as any,
config,
const idPlaceholders = matched_ids.map(() => "?").join(",");
const sql = `UPDATE ${quoteIdentifier(table)} SET ${setParts.join(", ")} WHERE id IN (${idPlaceholders})`;
const values = [...setValues, ...matched_ids];
sqlObj.string = sql;
sqlObj.values = values;
const res = await dbHandler({
query: sql,
values: values as any,
client: tx,
});
if (!res.success) {
throw new UpdateAbort({ ...res, debug: { sqlObj } });
}
const updated_res = await dbHandler({
query: `SELECT * FROM ${quoteIdentifier(table)} WHERE id IN (${idPlaceholders})`,
values: matched_ids,
client: tx,
});
return {
...updated_res,
debug: {
sqlObj,
},
db_res: res.db_res,
} as DBResponseObject;
});
sqlObj.string = sql;
sqlObj.values = values as any[];
if (res.error) {
return { ...res, debug: { sqlObj } };
}
const updated_res = await dbHandler({
query: `SELECT * FROM ${quoteIdentifier(table)} WHERE id IN (${idPlaceholders})`,
values: matched_ids,
config,
});
return {
...updated_res,
debug: {
sqlObj,
},
db_res: res.db_res,
};
} catch (error: any) {
if (error instanceof UpdateAbort) {
return error.response;
}
return {
success: false,
error: error.message,
src/lib/schema/get-table-columns-gemnini.ts
-73
View File
@@ -1,73 +0,0 @@
import type { BunMariaDBConfig } from "../../types";
import { querySchemaRows } from "./run-schema-query";
import schemaCondition from "./schema-condition";
export type ColumnInfoRow = {
name: string;
type: string;
comment?: string;
isNullable: boolean;
columnDefault: string | null;
extra: string;
};
export default async function getTableColumnsGemini({
tableName,
config,
}: {
tableName: string;
config?: BunMariaDBConfig;
}): Promise<ColumnInfoRow[]> {
const schemaCond = schemaCondition(config);
const rows = await querySchemaRows<{
COLUMN_NAME: string;
COLUMN_TYPE: string;
COLUMN_COMMENT: string;
IS_NULLABLE: string;
COLUMN_DEFAULT: string | null;
EXTRA: string;
IS_JSON: number | boolean;
}>({
query: `
SELECT
c.COLUMN_NAME,
c.COLUMN_TYPE,
c.COLUMN_COMMENT,
c.IS_NULLABLE,
c.COLUMN_DEFAULT,
c.EXTRA,
EXISTS (
SELECT 1
FROM information_schema.CHECK_CONSTRAINTS cc
WHERE cc.CONSTRAINT_SCHEMA = c.TABLE_SCHEMA
AND cc.TABLE_NAME = c.TABLE_NAME
AND cc.CHECK_CLAUSE LIKE CONCAT('%json_valid(\`', c.COLUMN_NAME, '\`)%')
) AS IS_JSON
FROM information_schema.COLUMNS c
WHERE ${schemaCond.where.replace(/\bTABLE_SCHEMA\b/g, "c.TABLE_SCHEMA")}
AND c.TABLE_NAME = ?
ORDER BY c.ORDINAL_POSITION
`,
values: [...schemaCond.values, tableName],
config,
});
return rows.map((row) => {
const isJson = Number(row.IS_JSON) === 1;
// Normalize longtext with a json_valid constraint to "json"
let resolvedType = row.COLUMN_TYPE;
if (isJson && row.COLUMN_TYPE.toLowerCase() === "longtext") {
resolvedType = "json";
}
return {
name: row.COLUMN_NAME,
type: resolvedType,
comment: row.COLUMN_COMMENT,
isNullable: String(row.IS_NULLABLE).toUpperCase() === "YES",
columnDefault: row.COLUMN_DEFAULT,
extra: row.EXTRA || "",
};
});
}
src/lib/schema/get-table-columns.ts
+42 -9
View File
@@ -11,6 +11,9 @@ export type ColumnInfoRow = {
extra: string;
};
/**
* Live column info. LONGTEXT columns with a `json_valid` check are reported as `json`.
*/
export default async function getTableColumns({
tableName,
config,
@@ -26,18 +29,48 @@ export default async function getTableColumns({
IS_NULLABLE: string;
COLUMN_DEFAULT: string | null;
EXTRA: string;
IS_JSON: number | boolean;
}>({
query: `SELECT COLUMN_NAME, COLUMN_TYPE, COLUMN_COMMENT, IS_NULLABLE, COLUMN_DEFAULT, EXTRA FROM information_schema.COLUMNS WHERE ${schemaCond.where} AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION`,
query: `
SELECT
c.COLUMN_NAME,
c.COLUMN_TYPE,
c.COLUMN_COMMENT,
c.IS_NULLABLE,
c.COLUMN_DEFAULT,
c.EXTRA,
EXISTS (
SELECT 1
FROM information_schema.CHECK_CONSTRAINTS cc
WHERE cc.CONSTRAINT_SCHEMA = c.TABLE_SCHEMA
AND cc.TABLE_NAME = c.TABLE_NAME
AND cc.CHECK_CLAUSE LIKE CONCAT('%json_valid(\`', c.COLUMN_NAME, '\`)%')
) AS IS_JSON
FROM information_schema.COLUMNS c
WHERE ${schemaCond.where.replace(/\bTABLE_SCHEMA\b/g, "c.TABLE_SCHEMA")}
AND c.TABLE_NAME = ?
ORDER BY c.ORDINAL_POSITION
`,
values: [...schemaCond.values, tableName],
config,
});
return rows.map((row) => ({
name: row.COLUMN_NAME,
type: row.COLUMN_TYPE,
comment: row.COLUMN_COMMENT,
isNullable: String(row.IS_NULLABLE).toUpperCase() === "YES",
columnDefault: row.COLUMN_DEFAULT,
extra: row.EXTRA || "",
}));
return rows.map((row) => {
const isJson = Number(row.IS_JSON) === 1;
// Normalize longtext with a json_valid constraint to "json"
let resolvedType = row.COLUMN_TYPE;
if (isJson && row.COLUMN_TYPE.toLowerCase() === "longtext") {
resolvedType = "json";
}
return {
name: row.COLUMN_NAME,
type: resolvedType,
comment: row.COLUMN_COMMENT,
isNullable: String(row.IS_NULLABLE).toUpperCase() === "YES",
columnDefault: row.COLUMN_DEFAULT,
extra: row.EXTRA || "",
};
});
}
src/lib/schema/mariadb-quote-gen.ts
+3 -1
View File
@@ -1,3 +1,5 @@
import { quoteIdentifier } from "../../utils/sql-identifier";
export default function MariaDBQuoteGen(str: string) {
return `\`${str.replace(/`/g, "``")}\``;
return quoteIdentifier(str);
}
src/lib/schema/run-schema-query.ts
+75
View File
@@ -1,6 +1,62 @@
import type { BunMariaDBConfig } from "../../types";
import dbHandler from "../db-handler";
type SchemaRunState = {
/** Record statements instead of executing them */
dryRun: boolean;
statements: string[];
/**
* Destructive statements that may run. `true` allows all of them;
* otherwise only exact matches are allowed.
*/
allowDestructive: true | Set<string>;
};
let schemaRunState: SchemaRunState | null = null;
/**
* Statements that discard stored data (tables or column values).
*/
export function isDestructiveSchemaStatement(query: string): boolean {
return /^\s*DROP\s+TABLE\b/i.test(query) || /\bDROP\s+COLUMN\b/i.test(query);
}
/**
* Run `fn` with schema statements recorded but not executed.
* Reads (information_schema) still run, so the plan is a close approximation:
* steps that depend on earlier changes (e.g. after a table rename) may differ.
*/
export async function planSchemaQueries(
fn: () => Promise<unknown>,
): Promise<string[]> {
const previous = schemaRunState;
schemaRunState = { dryRun: true, statements: [], allowDestructive: true };
try {
await fn();
return schemaRunState.statements;
} finally {
schemaRunState = previous;
}
}
/**
* Run `fn`, refusing any destructive statement that was not approved.
*/
export async function runSchemaQueriesGuarded(
fn: () => Promise<unknown>,
allowDestructive: true | Set<string>,
): Promise<void> {
const previous = schemaRunState;
schemaRunState = { dryRun: false, statements: [], allowDestructive };
try {
await fn();
} finally {
schemaRunState = previous;
}
}
export default async function runSchemaQuery({
query,
values,
@@ -10,6 +66,25 @@ export default async function runSchemaQuery({
values?: any[];
config?: BunMariaDBConfig;
}): Promise<void> {
if (schemaRunState) {
schemaRunState.statements.push(query);
if (schemaRunState.dryRun) {
return;
}
const allowed = schemaRunState.allowDestructive;
if (
allowed !== true &&
isDestructiveSchemaStatement(query) &&
!allowed.has(query)
) {
throw new Error(
`Refusing unapproved destructive statement: ${query}. Re-run with --dry-run to review, or --yes to allow it.`,
);
}
}
const res = await dbHandler({
query,
values,
src/lib/schema/update-table.ts
+1 -2
View File
@@ -8,7 +8,6 @@ import buildColumnDefinition, {
} from "./build-column-definition";
import createTable from "./create-table";
import getTableColumns, { type ColumnInfoRow } from "./get-table-columns";
import getTableColumnsGemini from "./get-table-columns-gemnini";
import isVectorField from "./is-vector-field";
import mapDataType from "./map-data-types";
import MariaDBQuoteGen from "./mariadb-quote-gen";
@@ -278,7 +277,7 @@ export default async function updateTable({
table: BUN_MARIADB_TableSchemaType;
config?: BunMariaDBConfig;
}): Promise<void> {
const existingColumns = await getTableColumnsGemini({
const existingColumns = await getTableColumns({
tableName: table.tableName,
config,
});