@iskra-bun/db-kit 0.2.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,4 +1,4 @@
-import { type App, type Driver, type AppConfig, DriverError } from '@iskra-bun/core';
+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';
@@ -6,8 +6,9 @@ import type { LibSQLDatabase } from 'drizzle-orm/libsql';
 import postgres from 'postgres';
 import mysql from 'mysql2/promise';
 import { sql } from 'drizzle-orm';
-import { ConnectionError, QueryError } from './errors';
-import { MigrationHelper, mapDialect } from './migrations';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ConnectionError, MigrationError, QueryError } from './errors';
+import { SENSITIVE_URL_PARAM } from './secrets';
 
 /**
  * Observability callback invoked for every SQL statement Drizzle executes.
@@ -21,8 +22,7 @@ export type OnQueryHook = (query: string, params: unknown[]) => void;
  * 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>;
+export type IskraDrizzleTx<TSchema extends Record<string, unknown> = Record<string, never>> = IskraDrizzleDb<TSchema>;
 
 /**
  * The Drizzle database handle exposed by {@link DbDriver}, parameterized by the
@@ -39,16 +39,21 @@ export type IskraDrizzleDb<TSchema extends Record<string, unknown> = Record<stri
     | LibSQLDatabase<TSchema>;
 
 /**
- * Redact username and password from a database URL so it is safe to log.
+ * 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;
@@ -68,6 +73,9 @@ interface DbClient {
 export class DbDriver<TSchema extends Record<string, unknown> = Record<string, never>> implements Driver {
     name = 'db';
     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;
@@ -129,12 +137,14 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
                 case 'mysql': {
                     const client = mysql.createPool(config.url);
                     this.client = client;
-                    this.db = drizzleMysql<TSchema>(client, { logger });
+                    // 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");
+                    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 });
@@ -154,9 +164,13 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
                         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', {
@@ -170,27 +184,52 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
     }
 
     /**
-     * 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,
-        );
-
-        await helper.migrate();
+        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 },
+            });
+        }
     }
 
     /**
@@ -198,7 +237,11 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
      * `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} (Drizzle rolls back on throw).
+     * 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) {
@@ -207,12 +250,15 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
             });
         }
         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));
+            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', {
@@ -222,6 +268,39 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
         }
     }
 
+    /**
+     * 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;
+    }
+
     /**
      * Liveness probe for readiness checks (e.g. web-kit's addReadinessCheck /
      * k8s readiness). Runs a trivial `SELECT 1` against the active dialect and
@@ -230,25 +309,30 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
     async ping(): Promise<boolean> {
         if (!this.db) return false;
         try {
-            // 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 {
-                return false;
-            }
+            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() {
         const client = this.client;
         try {
@@ -271,3 +355,10 @@ export class DbDriver<TSchema extends Record<string, unknown> = Record<string, n
         }
     }
 }
+
+// `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,16 +1,48 @@
 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';
 
 /**
- * Redacta credenciales `//user:pass@host` embebidas 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.
+ * 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:@]+:[^/\s@]+@/g, '$1***:***@');
+    return text
+        .replace(/(\/\/)(?:[^\s'"`@]*@)+/g, '$1***:***@')
+        .replace(
+            new RegExp(`([?&][^=\\s&'"\`]*(?:${SENSITIVE_URL_PARAM.source})[^=\\s&'"\`]*=)[^&\\s'"\`]*`, 'gi'),
+            '$1***',
+        );
 }
 
 export interface MigrationConfig {
@@ -28,7 +60,8 @@ export interface MigrationConfig {
 
 /**
  * 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;
@@ -45,7 +78,7 @@ export class MigrationHelper {
      * 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);
@@ -59,7 +92,7 @@ export class MigrationHelper {
      * comando, por eso únicamente reenviamos configPath cuando está presente.
      */
     async migrate(): Promise<void> {
-        const args = ['drizzle-kit', 'migrate'];
+        const args = ['migrate'];
         if (this.config.configPath) args.push('--config', this.config.configPath);
         await this.exec(args, 'migrate');
     }
@@ -69,18 +102,19 @@ export class MigrationHelper {
      * Útil para desarrollo rápido. `push` acepta --schema pero no --out.
      */
     async push(): Promise<void> {
-        const args = ['drizzle-kit', '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> {
-        const args = ['drizzle-kit', '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');
@@ -88,15 +122,18 @@ export class MigrationHelper {
 
     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',

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;