npm - @iskra-bun/db-kit - Versions diffs - 0.1.0 → 0.2.0 - Mend

@iskra-bun/db-kit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,26 @@
 # @iskra-bun/db-kit
+## 0.2.0
+### Minor Changes
+- f9654df: New DB features and a migration fix:
+    - **Fix:** `MigrationHelper` now passes `schemaPath`/`migrationsDir` (and an optional `configPath`) to drizzle-kit as `--schema`/`--out`/`--config` flags per command, instead of silently ignoring them when no `drizzle.config.ts` sits in the cwd.
+    - `DbDriver.transaction(fn)` — typed wrapper around Drizzle's transaction so callers don't reach into the raw `db`.
+    - `DbDriver.setOnQuery(cb)` — observability hook wired through Drizzle's logger to surface executed SQL + params.
+    - `DbDriver.ping()` — runs a trivial liveness query and resolves `true`/`false` (never rejects), suitable for readiness probes.
+### Patch Changes
+- f9654df: `DbDriver` and `DbFeature` now accept an optional schema generic (`DbDriver<TSchema>` / `DbFeature<TSchema>`), so `.db` is a typed Drizzle database instead of `any` — opt-in callers get typed relational queries and autocomplete. The generic defaults preserve existing behavior, so no call site needs changes; consumers that relied on `any` may need to add a type argument or annotation.
+- f9654df: Scrub credentials from the URL placed in `ConnectionError` context so passwords no longer leak into structured logs, and scrub `//user:pass@` credentials out of drizzle-kit stderr before storing it in `MigrationError` context. The MySQL driver now uses a connection pool (`createPool`) instead of a single serialized connection — note that `createPool` changes the MySQL lifecycle (pooled connections vs. a single serialized connection), so teardown now drains the pool via `end()`. `DbDriver.stop()` is hardened to swallow a throwing `end()`/`close()` (logging via `app.logger`) and to null the `client`/`db` handles so a post-stop `ping()`/`transaction()` hits the not-started guard instead of an already-closed connection.
+- Scrub `//user:pass@` credentials out of the drizzle-kit stderr captured in `MigrationError.context.stderr`, so connection passwords no longer leak into migration error logs. Non-credential diagnostic text in stderr is preserved.
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
 ## 0.1.0
 ### Minor Changes

package/dist/index.d.ts CHANGED Viewed

@@ -1,17 +1,76 @@
 import { Driver, App, IskraError } from '@iskra-bun/core';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { MySql2Database } from 'drizzle-orm/mysql2';
