@iskra-bun/db-kit 0.1.0 → 0.3.0

package/src/cli.ts

@@ -11,6 +11,8 @@
  * Requiere un archivo drizzle.config.ts en el directorio actual.
  */
 
+import { drizzleKitCommand } from './migrations';
+
 const [command, ...rest] = process.argv.slice(2);
 
 const validCommands = ['generate', 'migrate', 'push', 'drop'];
@@ -26,12 +28,19 @@ Comandos:
   generate [nombre]  Genera archivos de migración a partir del schema
   migrate            Aplica migraciones pendientes
   push               Empuja el schema directo a la DB (sin migración)
-  drop               Elimina todas las tablas
+  drop               Elimina un archivo de migracion generado (no toca la DB)
 `);
     process.exit(command ? 1 : 0);
 }
 
-const args = ['bunx', 'drizzle-kit', command, ...rest];
+// The project's own drizzle-kit, never one bunx downloads (see drizzleKitCommand).
+let args: string[];
+try {
+    args = drizzleKitCommand([command, ...rest]);
+} catch (error) {
+    console.error((error as Error).message);
+    process.exit(1);
+}
 
 console.log(`> ${args.join(' ')}`);
 

package/src/driver.ts

@@ -1,17 +1,113 @@
-import { type App, type Driver, type AppConfig, DriverError } from '@iskra-bun/core';
-import { drizzle } from 'drizzle-orm/postgres-js';
-import { drizzle as drizzleMysql } from 'drizzle-orm/mysql2';
+import { type App, type Driver, DriverError } from '@iskra-bun/core';
+import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { drizzle as drizzleMysql, type MySql2Database } from 'drizzle-orm/mysql2';
+import type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import type { LibSQLDatabase } from 'drizzle-orm/libsql';
 import postgres from 'postgres';
 import mysql from 'mysql2/promise';
-import { ConnectionError } from './errors';
-import { MigrationHelper, mapDialect } from './migrations';
+import { sql } from 'drizzle-orm';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ConnectionError, MigrationError, QueryError } from './errors';
+import { SENSITIVE_URL_PARAM } from './secrets';
 
-export class DbDriver implements Driver {
+/**
+ * Observability callback invoked for every SQL statement Drizzle executes.
+ * Receives the rendered query and its bound parameters.
+ */
+export type OnQueryHook = (query: string, params: unknown[]) => void;
+
+/**
+ * The transaction handle passed to {@link DbDriver.transaction}. Drizzle types
+ * the transaction object per dialect, so — like {@link IskraDrizzleDb} — this is
+ * the union of the supported dialect databases for the same schema. Callers can
+ * narrow by dialect if they need dialect-specific transaction APIs.
+ */
+export type IskraDrizzleTx<TSchema extends Record<string, unknown> = Record<string, never>> = IskraDrizzleDb<TSchema>;
+
+/**
+ * The Drizzle database handle exposed by {@link DbDriver}, parameterized by the
+ * caller's schema. Because the concrete dialect is chosen at runtime, this is a
+ * union of the supported dialect databases — all four share the same
+ * `TSchema extends Record<string, unknown> = Record<string, never>` parameter,
+ * so passing a schema types `db.query.*` for opt-in callers while the default
+ * `Record<string, never>` reproduces the historical untyped behavior.
+ */
+export type IskraDrizzleDb<TSchema extends Record<string, unknown> = Record<string, never>> =
+    | PostgresJsDatabase<TSchema>
+    | MySql2Database<TSchema>
+    | BunSQLiteDatabase<TSchema>
+    | LibSQLDatabase<TSchema>;
+
+/**
+ * Redact the username, password and secret query parameters (`authToken`,
+ * `password`, `sslpassword`...) from a database URL so it is safe to log.
+ * Returns the scrubbed URL string, or undefined if parsing fails.
+ *
+ * e.g. postgres://user:pass@host:5432/db → postgres://***:***@host:5432/db
+ *      libsql://db.turso.io?authToken=eyJ… → libsql://db.turso.io?authToken=***
+ */
+export function scrubUrl(url: string): string | undefined {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username) parsed.username = '***';
+        if (parsed.password) parsed.password = '***';
+        for (const key of [...new Set(parsed.searchParams.keys())]) {
+            if (SENSITIVE_URL_PARAM.test(key)) parsed.searchParams.set(key, '***');
+        }
+        return parsed.toString();
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * The minimal teardown surface {@link DbDriver.stop} probes on the underlying
+ * client. postgres-js and mysql2 expose async `end()`; bun:sqlite and libsql
+ * expose synchronous `close()`. Typed as optional so either shape satisfies it.
+ */
+interface DbClient {
+    end?(): Promise<void>;
+    close?(): void;
+}
+
+export class DbDriver<TSchema extends Record<string, unknown> = Record<string, never>> implements Driver {
     name = 'db';
-    private client: any;
-    public db: any;
+    private client: DbClient | undefined;
+    /** Serializes transactions on the single bun:sqlite connection. */
+    private sqliteTxQueue: Promise<unknown> = Promise.resolve();
+    private readonly inSqliteTx = new AsyncLocalStorage<true>();
+    public db: IskraDrizzleDb<TSchema> | undefined;
 
     private app: App | undefined;
+    private onQuery: OnQueryHook | undefined;
+
+    /**
+     * Register an observability callback that receives every SQL statement (and
+     * its bound params) Drizzle executes. Must be called before {@link start},
+     * since Drizzle's logger is wired at connection time. A throwing callback is
+     * swallowed so observability never breaks a real query.
+     */
+    setOnQuery(onQuery: OnQueryHook): void {
+        this.onQuery = onQuery;
+    }
+
+    /**
+     * Build the Drizzle `logger` option that forwards to {@link onQuery} when a
+     * hook is registered, or `undefined` to leave Drizzle's default logging off.
+     */
+    private buildLogger(): { logQuery(query: string, params: unknown[]): void } | undefined {
+        const hook = this.onQuery;
+        if (!hook) return undefined;
+        return {
+            logQuery: (query: string, params: unknown[]) => {
+                try {
+                    hook(query, params);
+                } catch {
+                    // Observability must never break the underlying query.
+                }
+            },
+        };
+    }
 
     async init(app: App) {
         this.app = app;
@@ -28,28 +124,38 @@ export class DbDriver implements Driver {
 
         this.app!.logger.info(`Initializing DB driver: ${config.driver}`);
 
+        const logger = this.buildLogger();
+
         try {
             switch (config.driver) {
-                case 'postgres':
-                    this.client = postgres(config.url);
-                    this.db = drizzle(this.client);
+                case 'postgres': {
+                    const client = postgres(config.url);
+                    this.client = client;
+                    this.db = drizzle<TSchema>(client, { logger });
                     break;
-                case 'mysql':
-                    this.client = await mysql.createConnection(config.url);
-                    this.db = drizzleMysql(this.client);
+                }
+                case 'mysql': {
+                    const client = mysql.createPool(config.url);
+                    this.client = client;
+                    // Name the client type: with only TSchema given, drizzle's
+                    // TClient defaults to mysql2's callback Pool, not this promise Pool.
+                    this.db = drizzleMysql<TSchema, typeof client>(client, { logger });
                     break;
+                }
                 case 'sqlite': {
-                    const { Database } = await import("bun:sqlite");
-                    const { drizzle: drizzleSqlite } = await import("drizzle-orm/bun-sqlite");
-                    this.client = new Database(config.url);
-                    this.db = drizzleSqlite(this.client);
+                    const { Database } = await import('bun:sqlite');
+                    const { drizzle: drizzleSqlite } = await import('drizzle-orm/bun-sqlite');
+                    const client = new Database(config.url);
+                    this.client = client;
+                    this.db = drizzleSqlite<TSchema>(client, { logger });
                     break;
                 }
                 case 'libsql': {
                     const { createClient } = await import('@libsql/client');
                     const { drizzle: drizzleLibsql } = await import('drizzle-orm/libsql');
-                    this.client = createClient({ url: config.url, authToken: config.authToken });
-                    this.db = drizzleLibsql(this.client);
+                    const client = createClient({ url: config.url, authToken: config.authToken });
+                    this.client = client;
+                    this.db = drizzleLibsql<TSchema>(client, { logger });
                     break;
                 }
                 default:
@@ -58,51 +164,201 @@ export class DbDriver implements Driver {
                         context: { driver: config.driver },
                     });
             }
+            // postgres-js and mysql2 pools connect lazily: without a round-trip
+            // a wrong host or password only surfaced on the first query.
+            await this.roundTrip();
             this.app!.logger.info('DB connected successfully.');
         } catch (error) {
             if (error instanceof DriverError) throw error;
+            await this.stop();
             this.app!.logger.error({ error }, 'Failed to connect to DB');
+            const safeUrl = scrubUrl(config.url);
             throw new ConnectionError('Failed to connect to DB', {
                 cause: error instanceof Error ? error : new Error(String(error)),
-                context: { driver: config.driver, url: config.url },
+                context: {
+                    driver: config.driver,
+                    ...(safeUrl !== undefined ? { url: safeUrl } : {}),
+                },
             });
         }
     }
 
     /**
-     * Ejecuta migraciones pendientes usando Drizzle Kit.
+     * Applies the pending migrations in `migrationsDir` (generated with
+     * `drizzle-kit generate`) over the live connection, using Drizzle's
+     * migrator for the configured dialect. Requires `start()`.
+     *
+     * It used to shell out to `drizzle-kit migrate`, which ignored both
+     * arguments and failed without a drizzle.config.ts. `schemaPath` is kept for
+     * compatibility; applying migrations does not need the schema.
      */
-    async runMigrations(schemaPath: string, migrationsDir: string = './drizzle'): Promise<void> {
-        if (!this.app?.config.db) {
+    async runMigrations(_schemaPath?: string, migrationsDir: string = './drizzle'): Promise<void> {
+        const config = this.app?.config.db;
+        if (!config) {
             throw new DriverError('Cannot run migrations: no DB configuration found', {
                 code: 'DRIVER_START_FAILED',
             });
         }
+        if (!this.db) {
+            throw new DriverError('Cannot run migrations: DB is not started', {
+                code: 'DRIVER_START_FAILED',
+                context: { driver: config.driver },
+            });
+        }
 
-        const config = this.app.config.db;
-        const helper = new MigrationHelper(
-            {
-                dialect: mapDialect(config.driver),
-                dbUrl: config.url,
-                schemaPath,
-                migrationsDir,
-            },
-            this.app,
-        );
+        const options = { migrationsFolder: migrationsDir };
+        const db = this.db as never;
+        try {
+            switch (config.driver) {
+                case 'postgres':
+                    await (await import('drizzle-orm/postgres-js/migrator')).migrate(db, options);
+                    break;
+                case 'mysql':
+                    await (await import('drizzle-orm/mysql2/migrator')).migrate(db, options);
+                    break;
+                case 'sqlite':
+                    (await import('drizzle-orm/bun-sqlite/migrator')).migrate(db, options);
+                    break;
+                case 'libsql':
+                    await (await import('drizzle-orm/libsql/migrator')).migrate(db, options);
+                    break;
+            }
+            this.app!.logger.info({ migrationsDir }, 'Migrations applied');
+        } catch (error) {
+            throw new MigrationError('Failed to apply migrations', {
+                cause: error instanceof Error ? error : new Error(String(error)),
+                context: { driver: config.driver, migrationsDir },
+            });
+        }
+    }
+
+    /**
+     * Run `fn` inside a database transaction, delegating to Drizzle's
+     * `db.transaction`. Callers receive the transaction-scoped db handle instead
+     * of reaching into the raw `db`. The dialect union means `tx` is typed as
+     * {@link IskraDrizzleTx}; narrow by dialect if you need dialect-specific APIs.
+     * Failures are wrapped in {@link QueryError}; the transaction is rolled back.
+     *
+     * With `sqlite`, transactions run one at a time on the single connection,
+     * and a query made outside `tx` while one is open is part of it. A nested
+     * `transaction()` call is rejected: it would wait for itself.
+     */
+    async transaction<R>(fn: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R> {
+        if (!this.db) {
+            throw new QueryError('Cannot run transaction: DB is not started', {
+                context: { driver: this.app?.config.db?.driver },
+            });
+        }
+        try {
+            if (this.app?.config.db?.driver === 'sqlite') return await this.sqliteTransaction(fn);
+            // The dialect-specific `transaction` overloads do not unify across the
+            // union, so we route through the runtime method with a faithful cast
+            // of the public handle types.
+            return await (
+                this.db as IskraDrizzleDb<TSchema> & {
+                    transaction(cb: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R>;
+                }
+            ).transaction((tx) => fn(tx));
+        } catch (error) {
+            if (error instanceof QueryError) throw error;
+            throw new QueryError('Transaction failed', {
+                cause: error instanceof Error ? error : new Error(String(error)),
+                context: { driver: this.app?.config.db?.driver },
+            });
+        }
+    }
+
+    /**
+     * Drizzle's bun-sqlite `transaction()` is synchronous: it commits as soon
+     * as the callback returns its promise, so an async callback that threw
+     * afterwards never rolled back. The transaction is opened and closed here
+     * around the awaited callback instead.
+     */
+    private async sqliteTransaction<R>(fn: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R> {
+        if (this.inSqliteTx.getStore()) {
+            throw new QueryError('Nested transaction() calls are not supported with sqlite', {
+                context: { driver: 'sqlite' },
+            });
+        }
+        const db = this.db as BunSQLiteDatabase<TSchema>;
+        const run = () =>
+            this.inSqliteTx.run(true, async () => {
+                // A transaction handle (tx.rollback(), tx.query.*) bound to the
+                // connection; the empty native transaction it comes from is done.
+                const tx = db.transaction((t) => t);
+                db.run(sql`begin`);
+                try {
+                    const result = await fn(tx as unknown as IskraDrizzleTx<TSchema>);
+                    db.run(sql`commit`);
+                    return result;
+                } catch (error) {
+                    db.run(sql`rollback`);
+                    throw error;
+                }
+            });
+        const result = this.sqliteTxQueue.then(run, run);
+        this.sqliteTxQueue = result.catch(() => undefined);
+        return result;
+    }
 
-        await helper.migrate();
+    /**
+     * Liveness probe for readiness checks (e.g. web-kit's addReadinessCheck /
+     * k8s readiness). Runs a trivial `SELECT 1` against the active dialect and
+     * resolves `true` on success or `false` on any failure — it never rejects.
+     */
+    async ping(): Promise<boolean> {
+        if (!this.db) return false;
+        try {
+            await this.roundTrip();
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** `SELECT 1` on the active connection; throws on failure. */
+    private async roundTrip(): Promise<void> {
+        // bun-sqlite exposes the synchronous `.run()`; postgres-js, mysql2 and
+        // libsql expose the async `.execute()`. Prefer whichever exists.
+        const handle = this.db as {
+            run?(query: unknown): unknown;
+            execute?(query: unknown): Promise<unknown>;
+        };
+        if (typeof handle.run === 'function') {
+            await handle.run(sql`SELECT 1`);
+        } else if (typeof handle.execute === 'function') {
+            await handle.execute(sql`SELECT 1`);
+        } else {
+            throw new Error('DB handle exposes neither run() nor execute()');
+        }
     }
 
     async stop() {
-        if (this.client) {
-            // Close connections based on client type
-            if (this.client.end) { // Postgres usage with postgres.js usually handles itself or has end. 
-                // mysql2 has end()
-                await this.client.end();
-            } else if (this.client.close) { // bun:sqlite / libsql
-                this.client.close();
+        const client = this.client;
+        try {
+            // postgres-js / mysql2 expose async end(); bun:sqlite / libsql expose
+            // synchronous close(). Probe for whichever this client provides.
+            if (client?.end) {
+                await client.end();
+            } else if (client?.close) {
+                client.close();
             }
-            // postgres.js handles cleanup usually but explicit close might be needed depending on version/usage
+        } catch (error) {
+            // A throwing teardown must never abort the orderly shutdown of other
+            // drivers; log and continue so the handles below are still cleared.
+            this.app?.logger.error({ error }, 'Failed to close DB connection cleanly');
+        } finally {
+            // Null the handles so a post-stop ping()/transaction() hits the
+            // not-started guard instead of an already-closed connection.
+            this.client = undefined;
+            this.db = undefined;
         }
     }
 }
+
+// `app.context.get('db')` is the DbDriver registered on the app.
+declare module '@iskra-bun/core' {
+    interface AppContextRegistry {
+        db: DbDriver;
+    }
+}

package/src/drizzle.config.template.ts

@@ -1,5 +1,3 @@
-import { defineConfig } from 'drizzle-kit';
-
 export interface DrizzleConfigOptions {
     /** Dialecto: 'postgresql', 'mysql', 'sqlite' */
     dialect: 'postgresql' | 'mysql' | 'sqlite';
@@ -11,6 +9,19 @@ export interface DrizzleConfigOptions {
     migrationsDir?: string;
 }
 
+/**
+ * La configuración que lee drizzle-kit (el `export default` de `drizzle.config.ts`).
+ * Se declara aquí para no importar drizzle-kit: es una herramienta de desarrollo,
+ * y el entry point de db-kit (que usa Bun vía la condición `bun`) fallaba al
+ * importarse donde no estaba instalada, por ejemplo con `--production`.
+ */
+export interface DrizzleKitConfig {
+    dialect: DrizzleConfigOptions['dialect'];
+    schema: string;
+    out: string;
+    dbCredentials: { url: string };
+}
+
 /**
  * Crea una configuración de drizzle-kit reutilizable.
  *
@@ -26,13 +37,13 @@ export interface DrizzleConfigOptions {
  * });
  * ```
  */
