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]>
2026-10-14 02:27:59 +01:00
parent b81b09324a
commit ddf431e866
82 changed files with 2140 additions and 1403 deletions
@@ -9,8 +9,19 @@ import exportCmd from "./export";
 import importCmd from "./import";
 import admin from "./admin";
 import init from "../functions/init";
+import { readFileSync } from "fs";

-init();
+try {
+    init();
+} catch (error: any) {
+    console.error(`Initialization ERROR => ${error.message}`);
+    process.exit(1);
+}
+
+/** Resolves to the package root from both src/commands and dist/commands */
+const { version } = JSON.parse(
+    readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+);

 /**
 * # Describe Program
@@ -18,7 +29,7 @@ init();
 program
    .name(`bun-mariadb`)
    .description(`MariaDB manager for Bun`)
-    .version(`1.0.0`);
+    .version(version);

 /**
 * # Declare Commands
@@ -6,11 +6,39 @@ import appendDefaultFieldsToDbSchema from "../utils/append-default-fields-to-db-
 import chalk from "chalk";
 import { writeLiveSchema } from "../functions/live-schema";
 import createDBSchema from "../lib/schema/create-db-schema";
+import {
+    isDestructiveSchemaStatement,
+    planSchemaQueries,
+    runSchemaQueriesGuarded,
+} from "../lib/schema/run-schema-query";
+import { confirm } from "@inquirer/prompts";
+import { AppData } from "../data/app-data";
+
+/** Silence progress logs while computing a plan */
+async function quietly<T>(fn: () => Promise<T>): Promise<T> {
+    const { log, warn } = console;
+    console.log = () => {};
+    console.warn = () => {};
+    try {
+        return await fn();
+    } finally {
+        console.log = log;
+        console.warn = warn;
+    }
+}

 export default function () {
    return new Command("schema")
        .description("Build DB From Schema")
        .option("-t, --typedef", "Generate typescript type definitions")
+        .option(
+            "--dry-run",
+            "Print the schema changes that would be applied, without applying them",
+        )
+        .option(
+            "-y, --yes",
+            "Apply destructive changes (dropped tables / columns) without confirmation",
+        )
        .action(async (opts) => {
            console.log(`Starting process ...`);

@@ -26,10 +54,78 @@ export default function () {
                    dbSchema,
                });

-                await createDBSchema({
-                    db_schema: finaldbSchema,
-                    config,
-                });
+                const params = { db_schema: finaldbSchema, config };
+
+                // Hide internal bookkeeping (schema manager rows, FK check toggles)
+                const plan = (
+                    await quietly(() =>
+                        planSchemaQueries(() => createDBSchema(params)),
+                    )
+                ).filter(
+                    (statement) =>
+                        !statement.includes(AppData.DbSchemaManagerTableName) &&
+                        !/^SET FOREIGN_KEY_CHECKS/i.test(statement),
+                );
+                const destructive = plan.filter(isDestructiveSchemaStatement);
+
+                if (opts.dryRun) {
+                    if (!plan.length) {
+                        console.log(chalk.green(`Schema is up to date.`));
+                    } else {
+                        console.log(chalk.bold(`Planned schema changes:\n`));
+                        for (const statement of plan) {
+                            console.log(
+                                isDestructiveSchemaStatement(statement)
+                                    ? chalk.red(`  ${statement}`)
+                                    : `  ${statement}`,
+                            );
+                        }
+                        if (destructive.length) {
+                            console.log(
+                                chalk.red(
+                                    `\n${destructive.length} destructive change(s) (in red) would discard data.`,
+                                ),
+                            );
+                        }
+                    }
+                    process.exit(0);
+                }
+
+                if (destructive.length && !opts.yes) {
+                    console.log(
+                        chalk.yellow(
+                            `\nThese changes will permanently discard data:\n`,
+                        ),
+                    );
+                    for (const statement of destructive) {
+                        console.log(chalk.red(`  ${statement}`));
+                    }
+                    console.log();
+
+                    if (!process.stdin.isTTY) {
+                        console.error(
+                            chalk.red(
+                                `Refusing to apply destructive changes non-interactively. Re-run with --yes to apply them.`,
+                            ),
+                        );
+                        process.exit(1);
+                    }
+
+                    const proceed = await confirm({
+                        message: `Apply ${destructive.length} destructive change(s)?`,
+                        default: false,
+                    });
+
+                    if (!proceed) {
+                        console.log(chalk.dim(`Schema sync cancelled.`));
+                        process.exit(1);
+                    }
+                }
+
+                await runSchemaQueriesGuarded(
+                    () => createDBSchema(params),
+                    opts.yes ? true : new Set(destructive),
+                );

                if (isTypeDef && config.typedef_file_path) {
                    const out_file = path.resolve(
@@ -7,23 +7,37 @@ type Params = {
    config: BunMariaDBConfig;
 };

-/** Reuse one client per database name to avoid exhausting MariaDB connections. */
+/** Reuse one client per distinct connection config to avoid exhausting MariaDB connections. */
 const clientCache = new Map<string, Bun.SQL>();

+/**
+ * Cache key covering everything that affects the connection, not just the
+ * database name.
+ */
+export function mariadbClientCacheKey(config?: BunMariaDBConfig): string {
+    return JSON.stringify({
+        db_name: config?.db_name || "__default__",
+        db_config: config?.db_config || null,
+        ssl_ca: config?.ssl_ca || null,
+        ssl_reject_unauthorized: config?.ssl_reject_unauthorized ?? null,
+    });
+}
+
 export default function grabMariaDBClient({
    config,
 }: Params): Bun.SQL | undefined {
-    const cacheKey = config.db_name || "__default__";
+    const cacheKey = mariadbClientCacheKey(config);

    const cached = clientCache.get(cacheKey);
    if (cached) {
        return cached;
    }

-    // Prefer the process-wide client when it matches the requested database
+    // Prefer the process-wide client when it was created from the same config
    if (
        global.MARIADB_CLIENT &&
-        (!global.CONFIG?.db_name || global.CONFIG.db_name === config.db_name)
+        global.CONFIG &&
+        mariadbClientCacheKey(global.CONFIG) === cacheKey
    ) {
        clientCache.set(cacheKey, global.MARIADB_CLIENT);
        return global.MARIADB_CLIENT;
@@ -24,121 +24,112 @@ declare global {
    var SCHEMA_FILE_PATH: string;
 }

+/**
+ * Load config + schema and set up the shared MariaDB client.
+ * Throws on any problem (never exits the process).
+ */
 export default function init(): void {
-    try {
-        const { ROOT_DIR } = grabDirNames();
-        const { ConfigFileName } = AppData;
+    const { ROOT_DIR } = grabDirNames();
+    const { ConfigFileName } = AppData;

-        const loadedConfig = resolveAndLoadDataFile<BunMariaDBConfig>(
-            ROOT_DIR,
-            ConfigFileName,
+    const loadedConfig = resolveAndLoadDataFile<BunMariaDBConfig>(
+        ROOT_DIR,
+        ConfigFileName,
+    );
+
+    if (!loadedConfig) {
+        throw new Error(
+            `Please create a ${supportedDataFileNames(ConfigFileName)} file at the root of your project.`,
+        );
+    }
+
+    const Config = loadedConfig.data;
+
+    if (!Config || typeof Config !== "object") {
+        throw new Error(
+            `Invalid config in \`${loadedConfig.path}\`. Expected a config object${loadedConfig.format === "ts" || loadedConfig.format === "js" ? " (export default)" : ""}.`,
+        );
+    }
+
+    if (!Config.db_name) {
+        throw new Error(
+            `\`db_name\` is required in your config`,
+        );
+    }
+
+    RequiredENVs.forEach((env_key) => {
+        if (
+            env_key == "BUN_MARIADB_SERVER_PORT" ||
+            env_key == "BUN_MARIADB_SERVER_SSL_KEY_PATH"
+        ) {
+            return;
+        }
+
+        if (!process.env[env_key]) {
+            throw new Error(
+                `\`${env_key}\` env variable is required.`,
+            );
+        }
+    });
+
+    if (!Config.db_dir) {
+        throw new Error(
+            `\`db_dir\` is required in your config. This directory holds all database related configuration. Also note that a ${supportedDataFileNames(AppData.DbSchemaFileName)} file is also required in this directory to define your database schema`,
+        );
+    }
+
+    const db_dir = path.resolve(ROOT_DIR, Config.db_dir);
+    if (!fs.existsSync(db_dir)) {
+        fs.mkdirSync(db_dir, { recursive: true });
+    }
+
+    const loadedSchema =
+        resolveAndLoadDataFile<BUN_MARIADB_DatabaseSchemaType>(
+            db_dir,
+            AppData.DbSchemaFileName,
        );

-        if (!loadedConfig) {
-            console.error(
-                `Please create a ${supportedDataFileNames(ConfigFileName)} file at the root of your project.`,
-            );
-            process.exit(1);
-        }
-
-        const Config = loadedConfig.data;
-
-        if (!Config || typeof Config !== "object") {
-            console.error(
-                `Invalid config in \`${loadedConfig.path}\`. Expected a config object${loadedConfig.format === "ts" || loadedConfig.format === "js" ? " (export default)" : ""}.`,
-            );
-            process.exit(1);
-        }
-
-        if (!Config.db_name) {
-            console.error(`\`db_name\` is required in your config`);
-            process.exit(1);
-        }
-
-        RequiredENVs.forEach((env_key) => {
-            if (
-                env_key == "BUN_MARIADB_SERVER_PORT" ||
-                env_key == "BUN_MARIADB_SERVER_SSL_KEY_PATH"
-            ) {
-                return;
-            }
-
-            if (!process.env[env_key]) {
-                console.error(`\`${env_key}\` env variable is required.`);
-                process.exit(1);
-            }
-        });
-
-        if (!Config.db_dir) {
-            console.error(
-                `\`db_dir\` is required in your config. This directory holds all database related configuration. Also note that a ${supportedDataFileNames(AppData.DbSchemaFileName)} file is also required in this directory to define your database schema`,
-            );
-            process.exit(1);
-        }
-
-        const db_dir = path.resolve(ROOT_DIR, Config.db_dir);
-        if (!fs.existsSync(db_dir)) {
-            fs.mkdirSync(db_dir, { recursive: true });
-        }
-
-        const loadedSchema =
-            resolveAndLoadDataFile<BUN_MARIADB_DatabaseSchemaType>(
-                db_dir,
-                AppData.DbSchemaFileName,
-            );
-
-        if (!loadedSchema) {
-            console.error(
-                `Please create a schema file (${supportedDataFileNames(AppData.DbSchemaFileName)}) in \`${db_dir}\`${loadedConfig.format === "ts" || loadedConfig.format === "js" ? ". Don't forget to export a default module from .ts/.js files." : "."}`,
-            );
-            process.exit(1);
-        }
-
-        const DbSchema = loadedSchema.data;
-
-        if (!DbSchema || typeof DbSchema !== "object") {
-            console.error(
-                `Invalid schema in \`${loadedSchema.path}\`. Expected a schema object${loadedSchema.format === "ts" || loadedSchema.format === "js" ? " (export default)" : ""}.`,
-            );
-            process.exit(1);
-        }
-
-        const backup_dir =
-            Config.db_backup_dir || AppData["DefaultBackupDirName"];
-
-        const BackupDir = path.resolve(db_dir, backup_dir);
-        if (!fs.existsSync(BackupDir)) {
-            fs.mkdirSync(BackupDir, { recursive: true });
-        }
-
-        const ExportDir = path.resolve(db_dir, AppData["DefaultExportDirName"]);
-        if (!fs.existsSync(ExportDir)) {
-            fs.mkdirSync(ExportDir, { recursive: true });
-        }
-
-        global.CONFIG = Config;
-        global.DB_SCHEMA = DbSchema;
-        global.CONFIG_FILE_PATH = loadedConfig.path;
-        global.SCHEMA_FILE_PATH = loadedSchema.path;
-
-        if (!global.CONFIG) {
-            console.error(`Couldn't grab global Config.`);
-            process.exit(1);
-        }
-
-        if (!global.DB_SCHEMA) {
-            console.error(`Couldn't grab Database Schema.`);
-            process.exit(1);
-        }
-
-        setMariaDBClient({ config: Config });
-
-        if (!global.MARIADB_CLIENT) {
-            console.error(`Couldn't set MariaDB Client.`);
-            process.exit(1);
-        }
-    } catch (error: any) {
-        console.error(`Initialization ERROR => ` + error.message);
-        process.exit(1);
+    if (!loadedSchema) {
+        throw new Error(
+            `Please create a schema file (${supportedDataFileNames(AppData.DbSchemaFileName)}) in \`${db_dir}\`${loadedConfig.format === "ts" || loadedConfig.format === "js" ? ". Don't forget to export a default module from .ts/.js files." : "."}`,
+        );
    }
+
+    const DbSchema = loadedSchema.data;
+
+    if (!DbSchema || typeof DbSchema !== "object") {
+        throw new Error(
+            `Invalid schema in \`${loadedSchema.path}\`. Expected a schema object${loadedSchema.format === "ts" || loadedSchema.format === "js" ? " (export default)" : ""}.`,
+        );
+    }
+
+    const backup_dir =
+        Config.db_backup_dir || AppData["DefaultBackupDirName"];
+
+    const BackupDir = path.resolve(db_dir, backup_dir);
+    if (!fs.existsSync(BackupDir)) {
+        fs.mkdirSync(BackupDir, { recursive: true });
+    }
+
+    const ExportDir = path.resolve(db_dir, AppData["DefaultExportDirName"]);
+    if (!fs.existsSync(ExportDir)) {
+        fs.mkdirSync(ExportDir, { recursive: true });
+    }
+
+    global.CONFIG = Config;
+    global.DB_SCHEMA = DbSchema;
+    global.CONFIG_FILE_PATH = loadedConfig.path;
+    global.SCHEMA_FILE_PATH = loadedSchema.path;
+
+    setMariaDBClient({ config: Config });
+}
+
+/**
+ * Initialize once, on first use.
+ */
+export function ensureInit(): void {
+    if (global.CONFIG && global.DB_SCHEMA && global.MARIADB_CLIENT !== undefined) {
+        return;
+    }
+    init();
 }
@@ -6,24 +6,11 @@ type Params = {
 };

 export default function setMariaDBClient({ config }: Params): void {
-    try {
-        const MariaDBClient = grabMariaDBClient({ config });
+    const MariaDBClient = grabMariaDBClient({ config });

-        if (!MariaDBClient) {
-            throw new Error(`Couldn't grab MariaDB Client`);
-        }
-
-        global.MARIADB_CLIENT = MariaDBClient;
-
-        // const test = await MariaDBClient.unsafe(`SHOW DATABASES`);
-
-        // if (!test.count) {
-        //     console.error(`MariaDBClient Error: Database not ready.`);
-        //     console.log(test);
-        //     process.exit(1);
-        // }
-    } catch (error: any) {
-        console.error(`ERROR setting MariaDB Client => ` + error.message);
-        process.exit(1);
+    if (!MariaDBClient) {
+        throw new Error(`Couldn't grab MariaDB Client`);
    }
+
+    global.MARIADB_CLIENT = MariaDBClient;
 }
@@ -1,4 +1,4 @@
-import init from "./functions/init";
+import { ensureInit } from "./functions/init";
 import DbDelete from "./lib/mariadb/db-delete";
 import DbInsert from "./lib/mariadb/db-insert";
 import DbSelect from "./lib/mariadb/db-select";
@@ -7,16 +7,25 @@ import DbUpdate from "./lib/mariadb/db-update";
 import grabDbSchema from "./utils/grab-db-schema";
 import grabJoinFieldsFromQueryObject from "./utils/grab-join-fields-from-query-object";

-init();
+/**
+ * Initialize lazily on first call, so importing the library never exits or
+ * throws. Setup errors (missing config / env) reject the call instead.
+ */
+function withInit<F extends (...args: any[]) => Promise<any>>(fn: F): F {
+    return (async (...args: Parameters<F>) => {
+        ensureInit();
+        return fn(...args);
+    }) as F;
+}

 const BunMariaDB = {
-    select: DbSelect,
-    insert: DbInsert,
-    update: DbUpdate,
-    delete: DbDelete,
-    sql: DbSQL,
+    select: withInit(DbSelect),
+    insert: withInit(DbInsert),
+    update: withInit(DbUpdate),
+    delete: withInit(DbDelete),
+    sql: withInit(DbSQL),
    utils: {
-        grab_db_schema: grabDbSchema,
+        grab_db_schema: withInit(grabDbSchema),
        grab_join_fields_from_query_object: grabJoinFieldsFromQueryObject,
    },
 } as const;
@@ -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;
@@ -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;
@@ -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;
@@ -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,
            });

@@ -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: {
@@ -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,
@@ -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 || "",
-        };
-    });
-}
@@ -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 || "",
+        };
+    });
 }