+import { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import { LibSQLDatabase } from 'drizzle-orm/libsql';
 import * as drizzle_kit from 'drizzle-kit';
-declare class DbDriver implements Driver {
+/**
+ * Observability callback invoked for every SQL statement Drizzle executes.
+ * Receives the rendered query and its bound parameters.
+ */
+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.
+ */
+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.
+ */
+type IskraDrizzleDb<TSchema extends Record<string, unknown> = Record<string, never>> = PostgresJsDatabase<TSchema> | MySql2Database<TSchema> | BunSQLiteDatabase<TSchema> | LibSQLDatabase<TSchema>;
+/**
+ * Redact username and password 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
+ */
+declare function scrubUrl(url: string): string | undefined;
+declare class DbDriver<TSchema extends Record<string, unknown> = Record<string, never>> implements Driver {
     name: string;
     private client;
-    db: any;
+    db: IskraDrizzleDb<TSchema> | undefined;
     private app;
+    private onQuery;
+    /**
+     * 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;
+    /**
+     * 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;
     init(app: App): Promise<void>;
     start(): Promise<void>;
     /**
      * Ejecuta migraciones pendientes usando Drizzle Kit.
      */
     runMigrations(schemaPath: string, migrationsDir?: string): Promise<void>;
+    /**
+     * 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} (Drizzle rolls back on throw).
+     */
+    transaction<R>(fn: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R>;
+    /**
+     * 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.
+     */
+    ping(): Promise<boolean>;
     stop(): Promise<void>;
 }
@@ -34,6 +93,15 @@ declare class MigrationError extends IskraError {
     });
 }
+/**
+ * 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.
+ *
+ * e.g. "... postgres://user:pass@host:5432/db" → "... postgres://***:***@host:5432/db"
+ */
+declare function scrubCredentials(text: string): string;
 interface MigrationConfig {
     /** Dialecto de la base de datos */
     dialect: 'postgresql' | 'mysql' | 'sqlite';
@@ -43,6 +111,8 @@ 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.
@@ -54,19 +124,24 @@ declare class MigrationHelper {
     constructor(config: MigrationConfig, app?: App);
     /**
      * 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).
      */
     generate(name?: string): Promise<void>;
     /**
      * 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.
      */
     migrate(): Promise<void>;
     /**
      * 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.
      */
     push(): Promise<void>;
     /**
      * Elimina todas las tablas de la base de datos.
+     * `drop` acepta --out (dónde viven las migraciones) pero no --schema.
      */
     drop(): Promise<void>;
     private exec;
@@ -103,4 +178,4 @@ interface DrizzleConfigOptions {
  */
 declare function createDrizzleConfig(options: DrizzleConfigOptions): drizzle_kit.Config;
-export { ConnectionError, DbDriver, type DrizzleConfigOptions, type MigrationConfig, MigrationError, MigrationHelper, QueryError, createDrizzleConfig, mapDialect };
+export { ConnectionError, DbDriver, type DrizzleConfigOptions, type IskraDrizzleDb, type IskraDrizzleTx, type MigrationConfig, MigrationError, MigrationHelper, type OnQueryHook, QueryError, createDrizzleConfig, mapDialect, scrubCredentials, scrubUrl };

package/dist/index.js CHANGED Viewed

@@ -4,6 +4,7 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import { drizzle as drizzleMysql } from "drizzle-orm/mysql2";
 import postgres from "postgres";
 import mysql from "mysql2/promise";
+import { sql } from "drizzle-orm";
 // src/errors.ts
 import { IskraError, ErrorCodes } from "@iskra-bun/core";
@@ -27,6 +28,9 @@ var MigrationError = class extends IskraError {
 };
 // src/migrations.ts
+function scrubCredentials(text) {
+  return text.replace(/(\/\/)[^/\s:@]+:[^/\s@]+@/g, "$1***:***@");
+}
 var MigrationHelper = class {
   config;
   app;
@@ -36,30 +40,46 @@ var MigrationHelper = class {
   }
   /**
    * 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) {
     const args = ["drizzle-kit", "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() {
-    await this.exec(["drizzle-kit", "migrate"], "migrate");
+    const args = ["drizzle-kit", "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() {
-    await this.exec(["drizzle-kit", "push"], "push");
+    const args = ["drizzle-kit", "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.
+   * `drop` acepta --out (dónde viven las migraciones) pero no --schema.
    */
   async drop() {
-    await this.exec(["drizzle-kit", "drop"], "drop");
+    const args = ["drizzle-kit", "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");
   }
   async exec(args, operation) {
     const env = {
@@ -80,7 +100,7 @@ var MigrationHelper = class {
       if (stdout) this.app?.logger.info(stdout.trim());
       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()) }
         });
       }
       this.app?.logger.info(`Migration ${operation} completed successfully`);
@@ -110,11 +130,47 @@ function mapDialect(driver) {
 }
 // src/driver.ts
+function scrubUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.username) parsed.username = "***";
+    if (parsed.password) parsed.password = "***";
+    return parsed.toString();
+  } catch {
+    return void 0;
+  }
+}
 var DbDriver = class {
   name = "db";
   client;
   db;
   app;
+  onQuery;
+  /**
+   * 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) {
+    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.
+   */
+  buildLogger() {
+    const hook = this.onQuery;
+    if (!hook) return void 0;
+    return {
+      logQuery: (query, params) => {
+        try {
+          hook(query, params);
+        } catch {
+        }
+      }
+    };
+  }
   async init(app) {
     this.app = app;
     app.context.set("db", this);
@@ -127,28 +183,35 @@ var DbDriver = class {
       return;
     }
     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(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;
+          this.db = drizzleMysql(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 client = new Database(config.url);
+          this.client = client;
+          this.db = drizzleSqlite(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(client, { logger });
           break;
         }
         default:
@@ -161,9 +224,13 @@ var DbDriver = class {
     } catch (error) {
       if (error instanceof DriverError) throw error;
       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 !== void 0 ? { url: safeUrl } : {}
+        }
       });
     }
   }
@@ -188,13 +255,63 @@ var DbDriver = class {
     );
     await helper.migrate();
   }
