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

- 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:
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
+12 -1
View File
@@ -1,9 +1,20 @@
import type { BunMariaDBConfig, 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.
*/
export declare function resolveClient(config?: BunMariaDBConfig): Bun.SQL | undefined;
/**
* # Main DB Handler Function
*/
@@ -11,5 +22,5 @@ export default 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>>;
export {};
+42 -21
View File
@@ -1,41 +1,62 @@
import grabMariaDBClient from "../functions/grab-mariadb-client";
import grabMariaDBClient, { mariadbClientCacheKey, } from "../functions/grab-mariadb-client";
/**
* 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) {
const resolvedConfig = config || global.CONFIG;
// Same database as the global client → reuse it
if (global.MARIADB_CLIENT &&
(!resolvedConfig?.db_name ||
!global.CONFIG?.db_name ||
resolvedConfig.db_name === global.CONFIG.db_name)) {
export function resolveClient(config) {
if (!config) {
return global.MARIADB_CLIENT;
}
if (resolvedConfig) {
return grabMariaDBClient({ config: resolvedConfig });
// Same connection config as the global client → reuse it
if (global.MARIADB_CLIENT &&
(!global.CONFIG ||
mariadbClientCacheKey(config) ===
mariadbClientCacheKey(global.CONFIG))) {
return global.MARIADB_CLIENT;
}
return global.MARIADB_CLIENT;
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) {
if (typeof value == "bigint") {
const num = Number(value);
return Number.isSafeInteger(num) ? num : value.toString();
}
if (value instanceof Date) {
return Number.isNaN(value.getTime()) ? null : value.toISOString();
}
return value;
}
function normalizeRows(res) {
if (!Array.isArray(res))
return undefined;
return res.map((row) => {
if (!row || typeof row != "object")
return row;
const normalized = {};
for (const [key, value] of Object.entries(row)) {
normalized[key] = normalizeValue(value);
}
return normalized;
});
}
/**
* # Main DB Handler Function
*/
export default async function dbHandler({ query, values, config }) {
export default async function dbHandler({ query, values, config, client }) {
try {
const CLIENT = resolveClient(config);
const CLIENT = client || resolveClient(config);
if (!CLIENT) {
throw new Error(`Couldn't grab MariaDB Client.`);
}
const res = await CLIENT.unsafe(query, values);
const count = res.count;
const res_array = (() => {
try {
return JSON.parse(JSON.stringify(res));
}
catch (error) {
return undefined;
}
})();
const res_array = normalizeRows(res);
const last_insert_id = res_array?.[0] ? res_array[0]?.id : undefined;
const affected_rows = res_array?.[0] ? res_array.length : undefined;
const insert_return = {
+1 -3
View File
@@ -1,6 +1,4 @@
function quoteIdentifier(identifier) {
return `\`${identifier.replace(/`/g, "``")}\``;
}
import { quoteIdentifier } from "../utils/sql-identifier";
export default async function ({ sql: passedSql, table, data }) {
const config = global.CONFIG;
const dbSchema = global.DB_SCHEMA;
+6 -15
View File
@@ -1,27 +1,17 @@
import dbHandler from "../db-handler";
import _ from "lodash";
import sqlGenerator from "../../utils/sql-generator";
function quoteIdentifier(identifier) {
return `\`${identifier.replace(/`/g, "``")}\``;
}
import { quoteIdentifier } from "../../utils/sql-identifier";
export default async function DbDelete({ table, query, targetId, config, }) {
let sqlObj = null;
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge(finalQuery, {
query: {
id: {
value: Number(targetId),
},
},
});
}
const finalQuery = query || {};
sqlObj = sqlGenerator({
tableName: quoteIdentifier(table),
tableName: table,
genObject: finalQuery,
targetId,
});
const whereClause = sqlObj.string.match(/WHERE .*/)?.[0];
const whereClause = sqlObj.where;
if (!whereClause) {
return {
success: false,
@@ -34,6 +24,7 @@ export default async function DbDelete({ table, query, targetId, config, }) {
let sql = `DELETE FROM ${quoteIdentifier(table)} ${whereClause}`;
sql += ` RETURNING *`;
sqlObj.string = sql;
sqlObj.values = sqlObj.whereValues;
const res = await dbHandler({
query: sql,
values: sqlObj.values,
+7 -10
View File
@@ -1,5 +1,6 @@
import _ from "lodash";
import generateTypeDefinition from "./db-generate-type-defs";
import resolveTable from "../schema/resolve-table";
export default function dbSchemaToType({ config, dbSchema, }) {
let datasquirelSchema = dbSchema;
if (!datasquirelSchema)
@@ -14,16 +15,12 @@ export default function dbSchemaToType({ config, dbSchema, }) {
const defNames = [];
const schemas = dbTablesSchemas
.map((table) => {
let final_table = _.cloneDeep(table);
if (final_table.parentTableName) {
const parent_table = dbTablesSchemas.find((t) => t.tableName === final_table.parentTableName);
if (parent_table) {
final_table = _.merge(parent_table, {
tableName: final_table.tableName,
tableDescription: final_table.tableDescription,
});
}
}
const has_parent = Boolean(table.parentTableName &&
dbTablesSchemas.find((t) => t.tableName === table.parentTableName));
// Merge parent fields into a copy; never mutate the parent schema
const final_table = has_parent
? resolveTable(table, datasquirelSchema)
: _.cloneDeep(table);
const defObj = generateTypeDefinition({
paradigm: "TypeScript",
table: final_table,
+5 -16
View File
@@ -1,25 +1,13 @@
import dbHandler from "../db-handler";
import _ from "lodash";
import sqlGenerator from "../../utils/sql-generator";
function quoteIdentifier(identifier) {
return `\`${identifier.replace(/`/g, "``")}\``;
}
export default async function DbSelect({ table, query, count, targetId, config, }) {
let sqlObj = null;
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge(finalQuery, {
query: {
id: {
value: Number(targetId),
},
},
});
}
const finalQuery = query || {};
sqlObj = sqlGenerator({
tableName: quoteIdentifier(table),
tableName: table,
genObject: finalQuery,
targetId,
});
const res = await dbHandler({
query: sqlObj.string,
@@ -49,8 +37,9 @@ export default async function DbSelect({ table, query, count, targetId, config,
};
if (count) {
const countSqlObject = sqlGenerator({
tableName: quoteIdentifier(table),
tableName: table,
genObject: finalQuery,
targetId,
count,
});
const countSql = `SELECT COUNT(*) AS count FROM (${countSqlObject.string}) AS c`;
+3 -2
View File
@@ -1,11 +1,12 @@
import type { DBResponseObject, SQLInsertGenValueType } from "../../types";
import type { BunMariaDBConfig, DBResponseObject, SQLInsertGenValueType } from "../../types";
type Params = {
sql: string;
values?: SQLInsertGenValueType[];
config?: BunMariaDBConfig;
};
export default function DbSQL<T extends {
[k: string]: any;
} = {
[k: string]: any;
}>({ sql, values }: Params): Promise<DBResponseObject<T>>;
}>({ sql, values, config }: Params): Promise<DBResponseObject<T>>;
export {};
+3 -5
View File
@@ -1,11 +1,12 @@
import dbHandler from "../db-handler";
export default async function DbSQL({ sql, values }) {
export default async function DbSQL({ sql, values, config }) {
try {
const trimmedSql = sql.trim();
const isSelect = trimmedSql.match(/^select/i);
const res = await dbHandler({
query: trimmedSql,
values: values,
config,
});
if (!res.success) {
return {
@@ -23,12 +24,9 @@ export default async function DbSQL({ sql, values }) {
}
const payload = isSelect ? (res.payload || []) : undefined;
const single_res = isSelect ? payload?.[0] : res.single_res;
const singleRaw = res.single_res;
return {
...res,
success: isSelect
? Boolean(single_res) || Boolean(payload?.[0])
: true,
success: true,
payload,
single_res,
debug: {
+92 -58
View File
@@ -1,37 +1,38 @@
import dbHandler from "../db-handler";
import _ from "lodash";
import dbHandler, { resolveClient } from "../db-handler";
import sqlGenerator from "../../utils/sql-generator";
import sanitizeHtmlFields from "../../utils/sanitize-html-fields";
function quoteIdentifier(identifier) {
return `\`${identifier.replace(/`/g, "``")}\``;
import { quoteIdentifier } from "../../utils/sql-identifier";
import sqlValuePlaceholder from "../../utils/sql-value-placeholder";
import grabTableFields from "../../utils/grab-table-fields";
/** Thrown inside the transaction to roll back and return a response */
class UpdateAbort extends Error {
response;
constructor(response) {
super(response.msg || response.error || "Update aborted");
this.response = response;
}
}
export default async function DbUpdate({ table, data, query, targetId, config, }) {
let sqlObj = { string: "", values: [] };
let sqlObj = {
string: "",
values: [],
where: "",
whereValues: [],
};
try {
let finalQuery = query || {};
if (targetId) {
finalQuery = _.merge(finalQuery, {
query: {
id: {
value: Number(targetId),
},
},
});
}
const finalQuery = query || {};
const sqlQueryObj = sqlGenerator({
tableName: quoteIdentifier(table),
tableName: table,
genObject: finalQuery,
targetId,
});
const whereClause = sqlQueryObj.string.match(/WHERE .*/)?.[0];
const whereClause = sqlQueryObj.where;
if (!whereClause) {
return {
success: false,
msg: `No WHERE clause`,
};
}
let values = [];
let sql = ``;
sql += `UPDATE ${quoteIdentifier(table)} SET`;
const sanitizedData = sanitizeHtmlFields({
table,
data,
@@ -41,48 +42,81 @@ export default async function DbUpdate({ table, data, query, targetId, config, }
updated_at: Date.now(),
...sanitizedData,
};
const keys = Object.keys(finalData);
for (let i = 0; i < keys.length; i++) {
const key = keys[i];
if (!key)
continue;
const isLast = i == keys.length - 1;
sql += ` ${quoteIdentifier(key)}=?`;
values.push(finalData[key] ?? null);
if (!isLast) {
sql += `,`;
const fieldsMap = new Map(grabTableFields(table).map((f) => [f.fieldName, f]));
const setParts = [];
const setValues = [];
for (const key of Object.keys(finalData)) {
const { placeholder, value } = sqlValuePlaceholder({
value: finalData[key],
field: fieldsMap.get(key),
});
setParts.push(`${quoteIdentifier(key)}=${placeholder}`);
setValues.push(value);
}
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({
query: `SELECT id FROM ${quoteIdentifier(table)} ${whereClause} FOR UPDATE`,
values: sqlQueryObj.whereValues,
client: tx,
});
if (!matched_res.success) {
throw new UpdateAbort({
...matched_res,
success: false,
debug: { sqlObj: sqlQueryObj },
});
}
}
sql += ` ${whereClause}`;
values = [...values, ...sqlQueryObj.values];
const res = await dbHandler({
query: sql,
values: values,
config,
const matched_ids = (matched_res.payload || [])
.map((row) => row.id)
.filter((id) => id !== undefined && id !== null);
if (matched_ids.length === 0) {
throw new UpdateAbort({
success: false,
msg: "No rows matched the update query",
payload: [],
debug: { sqlObj: sqlQueryObj },
});
}
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,
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,
};
});
if (res.error) {
return res;
}
sqlObj.string = sql;
sqlObj.values = values;
let updated_sql = ``;
let updated_sql_values = [];
updated_sql += `SELECT * FROM ${quoteIdentifier(table)} ${whereClause}`;
updated_sql_values = [...sqlQueryObj.values];
const updated_res = await dbHandler({
query: updated_sql,
values: updated_sql_values,
config,
});
return {
...updated_res,
debug: {
sqlObj,
},
db_res: res.db_res,
};
}
catch (error) {
if (error instanceof UpdateAbort) {
return error.response;
}
return {
success: false,
error: error.message,
-13
View File
@@ -1,13 +0,0 @@
import type { BunMariaDBConfig } from "../../types";
export type ColumnInfoRow = {
name: string;
type: string;
comment?: string;
isNullable: boolean;
columnDefault: string | null;
extra: string;
};
export default function getTableColumnsGemini({ tableName, config, }: {
tableName: string;
config?: BunMariaDBConfig;
}): Promise<ColumnInfoRow[]>;
-45
View File
@@ -1,45 +0,0 @@
import { querySchemaRows } from "./run-schema-query";
import schemaCondition from "./schema-condition";
export default async function getTableColumnsGemini({ tableName, config, }) {
const schemaCond = schemaCondition(config);
const rows = await querySchemaRows({
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 || "",
};
});
}
+3
View File
@@ -7,6 +7,9 @@ export type ColumnInfoRow = {
columnDefault: string | null;
extra: string;
};
/**
* Live column info. LONGTEXT columns with a `json_valid` check are reported as `json`.
*/
export default function getTableColumns({ tableName, config, }: {
tableName: string;
config?: BunMariaDBConfig;
+39 -9
View File
@@ -1,18 +1,48 @@
import { querySchemaRows } from "./run-schema-query";
import schemaCondition from "./schema-condition";
/**
* Live column info. LONGTEXT columns with a `json_valid` check are reported as `json`.
*/
export default async function getTableColumns({ tableName, config, }) {
const schemaCond = schemaCondition(config);
const rows = await querySchemaRows({
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 || "",
};
});
}
+2 -1
View File
@@ -1,3 +1,4 @@
import { quoteIdentifier } from "../../utils/sql-identifier";
export default function MariaDBQuoteGen(str) {
return `\`${str.replace(/`/g, "``")}\``;
return quoteIdentifier(str);
}
+14
View File
@@ -1,4 +1,18 @@
import type { BunMariaDBConfig } from "../../types";
/**
* Statements that discard stored data (tables or column values).
*/
export declare function isDestructiveSchemaStatement(query: string): boolean;
/**
* 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 declare function planSchemaQueries(fn: () => Promise<unknown>): Promise<string[]>;
/**
* Run `fn`, refusing any destructive statement that was not approved.
*/
export declare function runSchemaQueriesGuarded(fn: () => Promise<unknown>, allowDestructive: true | Set<string>): Promise<void>;
export default function runSchemaQuery({ query, values, config, }: {
query: string;
values?: any[];
+48
View File
@@ -1,5 +1,53 @@
import dbHandler from "../db-handler";
let schemaRunState = null;
/**
* Statements that discard stored data (tables or column values).
*/
export function isDestructiveSchemaStatement(query) {
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) {
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, allowDestructive) {
const previous = schemaRunState;
schemaRunState = { dryRun: false, statements: [], allowDestructive };
try {
await fn();
}
finally {
schemaRunState = previous;
}
}
export default async function runSchemaQuery({ query, values, config, }) {
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,
+1 -2
View File
@@ -1,7 +1,6 @@
import buildColumnDefinition, { fieldRequiresNotNull, } from "./build-column-definition";
import createTable from "./create-table";
import getTableColumns, {} 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";
@@ -188,7 +187,7 @@ async function recreateColumn({ tableName, field, config, }) {
await addColumn({ tableName, field, config });
}
export default async function updateTable({ table, config, }) {
const existingColumns = await getTableColumnsGemini({
const existingColumns = await getTableColumns({
tableName: table.tableName,
config,
});