@@ -1,3 +1,5 @@
+import { quoteIdentifier } from "../../utils/sql-identifier";
+
 export default function MariaDBQuoteGen(str: string) {
-    return `\`${str.replace(/`/g, "``")}\``;
+    return quoteIdentifier(str);
 }
@@ -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,
@@ -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,
    });
@@ -0,0 +1,19 @@
+import type {
+    BUN_MARIADB_DatabaseSchemaType,
+    BUN_MARIADB_FieldSchemaType,
+} from "../types";
+import { readLiveSchema } from "../functions/live-schema";
+
+/**
+ * Grab a table's schema fields from the loaded (or last synced) schema.
+ */
+export default function grabTableFields(
+    tableName: string,
+): BUN_MARIADB_FieldSchemaType[] {
+    const dbSchema: BUN_MARIADB_DatabaseSchemaType | undefined =
+        global.DB_SCHEMA || readLiveSchema();
+
+    const tableSchema = dbSchema?.tables?.find((t) => t.tableName === tableName);
+
+    return tableSchema?.fields || [];
+}
@@ -1,20 +1,7 @@
 import sanitizeHtml from "sanitize-html";
-import type {
-    BUN_MARIADB_DatabaseSchemaType,
-    BUN_MARIADB_FieldSchemaType,
-    BunMariaDBConfig,
-} from "../types";
-import { readLiveSchema } from "../functions/live-schema";
+import type { BUN_MARIADB_FieldSchemaType, BunMariaDBConfig } from "../types";
 import getSanitizeHtmlOptions from "./sanitize-html-options";