+  /**
+   * 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} (Drizzle rolls back on throw).
+   */
+  async transaction(fn) {
+    if (!this.db) {
+      throw new QueryError("Cannot run transaction: DB is not started", {
+        context: { driver: this.app?.config.db?.driver }
+      });
+    }
+    try {
+      return await this.db.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 }
+      });
+    }
+  }
+  /**
+   * 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() {
+    if (!this.db) return false;
+    try {
+      const handle = this.db;
+      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;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
   async stop() {
-    if (this.client) {
-      if (this.client.end) {
-        await this.client.end();
-      } else if (this.client.close) {
-        this.client.close();
+    const client = this.client;
+    try {
+      if (client?.end) {
+        await client.end();
+      } else if (client?.close) {
+        client.close();
       }
+    } catch (error) {
+      this.app?.logger.error({ error }, "Failed to close DB connection cleanly");
+    } finally {
+      this.client = void 0;
+      this.db = void 0;
     }
   }
 };
@@ -222,6 +339,8 @@ export {
   MigrationHelper,
   QueryError,
   createDrizzleConfig,
-  mapDialect
+  mapDialect,
+  scrubCredentials,
+  scrubUrl
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/driver.ts","../src/errors.ts","../src/migrations.ts","../../../node_modules/drizzle-kit/index.mjs","../src/drizzle.config.template.ts"],"sourcesContent":["import { type App, type Driver, type AppConfig, DriverError } from '@iskra-bun/core';\nimport { drizzle } from 'drizzle-orm/postgres-js';\nimport { drizzle as drizzleMysql } from 'drizzle-orm/mysql2';\nimport postgres from 'postgres';\nimport mysql from 'mysql2/promise';\nimport { ConnectionError } from './errors';\nimport { MigrationHelper, mapDialect } from './migrations';\n\nexport class DbDriver implements Driver {\n name = 'db';\n private client: any;\n public db: any;\n\n private app: App \| undefined;\n\n async init(app: App) {\n this.app = app;\n app.context.set('db', this);\n }\n\n async start() {\n if (!this.app) return;\n const config = this.app.config.db;\n if (!config) {\n this.app!.logger.warn('No DB configuration found. Skipping DB initialization.');\n return;\n }\n\n this.app!.logger.info(`Initializing DB driver: ${config.driver}`);\n\n try {\n switch (config.driver) {\n case 'postgres':\n this.client = postgres(config.url);\n this.db = drizzle(this.client);\n break;\n case 'mysql':\n this.client = await mysql.createConnection(config.url);\n this.db = drizzleMysql(this.client);\n break;\n case 'sqlite': {\n const { Database } = await import(\"bun:sqlite\");\n const { drizzle: drizzleSqlite } = await import(\"drizzle-orm/bun-sqlite\");\n this.client = new Database(config.url);\n this.db = drizzleSqlite(this.client);\n break;\n }\n case 'libsql': {\n const { createClient } = await import('@libsql/client');\n const { drizzle: drizzleLibsql } = await import('drizzle-orm/libsql');\n this.client = createClient({ url: config.url, authToken: config.authToken });\n this.db = drizzleLibsql(this.client);\n break;\n }\n default:\n throw new DriverError(`Unsupported DB driver: ${config.driver}`, {\n code: 'DRIVER_START_FAILED',\n context: { driver: config.driver },\n });\n }\n this.app!.logger.info('DB connected successfully.');\n } catch (error) {\n if (error instanceof DriverError) throw error;\n this.app!.logger.error({ error }, 'Failed to connect to DB');\n throw new ConnectionError('Failed to connect to DB', {\n cause: error instanceof Error ? error : new Error(String(error)),\n context: { driver: config.driver, url: config.url },\n });\n }\n }\n\n /*\n Ejecuta migraciones pendientes usando Drizzle Kit.\n /\n async runMigrations(schemaPath: string, migrationsDir: string = './drizzle'): Promise<void> {\n if (!this.app?.config.db) {\n throw new DriverError('Cannot run migrations: no DB configuration found', {\n code: 'DRIVER_START_FAILED',\n });\n }\n\n const config = this.app.config.db;\n const helper = new MigrationHelper(\n {\n dialect: mapDialect(config.driver),\n dbUrl: config.url,\n schemaPath,\n migrationsDir,\n },\n this.app,\n );\n\n await helper.migrate();\n }\n\n async stop() {\n if (this.client) {\n // Close connections based on client type\n if (this.client.end) { // Postgres usage with postgres.js usually handles itself or has end. \n // mysql2 has end()\n await this.client.end();\n } else if (this.client.close) { // bun:sqlite / libsql\n this.client.close();\n }\n // postgres.js handles cleanup usually but explicit close might be needed depending on version/usage\n }\n }\n}\n","import { IskraError, ErrorCodes, type ErrorCode } from '@iskra-bun/core';\n\n// ─── Connection Error ────────────────────────────────────────────────────────\n\nexport class ConnectionError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.CONNECTION_ERROR, ...options });\n this.name = 'ConnectionError';\n }\n}\n\n// ─── Query Error ─────────────────────────────────────────────────────────────\n\nexport class QueryError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.QUERY_ERROR, ...options });\n this.name = 'QueryError';\n }\n}\n\n// ─── Migration Error ─────────────────────────────────────────────────────────\n\nexport class MigrationError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.MIGRATION_ERROR, ...options });\n this.name = 'MigrationError';\n }\n}\n","import { type App } from '@iskra-bun/core';\nimport { MigrationError } from './errors';\n\nexport interface MigrationConfig {\n /* Dialecto de la base de datos /\n dialect: 'postgresql' \| 'mysql' \| 'sqlite';\n /* URL de conexión a la base de datos /\n dbUrl: string;\n /* Ruta al archivo de schema Drizzle (ej: './src/db/schema.ts') /\n schemaPath: string;\n /* Directorio donde se generan las migraciones (ej: './drizzle') /\n migrationsDir: string;\n}\n\n/\n Helper para ejecutar migraciones de Drizzle Kit.\n * Usa `bunx drizzle-kit` como subproceso para generar y aplicar migraciones.\n /\nexport class MigrationHelper {\n private config: MigrationConfig;\n private app?: App;\n\n constructor(config: MigrationConfig, app?: App) {\n this.config = config;\n this.app = app;\n }\n\n /\n Genera archivos de migración basados en los cambios del schema.\n /\n async generate(name?: string): Promise<void> {\n const args = ['drizzle-kit', 'generate'];\n if (name) args.push('--name', name);\n await this.exec(args, 'generate');\n }\n\n /\n Aplica las migraciones pendientes a la base de datos.\n /\n async migrate(): Promise<void> {\n await this.exec(['drizzle-kit', 'migrate'], 'migrate');\n }\n\n /\n Empuja el schema directamente a la base de datos (sin generar archivos de migración).\n * Útil para desarrollo rápido.\n /\n async push(): Promise<void> {\n await this.exec(['drizzle-kit', 'push'], 'push');\n }\n\n /\n Elimina todas las tablas de la base de datos.\n /\n async drop(): Promise<void> {\n await this.exec(['drizzle-kit', 'drop'], 'drop');\n }\n\n private async exec(args: string[], operation: string): Promise<void> {\n const env: Record<string, string> = {\n ...process.env as Record<string, string>,\n DATABASE_URL: this.config.dbUrl,\n };\n\n this.app?.logger.info(`Running migration: ${operation}`);\n\n try {\n const proc = Bun.spawn(['bunx', ...args], {\n cwd: process.cwd(),\n env,\n stdout: 'pipe',\n stderr: 'pipe',\n });\n\n const exitCode = await proc.exited;\n const stdout = await new Response(proc.stdout).text();\n const stderr = await new Response(proc.stderr).text();\n\n if (stdout) this.app?.logger.info(stdout.trim());\n\n if (exitCode !== 0) {\n throw new MigrationError(`Migration ${operation} failed with exit code ${exitCode}`, {\n context: { operation, exitCode, stderr: stderr.trim() },\n });\n }\n\n this.app?.logger.info(`Migration ${operation} completed successfully`);\n } catch (error) {\n if (error instanceof MigrationError) throw error;\n throw new MigrationError(`Migration ${operation} failed`, {\n cause: error instanceof Error ? error : new Error(String(error)),\n context: { operation },\n });\n }\n }\n}\n\n/\n Mapea el driver de Iskra al dialecto de Drizzle Kit.\n /\nexport function mapDialect(driver: string): MigrationConfig['dialect'] {\n switch (driver) {\n case 'postgres':\n return 'postgresql';\n case 'mysql':\n return 'mysql';\n case 'sqlite':\n case 'libsql':\n return 'sqlite';\n default:\n throw new MigrationError(`Cannot map driver \"${driver}\" to a Drizzle dialect`, {\n context: { driver },\n });\n }\n}\n","// src/index.ts\nfunction defineConfig(config) {\n return config;\n}\nexport {\n defineConfig\n};\n","import { defineConfig } from 'drizzle-kit';\n\nexport interface DrizzleConfigOptions {\n /* Dialecto: 'postgresql', 'mysql', 'sqlite' /\n dialect: 'postgresql' \| 'mysql' \| 'sqlite';\n /* URL de conexión a la base de datos /\n dbUrl: string;\n /* Ruta al archivo de schema (ej: './src/db/schema.ts') /\n schemaPath: string;\n /* Directorio de migraciones (ej: './drizzle') /\n migrationsDir?: string;\n}\n\n/\n Crea una configuración de drizzle-kit reutilizable.\n \n Uso en tu proyecto:\n * ```ts\n * // drizzle.config.ts\n * import { createDrizzleConfig } from '@iskra-bun/db-kit';\n \n export default createDrizzleConfig({\n * dialect: 'sqlite',\n * dbUrl: process.env.DATABASE_URL \|\| 'app.db',\n * schemaPath: './src/db/schema.ts',\n * });\n * ```\n */\nexport function createDrizzleConfig(options: DrizzleConfigOptions) {\n return defineConfig({\n dialect: options.dialect,\n schema: options.schemaPath,\n out: options.migrationsDir \|\| './drizzle',\n dbCredentials: {\n url: options.dbUrl,\n },\n });\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/driver.ts","../src/errors.ts","../src/migrations.ts","../../../node_modules/drizzle-kit/index.mjs","../src/drizzle.config.template.ts"],"sourcesContent":["import { type App, type Driver, type AppConfig, DriverError } from '@iskra-bun/core';\nimport { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';\nimport { drizzle as drizzleMysql, type MySql2Database } from 'drizzle-orm/mysql2';\nimport type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';\nimport type { LibSQLDatabase } from 'drizzle-orm/libsql';\nimport postgres from 'postgres';\nimport mysql from 'mysql2/promise';\nimport { sql } from 'drizzle-orm';\nimport { ConnectionError, QueryError } from './errors';\nimport { MigrationHelper, mapDialect } from './migrations';\n\n/*\n Observability callback invoked for every SQL statement Drizzle executes.\n * Receives the rendered query and its bound parameters.\n /\nexport type OnQueryHook = (query: string, params: unknown[]) => void;\n\n/\n The transaction handle passed to {@link DbDriver.transaction}. Drizzle types\n * the transaction object per dialect, so — like {@link IskraDrizzleDb} — this is\n * the union of the supported dialect databases for the same schema. Callers can\n * narrow by dialect if they need dialect-specific transaction APIs.\n /\nexport type IskraDrizzleTx<TSchema extends Record<string, unknown> = Record<string, never>> =\n IskraDrizzleDb<TSchema>;\n\n/\n The Drizzle database handle exposed by {@link DbDriver}, parameterized by the\n * caller's schema. Because the concrete dialect is chosen at runtime, this is a\n * union of the supported dialect databases — all four share the same\n * `TSchema extends Record<string, unknown> = Record<string, never>` parameter,\n * so passing a schema types `db.query.` for opt-in callers while the default\n `Record<string, never>` reproduces the historical untyped behavior.\n /\nexport type IskraDrizzleDb<TSchema extends Record<string, unknown> = Record<string, never>> =\n \| PostgresJsDatabase<TSchema>\n \| MySql2Database<TSchema>\n \| BunSQLiteDatabase<TSchema>\n \| LibSQLDatabase<TSchema>;\n\n/\n Redact username and password from a database URL so it is safe to log.\n * Returns the scrubbed URL string, or undefined if parsing fails.\n \n e.g. postgres://user:pass@host:5432/db → postgres://*:@host:5432/db\n /\nexport function scrubUrl(url: string): string \| undefined {\n try {\n const parsed = new URL(url);\n if (parsed.username) parsed.username = '*';\n if (parsed.password) parsed.password = '';\n return parsed.toString();\n } catch {\n return undefined;\n }\n}\n\n/\n The minimal teardown surface {@link DbDriver.stop} probes on the underlying\n * client. postgres-js and mysql2 expose async `end()`; bun:sqlite and libsql\n * expose synchronous `close()`. Typed as optional so either shape satisfies it.\n /\ninterface DbClient {\n end?(): Promise<void>;\n close?(): void;\n}\n\nexport class DbDriver<TSchema extends Record<string, unknown> = Record<string, never>> implements Driver {\n name = 'db';\n private client: DbClient \| undefined;\n public db: IskraDrizzleDb<TSchema> \| undefined;\n\n private app: App \| undefined;\n private onQuery: OnQueryHook \| undefined;\n\n /\n Register an observability callback that receives every SQL statement (and\n * its bound params) Drizzle executes. Must be called before {@link start},\n * since Drizzle's logger is wired at connection time. A throwing callback is\n * swallowed so observability never breaks a real query.\n /\n setOnQuery(onQuery: OnQueryHook): void {\n this.onQuery = onQuery;\n }\n\n /\n Build the Drizzle `logger` option that forwards to {@link onQuery} when a\n * hook is registered, or `undefined` to leave Drizzle's default logging off.\n /\n private buildLogger(): { logQuery(query: string, params: unknown[]): void } \| undefined {\n const hook = this.onQuery;\n if (!hook) return undefined;\n return {\n logQuery: (query: string, params: unknown[]) => {\n try {\n hook(query, params);\n } catch {\n // Observability must never break the underlying query.\n }\n },\n };\n }\n\n async init(app: App) {\n this.app = app;\n app.context.set('db', this);\n }\n\n async start() {\n if (!this.app) return;\n const config = this.app.config.db;\n if (!config) {\n this.app!.logger.warn('No DB configuration found. Skipping DB initialization.');\n return;\n }\n\n this.app!.logger.info(`Initializing DB driver: ${config.driver}`);\n\n const logger = this.buildLogger();\n\n try {\n switch (config.driver) {\n case 'postgres': {\n const client = postgres(config.url);\n this.client = client;\n this.db = drizzle<TSchema>(client, { logger });\n break;\n }\n case 'mysql': {\n const client = mysql.createPool(config.url);\n this.client = client;\n this.db = drizzleMysql<TSchema>(client, { logger });\n break;\n }\n case 'sqlite': {\n const { Database } = await import(\"bun:sqlite\");\n const { drizzle: drizzleSqlite } = await import(\"drizzle-orm/bun-sqlite\");\n const client = new Database(config.url);\n this.client = client;\n this.db = drizzleSqlite<TSchema>(client, { logger });\n break;\n }\n case 'libsql': {\n const { createClient } = await import('@libsql/client');\n const { drizzle: drizzleLibsql } = await import('drizzle-orm/libsql');\n const client = createClient({ url: config.url, authToken: config.authToken });\n this.client = client;\n this.db = drizzleLibsql<TSchema>(client, { logger });\n break;\n }\n default:\n throw new DriverError(`Unsupported DB driver: ${config.driver}`, {\n code: 'DRIVER_START_FAILED',\n context: { driver: config.driver },\n });\n }\n this.app!.logger.info('DB connected successfully.');\n } catch (error) {\n if (error instanceof DriverError) throw error;\n this.app!.logger.error({ error }, 'Failed to connect to DB');\n const safeUrl = scrubUrl(config.url);\n throw new ConnectionError('Failed to connect to DB', {\n cause: error instanceof Error ? error : new Error(String(error)),\n context: {\n driver: config.driver,\n ...(safeUrl !== undefined ? { url: safeUrl } : {}),\n },\n });\n }\n }\n\n /\n Ejecuta migraciones pendientes usando Drizzle Kit.\n /\n async runMigrations(schemaPath: string, migrationsDir: string = './drizzle'): Promise<void> {\n if (!this.app?.config.db) {\n throw new DriverError('Cannot run migrations: no DB configuration found', {\n code: 'DRIVER_START_FAILED',\n });\n }\n\n const config = this.app.config.db;\n const helper = new MigrationHelper(\n {\n dialect: mapDialect(config.driver),\n dbUrl: config.url,\n schemaPath,\n migrationsDir,\n },\n this.app,\n );\n\n await helper.migrate();\n }\n\n /\n Run `fn` inside a database transaction, delegating to Drizzle's\n * `db.transaction`. Callers receive the transaction-scoped db handle instead\n * of reaching into the raw `db`. The dialect union means `tx` is typed as\n * {@link IskraDrizzleTx}; narrow by dialect if you need dialect-specific APIs.\n * Failures are wrapped in {@link QueryError} (Drizzle rolls back on throw).\n /\n async transaction<R>(fn: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R> {\n if (!this.db) {\n throw new QueryError('Cannot run transaction: DB is not started', {\n context: { driver: this.app?.config.db?.driver },\n });\n }\n try {\n // The dialect-specific `transaction` overloads do not unify across the\n // union, so we route through the runtime method with a faithful cast\n // of the public handle types.\n return await (this.db as IskraDrizzleDb<TSchema> & {\n transaction(cb: (tx: IskraDrizzleTx<TSchema>) => Promise<R>): Promise<R>;\n }).transaction((tx) => fn(tx));\n } catch (error) {\n if (error instanceof QueryError) throw error;\n throw new QueryError('Transaction failed', {\n cause: error instanceof Error ? error : new Error(String(error)),\n context: { driver: this.app?.config.db?.driver },\n });\n }\n }\n\n /\n Liveness probe for readiness checks (e.g. web-kit's addReadinessCheck /\n * k8s readiness). Runs a trivial `SELECT 1` against the active dialect and\n * resolves `true` on success or `false` on any failure — it never rejects.\n /\n async ping(): Promise<boolean> {\n if (!this.db) return false;\n try {\n // bun-sqlite exposes the synchronous `.run()`; postgres-js, mysql2 and\n // libsql expose the async `.execute()`. Prefer whichever exists.\n const handle = this.db as {\n run?(query: unknown): unknown;\n execute?(query: unknown): Promise<unknown>;\n };\n if (typeof handle.run === 'function') {\n await handle.run(sql`SELECT 1`);\n } else if (typeof handle.execute === 'function') {\n await handle.execute(sql`SELECT 1`);\n } else {\n return false;\n }\n return true;\n } catch {\n return false;\n }\n }\n\n async stop() {\n const client = this.client;\n try {\n // postgres-js / mysql2 expose async end(); bun:sqlite / libsql expose\n // synchronous close(). Probe for whichever this client provides.\n if (client?.end) {\n await client.end();\n } else if (client?.close) {\n client.close();\n }\n } catch (error) {\n // A throwing teardown must never abort the orderly shutdown of other\n // drivers; log and continue so the handles below are still cleared.\n this.app?.logger.error({ error }, 'Failed to close DB connection cleanly');\n } finally {\n // Null the handles so a post-stop ping()/transaction() hits the\n // not-started guard instead of an already-closed connection.\n this.client = undefined;\n this.db = undefined;\n }\n }\n}\n","import { IskraError, ErrorCodes, type ErrorCode } from '@iskra-bun/core';\n\n// ─── Connection Error ────────────────────────────────────────────────────────\n\nexport class ConnectionError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.CONNECTION_ERROR, ...options });\n this.name = 'ConnectionError';\n }\n}\n\n// ─── Query Error ─────────────────────────────────────────────────────────────\n\nexport class QueryError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.QUERY_ERROR, ...options });\n this.name = 'QueryError';\n }\n}\n\n// ─── Migration Error ─────────────────────────────────────────────────────────\n\nexport class MigrationError extends IskraError {\n constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n super(message, { code: ErrorCodes.MIGRATION_ERROR, ...options });\n this.name = 'MigrationError';\n }\n}\n","import { type App } from '@iskra-bun/core';\nimport { MigrationError } from './errors';\n\n/\n Redacta credenciales `//user:pass@host` embebidas en texto arbitrario (p. ej.\n * el stderr de drizzle-kit, que suele imprimir la cadena de conexión completa al\n * fallar). A diferencia de `scrubUrl`, opera sobre texto libre y no requiere que\n * el contenido sea una URL parseable, dejando intacto el resto del diagnóstico.\n \n e.g. \"... postgres://user:pass@host:5432/db\" → \"... postgres://*:@host:5432/db\"\n /\nexport function scrubCredentials(text: string): string {\n return text.replace(/(\\/\\/)[^/\\s:@]+:[^/\\s@]+@/g, '$1*:@');\n}\n\nexport interface MigrationConfig {\n /* Dialecto de la base de datos /\n dialect: 'postgresql' \| 'mysql' \| 'sqlite';\n /* URL de conexión a la base de datos /\n dbUrl: string;\n /* Ruta al archivo de schema Drizzle (ej: './src/db/schema.ts') /\n schemaPath: string;\n /* Directorio donde se generan las migraciones (ej: './drizzle') /\n migrationsDir: string;\n /* Ruta opcional a un drizzle.config.ts; cuando se define se pasa como --config. /\n configPath?: string;\n}\n\n/\n Helper para ejecutar migraciones de Drizzle Kit.\n * Usa `bunx drizzle-kit` como subproceso para generar y aplicar migraciones.\n /\nexport class MigrationHelper {\n private config: MigrationConfig;\n private app?: App;\n\n constructor(config: MigrationConfig, app?: App) {\n this.config = config;\n this.app = app;\n }\n\n /\n Genera archivos de migración basados en los cambios del schema.\n * drizzle-kit generate soporta --schema y --out, así que ambos se reenvían\n * desde la config (antes se ignoraban silenciosamente).\n /\n async generate(name?: string): Promise<void> {\n const args = ['drizzle-kit', 'generate'];\n if (this.config.schemaPath) args.push('--schema', this.config.schemaPath);\n if (this.config.migrationsDir) args.push('--out', this.config.migrationsDir);\n if (name) args.push('--name', name);\n if (this.config.configPath) args.push('--config', this.config.configPath);\n await this.exec(args, 'generate');\n }\n\n /\n Aplica las migraciones pendientes a la base de datos.\n * `migrate` sólo acepta --config; schema y out no son flags válidos en este\n * comando, por eso únicamente reenviamos configPath cuando está presente.\n /\n async migrate(): Promise<void> {\n const args = ['drizzle-kit', 'migrate'];\n if (this.config.configPath) args.push('--config', this.config.configPath);\n await this.exec(args, 'migrate');\n }\n\n /\n Empuja el schema directamente a la base de datos (sin generar archivos de migración).\n * Útil para desarrollo rápido. `push` acepta --schema pero no --out.\n /\n async push(): Promise<void> {\n const args = ['drizzle-kit', 'push'];\n if (this.config.schemaPath) args.push('--schema', this.config.schemaPath);\n if (this.config.configPath) args.push('--config', this.config.configPath);\n await this.exec(args, 'push');\n }\n\n /\n Elimina todas las tablas de la base de datos.\n * `drop` acepta --out (dónde viven las migraciones) pero no --schema.\n /\n async drop(): Promise<void> {\n const args = ['drizzle-kit', 'drop'];\n if (this.config.migrationsDir) args.push('--out', this.config.migrationsDir);\n if (this.config.configPath) args.push('--config', this.config.configPath);\n await this.exec(args, 'drop');\n }\n\n private async exec(args: string[], operation: string): Promise<void> {\n const env: Record<string, string> = {\n ...process.env as Record<string, string>,\n DATABASE_URL: this.config.dbUrl,\n };\n\n this.app?.logger.info(`Running migration: ${operation}`);\n\n try {\n const proc = Bun.spawn(['bunx', ...args], {\n cwd: process.cwd(),\n env,\n stdout: 'pipe',\n stderr: 'pipe',\n });\n\n const exitCode = await proc.exited;\n const stdout = await new Response(proc.stdout).text();\n const stderr = await new Response(proc.stderr).text();\n\n if (stdout) this.app?.logger.info(stdout.trim());\n\n if (exitCode !== 0) {\n throw new MigrationError(`Migration ${operation} failed with exit code ${exitCode}`, {\n context: { operation, exitCode, stderr: scrubCredentials(stderr.trim()) },\n });\n }\n\n this.app?.logger.info(`Migration ${operation} completed successfully`);\n } catch (error) {\n if (error instanceof MigrationError) throw error;\n throw new MigrationError(`Migration ${operation} failed`, {\n cause: error instanceof Error ? error : new Error(String(error)),\n context: { operation },\n });\n }\n }\n}\n\n/\n Mapea el driver de Iskra al dialecto de Drizzle Kit.\n /\nexport function mapDialect(driver: string): MigrationConfig['dialect'] {\n switch (driver) {\n case 'postgres':\n return 'postgresql';\n case 'mysql':\n return 'mysql';\n case 'sqlite':\n case 'libsql':\n return 'sqlite';\n default:\n throw new MigrationError(`Cannot map driver \"${driver}\" to a Drizzle dialect`, {\n context: { driver },\n });\n }\n}\n","// src/index.ts\nfunction defineConfig(config) {\n return config;\n}\nexport {\n defineConfig\n};\n","import { defineConfig } from 'drizzle-kit';\n\nexport interface DrizzleConfigOptions {\n /* Dialecto: 'postgresql', 'mysql', 'sqlite' /\n dialect: 'postgresql' \| 'mysql' \| 'sqlite';\n /* URL de conexión a la base de datos /\n dbUrl: string;\n /* Ruta al archivo de schema (ej: './src/db/schema.ts') /\n schemaPath: string;\n /* Directorio de migraciones (ej: './drizzle') /\n migrationsDir?: string;\n}\n\n/\n Crea una configuración de drizzle-kit reutilizable.\n \n Uso en tu proyecto:\n * ```ts\n * // drizzle.config.ts\n * import { createDrizzleConfig } from '@iskra-bun/db-kit';\n \n export default createDrizzleConfig({\n * dialect: 'sqlite',\n * dbUrl: process.env.DATABASE_URL \|\| 'app.db',\n * schemaPath: './src/db/schema.ts',\n * });\n * ```\n */\nexport function createDrizzleConfig(options: DrizzleConfigOptions) {\n return defineConfig({\n dialect: options.dialect,\n schema: options.schemaPath,\n out: options.migrationsDir \|\| './drizzle',\n dbCredentials: {\n url: options.dbUrl,\n },\n });\n}\n"],"mappings":"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","names":[]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/db-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Base de datos SQL de Iskra con Drizzle ORM (PostgreSQL, MySQL, SQLite, LibSQL).",
     "keywords": [
         "iskra",
@@ -49,7 +49,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.0",
+        "@iskra-bun/core": "0.1.1",
         "drizzle-orm": "^0.30.0",
         "postgres": "^3.4.4",
         "mysql2": "^3.9.2",

package/src/driver.ts CHANGED Viewed

@@ -1,17 +1,105 @@
 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 { 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 { sql } from 'drizzle-orm';
+import { ConnectionError, QueryError } from './errors';
 import { MigrationHelper, mapDialect } from './migrations';
-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 username and password 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
+ */
+export function scrubUrl(url: string): string | undefined {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username) parsed.username = '***';
+        if (parsed.password) parsed.password = '***';
+        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;
+    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 +116,36 @@ 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;
+                    this.db = drizzleMysql<TSchema>(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 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:
@@ -62,9 +158,13 @@ export class DbDriver implements Driver {
         } catch (error) {
             if (error instanceof DriverError) throw error;
             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 } : {}),
+                },
             });
         }
     }