-export function createDrizzleConfig(options: DrizzleConfigOptions) {
-    return defineConfig({
+export function createDrizzleConfig(options: DrizzleConfigOptions): DrizzleKitConfig {
+    return {
         dialect: options.dialect,
         schema: options.schemaPath,
         out: options.migrationsDir || './drizzle',
         dbCredentials: {
             url: options.dbUrl,
         },
-    });
+    };
 }

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { IskraError, ErrorCodes, type ErrorCode } from '@iskra-bun/core';
+import { IskraError, ErrorCodes } from '@iskra-bun/core';
 
 // ─── Connection Error ────────────────────────────────────────────────────────
 

package/src/index.ts

@@ -1,4 +1,4 @@
 export * from './driver';
 export * from './errors';
 export * from './migrations';
-export { createDrizzleConfig, type DrizzleConfigOptions } from './drizzle.config.template';
+export { createDrizzleConfig, type DrizzleConfigOptions, type DrizzleKitConfig } from './drizzle.config.template';

package/src/migrations.ts

@@ -1,5 +1,49 @@
 import { type App } from '@iskra-bun/core';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import { MigrationError } from './errors';
+import { SENSITIVE_URL_PARAM } from './secrets';
+
+/**
+ * The drizzle-kit command to run `args` with, from the project's own install:
+ * `node_modules/.bin` in `cwd` or a parent (workspaces hoist it). drizzle-kit
+ * is a devDependency, and `bunx drizzle-kit` downloaded its latest release
+ * from npm where it was missing (a production install) and ran it with
+ * DATABASE_URL in its environment. `--no-install` keeps bunx from doing so.
+ */
+export function drizzleKitCommand(args: string[], cwd: string = process.cwd()): string[] {
+    for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+        const bin = path.join(dir, 'node_modules', '.bin', 'drizzle-kit');
+        if (['', '.exe', '.cmd'].some((ext) => existsSync(bin + ext))) {
+            return ['bunx', '--no-install', 'drizzle-kit', ...args];
+        }
+        if (path.dirname(dir) === dir) break;
+    }
+    throw new MigrationError(
+        'drizzle-kit is not installed in this project (it is never downloaded at run time): ' +
+            'add it with `bun add -d drizzle-kit`',
+        { context: { cwd } },
+    );
+}
+
+/**
+ * Redacta credenciales `//user:pass@host` y parámetros secretos (`authToken`,
+ * `password`...) embebidos en texto arbitrario (p. ej. el stderr de drizzle-kit,
+ * que suele imprimir la cadena de conexión completa al fallar). A diferencia de
+ * `scrubUrl`, opera sobre texto libre y no requiere que el contenido sea una
+ * URL parseable, dejando intacto el resto del diagnóstico. Una contraseña con
+ * `@` o `/` sin codificar también se redacta: se toma hasta el último `@`.
+ *
+ * e.g. "... postgres://user:pass@host:5432/db" → "... postgres://***:***@host:5432/db"
+ */
+export function scrubCredentials(text: string): string {
+    return text
+        .replace(/(\/\/)(?:[^\s'"`@]*@)+/g, '$1***:***@')
+        .replace(
+            new RegExp(`([?&][^=\\s&'"\`]*(?:${SENSITIVE_URL_PARAM.source})[^=\\s&'"\`]*=)[^&\\s'"\`]*`, 'gi'),
+            '$1***',
+        );
+}
 
 export interface MigrationConfig {
     /** Dialecto de la base de datos */
@@ -10,11 +54,14 @@ export interface MigrationConfig {
     schemaPath: string;
     /** Directorio donde se generan las migraciones (ej: './drizzle') */
     migrationsDir: string;
+    /** Ruta opcional a un drizzle.config.ts; cuando se define se pasa como --config. */
+    configPath?: string;
 }
 
 /**
  * Helper para ejecutar migraciones de Drizzle Kit.
- * Usa `bunx drizzle-kit` como subproceso para generar y aplicar migraciones.
+ * Usa el drizzle-kit instalado en el proyecto (`bunx --no-install drizzle-kit`)
+ * como subproceso para generar y aplicar migraciones; nunca lo descarga.
  */
 export class MigrationHelper {
     private config: MigrationConfig;
@@ -27,46 +74,66 @@ export class MigrationHelper {
 
     /**
      * Genera archivos de migración basados en los cambios del schema.
+     * drizzle-kit generate soporta --schema y --out, así que ambos se reenvían
+     * desde la config (antes se ignoraban silenciosamente).
      */
     async generate(name?: string): Promise<void> {
-        const args = ['drizzle-kit', 'generate'];
+        const args = ['generate'];
+        if (this.config.schemaPath) args.push('--schema', this.config.schemaPath);
+        if (this.config.migrationsDir) args.push('--out', this.config.migrationsDir);
         if (name) args.push('--name', name);
+        if (this.config.configPath) args.push('--config', this.config.configPath);
         await this.exec(args, 'generate');
     }
 
     /**
      * Aplica las migraciones pendientes a la base de datos.
+     * `migrate` sólo acepta --config; schema y out no son flags válidos en este
+     * comando, por eso únicamente reenviamos configPath cuando está presente.
      */
     async migrate(): Promise<void> {
-        await this.exec(['drizzle-kit', 'migrate'], 'migrate');
+        const args = ['migrate'];
+        if (this.config.configPath) args.push('--config', this.config.configPath);
+        await this.exec(args, 'migrate');
     }
 
     /**
      * Empuja el schema directamente a la base de datos (sin generar archivos de migración).
-     * Útil para desarrollo rápido.
+     * Útil para desarrollo rápido. `push` acepta --schema pero no --out.
      */
     async push(): Promise<void> {
-        await this.exec(['drizzle-kit', 'push'], 'push');
+        const args = ['push'];
+        if (this.config.schemaPath) args.push('--schema', this.config.schemaPath);
+        if (this.config.configPath) args.push('--config', this.config.configPath);
+        await this.exec(args, 'push');
     }
 
     /**
-     * Elimina todas las tablas de la base de datos.
+     * Elimina un archivo de migración ya generado (`drizzle-kit drop`, interactivo).
+     * No borra tablas ni datos de la base.
+     * `drop` acepta --out (dónde viven las migraciones) pero no --schema.
      */
     async drop(): Promise<void> {
-        await this.exec(['drizzle-kit', 'drop'], 'drop');
+        const args = ['drop'];
+        if (this.config.migrationsDir) args.push('--out', this.config.migrationsDir);
+        if (this.config.configPath) args.push('--config', this.config.configPath);
+        await this.exec(args, 'drop');
     }
 
     private async exec(args: string[], operation: string): Promise<void> {
         const env: Record<string, string> = {
-            ...process.env as Record<string, string>,
+            ...(process.env as Record<string, string>),
             DATABASE_URL: this.config.dbUrl,
         };
+        const cwd = process.cwd();
+        // Before anything runs with DATABASE_URL: never a downloaded drizzle-kit.
+        const command = drizzleKitCommand(args, cwd);
 
         this.app?.logger.info(`Running migration: ${operation}`);
 
         try {
-            const proc = Bun.spawn(['bunx', ...args], {
-                cwd: process.cwd(),
+            const proc = Bun.spawn(command, {
+                cwd,
                 env,
                 stdout: 'pipe',
                 stderr: 'pipe',
@@ -80,7 +147,7 @@ export class MigrationHelper {
 
             if (exitCode !== 0) {
                 throw new MigrationError(`Migration ${operation} failed with exit code ${exitCode}`, {
-                    context: { operation, exitCode, stderr: stderr.trim() },
+                    context: { operation, exitCode, stderr: scrubCredentials(stderr.trim()) },
                 });
             }
 

package/src/secrets.ts

@@ -0,0 +1,2 @@
+/** Query parameters that carry secrets, such as libsql's `authToken` or `password`. */
+export const SENSITIVE_URL_PARAM = /pass|token|secret|key|auth|credential|signature/i;