-
-function grabTableFields(tableName: string): BUN_MARIADB_FieldSchemaType[] {
-    const dbSchema: BUN_MARIADB_DatabaseSchemaType | undefined =
-        global.DB_SCHEMA || readLiveSchema();
-
-    const tableSchema = dbSchema?.tables?.find((t) => t.tableName === tableName);
-
-    return tableSchema?.fields || [];
-}
+import grabTableFields from "./grab-table-fields";

 /**
 * Only fields with an explicit `html: true` flag are sanitized.
@@ -122,6 +122,11 @@ export default function sqlGenOperatorGen({
                str: `${fieldName} IS NOT ${finalValue}`,
                param: finalParams,
            };
+        } else if (equality == "IN" || equality == "NOT IN") {
+            return {
+                str: `${fieldName} ${equality} (${finalValue})`,
+                param: finalParams,
+            };
        } else if (equality) {
            return {
                str: `${fieldName} ${sqlEqualityParser(
@@ -67,7 +67,39 @@ export default function sqlGenGenSearchStr({
        });
    }

-    if (Array.isArray(queryObj.value)) {
+    const listEquality =
+        queryObj.equality == "IN" || queryObj.equality == "NOT IN"
+            ? queryObj.equality
+            : undefined;
+
+    if (
+        listEquality &&
+        !queryObj.nullValue &&
+        !queryObj.notNullValue &&
+        queryObj.value !== undefined &&
+        queryObj.value !== null
+    ) {
+        const rawValues = Array.isArray(queryObj.value)
+            ? queryObj.value
+            : [queryObj.value];
+
+        const listValues = rawValues
+            .map((val) =>
+                val !== null && typeof val == "object" ? val.value : val,
+            )
+            .filter(
+                (val): val is string | number =>
+                    val !== undefined && val !== null,
+            );
+
+        if (listValues.length === 0) {
+            // Empty IN () is invalid SQL: IN matches nothing, NOT IN matches everything
+            str = listEquality == "IN" ? "1 = 0" : "1 = 1";
+        } else {
+            str = `${finalFieldName} ${listEquality} (${listValues.map(() => "?").join(",")})`;
+            sqlSearhValues.push(...listValues);
+        }
+    } else if (Array.isArray(queryObj.value)) {
        const strArray: string[] = [];

        queryObj.value.forEach((val) => {
@@ -20,6 +20,11 @@ type Param<T extends { [key: string]: any } = { [key: string]: any }> = {
    tableName: string;
    dbFullName?: string;
    count?: boolean;
+    /**
+     * Restrict to a single row id. Always combined with AND, regardless of
+     * `searchOperator`.
+     */
+    targetId?: number | string;
 };

 type Return = {
@@ -40,7 +45,13 @@ const MAX_LIMIT = "18446744073709551615";
 */
 export default function sqlGenerator<
    T extends { [key: string]: any } = { [key: string]: any },
->({ tableName: rawTableName, genObject, dbFullName, count }: Param<T>): Return {
+>({
+    tableName: rawTableName,
+    genObject,
+    dbFullName,
+    count,
+    targetId,
+}: Param<T>): Return {
    const tableName = quoteQualified(rawTableName);

    const finalQuery = genObject?.query ? genObject.query : undefined;
@@ -130,18 +141,35 @@ export default function sqlGenerator<
    const isSearchStr =
        cleanedUpSearchStr?.[0] && cleanedUpSearchStr.find((str) => str);

-    let where = ``;
+    const whereConditions: string[] = [];

    if (isSearchStr) {
        const stringOperator = sqlLogicalOperator(genObject?.searchOperator);
-        where += `WHERE ${cleanedUpSearchStr.join(` ${stringOperator} `)}`;
+        whereConditions.push(
+            `(${cleanedUpSearchStr.join(` ${stringOperator} `)})`,
+        );
    }

    if (genObject?.fullTextSearch && fullTextSearchStr && fullTextMatchStr) {
-        where += `${isSearchStr ? " AND" : "WHERE"} ${fullTextMatchStr}`;
+        whereConditions.push(fullTextMatchStr.trim());
        whereValues.push(fullTextSearchStr);
    }

+    if (targetId !== undefined && targetId !== null && targetId !== "") {
+        const id = Number(targetId);
+        if (!Number.isFinite(id)) {
+            throw new Error(`Invalid targetId: ${String(targetId)}`);
+        }
+        whereConditions.push(
+            `${columnRef("id", genObject?.join ? tableName : undefined)} = ?`,
+        );
+        whereValues.push(id);
+    }
+
+    const where = whereConditions.length
+        ? `WHERE ${whereConditions.join(" AND ")}`
+        : ``;
+
    if (where) {
        queryString += ` ${where}`;
    }
@@ -226,179 +254,3 @@ export default function sqlGenerator<
        whereValues,
    };
 }
-
-// let queryString = (() => {
-//     let str = "SELECT";
-
-//     if (genObject?.select_sql) {
-//         str += ` ${genObject.select_sql}`;
-//     } else if (genObject?.selectFields?.[0]) {
-//         if (genObject.join) {
-//             str += sqlGenGrabSelectFieldSQL<T>({
-//                 selectFields: genObject.selectFields,
-//                 append_table_names: true,
-//                 table_name: tableName,
-//             });
-//         } else {
-//             str += sqlGenGrabSelectFieldSQL({
-//                 selectFields: genObject.selectFields,
-//                 table_name: tableName,
-//             });
-//         }
-//     } else {
-//         if (genObject?.join) {
-//             str += ` ${tableName}.*`;
-//         } else {
-//             str += " *";
-//         }
-//     }
-
-//     if (genObject?.countSubQueries) {
-//         let countSqls: string[] = [];
-
-//         for (let i = 0; i < genObject.countSubQueries.length; i++) {
-//             const countSubQuery = genObject.countSubQueries[i];
-//             if (!countSubQuery) continue;
-
-//             const tableAlias = countSubQuery.table_alias;
-
-//             let subQStr = `(SELECT COUNT(*)`;
-
-//             subQStr += ` FROM ${countSubQuery.table}${
-//                 tableAlias ? ` ${tableAlias}` : ""
-//             }`;
-
-//             subQStr += ` WHERE (`;
-
-//             for (let j = 0; j < countSubQuery.srcTrgMap.length; j++) {
-//                 const csqSrc = countSubQuery.srcTrgMap[j];
-//                 if (!csqSrc) continue;
-
-//                 subQStr += ` ${tableAlias || countSubQuery.table}.${
-//                     csqSrc.src
-//                 }`;
-
-//                 if (typeof csqSrc.trg == "string") {
-//                     subQStr += ` = ?`;
-//                     sqlSearhValues.push(csqSrc.trg);
-//                 } else if (typeof csqSrc.trg == "object") {
-//                     subQStr += ` = ${csqSrc.trg.table}.${csqSrc.trg.field}`;
-//                 }
-
-//                 if (j < countSubQuery.srcTrgMap.length - 1) {
-//                     subQStr += ` AND `;
-//                 }
-//             }
-
-//             subQStr += ` )) AS ${countSubQuery.alias}`;
-//             countSqls.push(subQStr);
-//         }
-
-//         str += `, ${countSqls.join(",")}`;
-//     }
-
-//     if (genObject?.join) {
-//         const existingJoinTableNames: string[] = [tableName];
-
-//         str +=
-//             "," +
-//             genObject.join
-//                 .flat()
-//                 .filter((j) => !isUndefined(j))
-//                 .map((joinObj) => {
-//                     const joinTableName = joinObj.alias
-//                         ? joinObj.alias
-//                         : joinObj.tableName;
-
-//                     if (existingJoinTableNames.includes(joinTableName))
-//                         return null;
-//                     existingJoinTableNames.push(joinTableName);
-
-//                     if (joinObj.group_concat) {
-//                         return sqlGenGrabConcatStr({
-//                             field: `${joinTableName}.${joinObj.group_concat.field}`,
-//                             alias: joinObj.group_concat.alias,
-//                             separator: joinObj.group_concat.separator,
-//                         });
-//                     } else if (joinObj.selectFields) {
-//                         return joinObj.selectFields
-//                             .map((selectField) => {
-//                                 if (typeof selectField == "string") {
-//                                     return `${joinTableName}.${selectField}`;
-//                                 } else if (typeof selectField == "object") {
-//                                     let aliasSelectField = selectField.count
-//                                         ? `COUNT(${joinTableName}.${selectField.field})`
-//                                         : `${joinTableName}.${selectField.field}`;
-//                                     if (selectField.alias)
-//                                         aliasSelectField += ` AS ${selectField.alias}`;
-//                                     return aliasSelectField;
-//                                 }
-//                             })
-//                             .join(",");
-//                     } else {
-//                         return `${joinTableName}.*`;
-//                     }
-//                 })
-//                 .filter((_) => Boolean(_))
-//                 .join(",");
-//     }
-
-//     if (
-//         genObject?.fullTextSearch &&
-//         fullTextMatchStr &&
-//         fullTextSearchStr
-//     ) {
-//         str += `, ${fullTextMatchStr} AS ${genObject.fullTextSearch.scoreAlias}`;
-//         sqlSearhValues.push(fullTextSearchStr);
-//     }
-
-//     str += ` FROM ${tableName}`;
-
-//     if (genObject?.join) {
-//         str +=
-//             " " +
-//             genObject.join
-//                 .flat()
-//                 .filter((j) => !isUndefined(j))
-//                 .map((join) => {
-//                     return (
-//                         join.joinType +
-//                         " " +
-//                         (join.alias
-//                             ? `${join.tableName}` + " " + join.alias
-//                             : `${join.tableName}`) +
-//                         " ON " +
-//                         (() => {
-//                             if (Array.isArray(join.match)) {
-//                                 return (
-//                                     "(" +
-//                                     join.match
-//                                         .map((mtch) =>
-//                                             sqlGenGenJoinStr({
-//                                                 mtch,
-//                                                 join,
-//                                                 table_name: tableName,
-//                                             }),
-//                                         )
-//                                         .join(
-//                                             join.operator
-//                                                 ? ` ${join.operator} `
-//                                                 : " AND ",
-//                                         ) +
-//                                     ")"
-//                                 );
-//                             } else if (typeof join.match == "object") {
-//                                 return sqlGenGenJoinStr({
-//                                     mtch: join.match,
-//                                     join,
-//                                     table_name: tableName,
-//                                 });
-//                             }
-//                         })()
-//                     );
-//                 })
-//                 .join(" ");
-//     }
-
-//     return str;
-// })();
@@ -4,6 +4,8 @@ import type {
    SQLInsertGenValueType,
 } from "../types";
 import { quoteIdentifier } from "./sql-identifier";
+import sqlValuePlaceholder from "./sql-value-placeholder";
+import grabTableFields from "./grab-table-fields";

 /**
 * # SQL Insert Generator
@@ -28,6 +30,10 @@ export default function sqlInsertGenerator({
                });
            });

+            const fieldsMap = new Map(
+                grabTableFields(tableName).map((f) => [f.fieldName, f]),
+            );
+
            let queryBatches: string[] = [];
            let queryValues: SQLInsertGenValueType[] = [];

@@ -35,41 +41,12 @@ export default function sqlInsertGenerator({
                queryBatches.push(
                    `(${insertKeys
                        .map((ky) => {
-                            const value = item[ky];
-
-                            if (typeof value == "function") {
-                                const fnValue = value();
-                                queryValues.push(fnValue.value ?? null);
-                                return fnValue.placeholder || "?";
-                            }
-
-                            if (typeof value == "boolean") {
-                                queryValues.push(value ? 1 : 0);
-                                return "?";
-                            }
-
-                            if (typeof value == "number") {
-                                queryValues.push(value);
-                                return "?";
-                            }
-
-                            // Empty strings / null / undefined are stored as NULL
-                            if (value === undefined || value === null || value === "") {
-                                queryValues.push(null);
-                                return "?";
-                            }
-
-                            const is_embedding =
-                                Array.isArray(value) &&
-                                typeof value[0] == "number";
-
-                            if (is_embedding) {
-                                queryValues.push(JSON.stringify(value));
-                                return "VEC_FromText(?)";
-                            }
-
+                            const { placeholder, value } = sqlValuePlaceholder({
+                                value: item[ky],
+                                field: fieldsMap.get(ky),
+                            });
                            queryValues.push(value);
-                            return "?";
+                            return placeholder;
                        })
                        .join(",")})`,
                );
@@ -0,0 +1,57 @@
+import type {
+    BUN_MARIADB_FieldSchemaType,
+    SQLInsertGenValueType,
+} from "../types";
+
+type Return = {
+    placeholder: string;
+    value: SQLInsertGenValueType;
+};
+
+function isTextField(field?: BUN_MARIADB_FieldSchemaType): boolean {
+    if (!field || field.isVector) return false;
+    return /char|text|enum|set|json/i.test(String(field.dataType || ""));
+}
+
+/**
+ * Map a JS value to a bound parameter + placeholder for INSERT / UPDATE.
+ *
+ * - `false` / `true` -> `0` / `1`
+ * - number arrays (embeddings) -> `VEC_FromText(?)` with a JSON string
+ * - `{ value, placeholder }` factories are called once
+ * - `""` stays `""` for text columns and becomes `NULL` for everything else
+ *   (e.g. the `number | ""` typedefs for numeric columns)
+ */
+export default function sqlValuePlaceholder({
+    value,
+    field,
+}: {
+    value: any;
+    field?: BUN_MARIADB_FieldSchemaType;
+}): Return {
+    if (typeof value == "function") {
+        const fnValue = value();
+        return {
+            placeholder: fnValue?.placeholder || "?",
+            value: fnValue?.value ?? null,
+        };
+    }
+
+    if (typeof value == "boolean") {
+        return { placeholder: "?", value: value ? 1 : 0 };
+    }
+
+    if (value === undefined || value === null) {
+        return { placeholder: "?", value: null };
+    }
+
+    if (value === "") {
+        return { placeholder: "?", value: isTextField(field) ? "" : null };
+    }
+
+    if (Array.isArray(value) && typeof value[0] == "number") {
+        return { placeholder: "VEC_FromText(?)", value: JSON.stringify(value) };
+    }
+
+    return { placeholder: "?", value };
+}