@@ -93,16 +193,81 @@ export class DbDriver implements Driver {
         await helper.migrate();
     }
+    /**
+     * 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} (Drizzle rolls back on throw).
+     */
+    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 {
+            // 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 },
+            });
+        }
+    }
+    /**
+     * 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 {
+            // 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;
+            }
+            return true;
+        } catch {
+            return false;
+        }
+    }
     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;
         }
     }
 }

package/src/migrations.ts CHANGED Viewed

@@ -1,6 +1,18 @@
 import { type App } from '@iskra-bun/core';
 import { MigrationError } from './errors';
+/**
+ * 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.
+ *
+ * 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***:***@');
+}
 export interface MigrationConfig {
     /** Dialecto de la base de datos */
     dialect: 'postgresql' | 'mysql' | 'sqlite';
@@ -10,6 +22,8 @@ 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;
 }
 /**
@@ -27,33 +41,49 @@ 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'];
+        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 = ['drizzle-kit', '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 = ['drizzle-kit', '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.
+     * `drop` acepta --out (dónde viven las migraciones) pero no --schema.
      */
     async drop(): Promise<void> {
-        await this.exec(['drizzle-kit', 'drop'], 'drop');
+        const args = ['drizzle-kit', '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> {
@@ -80,7 +110,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()) },
                 });
             }