@warlock.js/cascade 4.6.0 → 4.6.1

package/esm/drivers/postgres/postgres-driver.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-driver.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/drivers/postgres/postgres-driver.ts"],"sourcesContent":["/**\n * PostgreSQL Driver\n *\n * Main driver implementation for PostgreSQL database operations.\n * Implements the DriverContract interface to provide a unified API\n * for CRUD operations, transactions, and query building.\n *\n * Uses the `pg` package for database connectivity with connection pooling.\n *\n * @module cascade/drivers/postgres\n */\n\nimport { colors } from \"@mongez/copper\";\nimport { log } from \"@warlock.js/logger\";\nimport { databaseTransactionContext } from \"../../context/database-transaction-context\";\nimport type {\n  CreateDatabaseOptions,\n  DriverContract,\n  DriverEventListener,\n  DriverTransactionContract,\n  DropDatabaseOptions,\n  InsertResult,\n  TransactionContext,\n  UpdateOperations,\n  UpdateResult,\n} from \"../../contracts/database-driver.contract\";\nimport type { DriverBlueprintContract } from \"../../contracts/driver-blueprint.contract\";\nimport type { MigrationDriverContract } from \"../../contracts/migration-driver.contract\";\nimport type { QueryBuilderContract } from \"../../contracts/query-builder.contract\";\nimport type { SyncAdapterContract } from \"../../contracts/sync-adapter.contract\";\nimport { TransactionRollbackError } from \"../../errors/transaction-rollback.error\";\nimport { SQLSerializer } from \"../../migration/sql-serializer\";\nimport { SqlDatabaseDirtyTracker } from \"../../sql-database-dirty-tracker\";\nimport type { ModelDefaults } from \"../../types\";\nimport { DatabaseDriver } from \"../../utils/connect-to-database\";\nimport { isValidDateValue } from \"../../utils/is-valid-date-value\";\nimport { PostgresBlueprint } from \"./postgres-blueprint\";\nimport { PostgresDialect } from \"./postgres-dialect\";\nimport { PostgresMigrationDriver } from \"./postgres-migration-driver\";\nimport { PostgresQueryBuilder } from \"./postgres-query-builder\";\nimport { PostgresSQLSerializer } from \"./postgres-sql-serializer\";\nimport { PostgresSyncAdapter } from \"./postgres-sync-adapter\";\nimport type { PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions } from \"./types\";\n\n/**\n * Lazily loaded pg module types.\n */\ntype PgPool = import(\"pg\").Pool;\ntype PgPoolClient = import(\"pg\").PoolClient;\ntype PgPoolConfig = import(\"pg\").PoolConfig;\n\n/**\n * Cached pg module reference.\n */\nlet pgModule: typeof import(\"pg\") | undefined;\n\n/**\n * Lazily load the pg package.\n *\n * @returns The pg module\n * @throws Error if pg is not installed\n */\nasync function loadPg(): Promise<typeof import(\"pg\")> {\n  if (pgModule) {\n    return pgModule;\n  }\n\n  try {\n    pgModule = await import(\"pg\");\n    return pgModule;\n  } catch {\n    throw new Error(\n      'The \"pg\" package is required for PostgreSQL support. ' + \"Please install it: npm install pg\",\n    );\n  }\n}\n\n/**\n * PostgreSQL database driver implementing the Cascade DriverContract.\n *\n * Provides connection pooling, CRUD operations, transactions, and\n * integration with Cascade's query builder and migration systems.\n *\n * @example\n * ```typescript\n * const driver = new PostgresDriver({\n *   host: 'localhost',\n *   port: 5432,\n *   database: 'myapp',\n *   user: 'postgres',\n *   password: 'secret'\n * });\n *\n * await driver.connect();\n *\n * // Insert a document\n * const result = await driver.insert('users', { name: 'Alice', email: 'alice@example.com' });\n *\n * // Query using the query builder\n * const users = await driver.queryBuilder('users')\n *   .where('name', 'Alice')\n *   .get();\n *\n * await driver.disconnect();\n * ```\n */\nexport class PostgresDriver implements DriverContract {\n  /**\n   * Driver name identifier.\n   */\n  public readonly name = \"postgres\" as DatabaseDriver;\n\n  /**\n   * SQL dialect for PostgreSQL-specific syntax.\n   */\n  public readonly dialect = new PostgresDialect();\n\n  /**\n   * PostgreSQL driver model defaults.\n   *\n   * PostgreSQL follows SQL conventions:\n   * - snake_case naming for columns (created_at, updated_at, deleted_at)\n   * - Native AUTO_INCREMENT for IDs (no manual generation)\n   * - Timestamps enabled by default\n   * - Permanent delete strategy (hard deletes)\n   */\n  public readonly modelDefaults: Partial<ModelDefaults> = {\n    namingConvention: \"snake_case\",\n    createdAtColumn: \"created_at\",\n    updatedAtColumn: \"updated_at\",\n    deletedAtColumn: \"deleted_at\",\n    timestamps: true,\n    autoGenerateId: false, // PostgreSQL uses SERIAL/BIGSERIAL\n    strictMode: \"fail\",\n    deleteStrategy: \"permanent\",\n  };\n\n  /**\n   * Connection pool instance.\n   */\n  private _pool: PgPool | undefined;\n\n  /**\n   * Event listeners for driver lifecycle events.\n   */\n  private readonly _eventListeners = new Map<string, Set<DriverEventListener>>();\n\n  /**\n   * Whether the driver is currently connected.\n   */\n  private _isConnected = false;\n\n  /**\n   * Blueprint instance (lazy-loaded).\n   */\n  private _blueprint: DriverBlueprintContract | undefined;\n\n  /**\n   * Migration driver instance (lazy-loaded).\n   */\n  private _migrationDriver: MigrationDriverContract | undefined;\n\n  /**\n   * Sync adapter instance (lazy-loaded).\n   */\n  private _syncAdapter: SyncAdapterContract | undefined;\n\n  /**\n   * Lookup set of column names that hold native PostgreSQL arrays\n   * (`JSONB[]`, `TEXT[]`, …) and must NOT be JSON-text encoded.\n   *\n   * @see PostgresPoolConfig.nativeArrayColumns\n   */\n  private readonly _nativeArrayColumns: ReadonlySet<string>;\n\n  /**\n   * Create a new PostgreSQL driver instance.\n   *\n   * @param config - PostgreSQL connection configuration\n   */\n  public constructor(private readonly config: PostgresPoolConfig) {\n    this._nativeArrayColumns = new Set(config.nativeArrayColumns ?? []);\n  }\n\n  /**\n   * Get the connection pool instance.\n   *\n   * @throws Error if not connected\n   */\n  public get pool(): PgPool {\n    if (!this._pool) {\n      throw new Error(\"PostgreSQL driver is not connected. Call connect() first.\");\n    }\n    return this._pool;\n  }\n\n  /**\n   * Get database native client\n   */\n  public getClient<Client = PgPool>(): Client {\n    return this.pool as Client;\n  }\n\n  /**\n   * Check if the driver is currently connected.\n   */\n  public get isConnected(): boolean {\n    return this._isConnected;\n  }\n\n  /**\n   * Get the driver blueprint (information schema).\n   */\n  public get blueprint(): DriverBlueprintContract {\n    if (!this._blueprint) {\n      this._blueprint = new PostgresBlueprint(this);\n    }\n    return this._blueprint;\n  }\n\n  /**\n   * Establish connection to the PostgreSQL database.\n   *\n   * Creates a connection pool with the configured options.\n   * Emits 'connected' event on successful connection.\n   */\n  public async connect(): Promise<void> {\n    if (this._isConnected) {\n      return;\n    }\n\n    const pg = await loadPg();\n\n    try {\n      const poolConfig: PgPoolConfig = {\n        host: this.config.host ?? \"localhost\",\n        port: this.config.port ?? 5432,\n        database: this.config.database,\n        user: this.config.user,\n        password: this.config.password,\n        connectionString: this.config.connectionString,\n        max: this.config.max ?? 10,\n        min: this.config.min ?? 0,\n        idleTimeoutMillis: this.config.idleTimeoutMillis ?? 30000,\n        connectionTimeoutMillis: this.config.connectionTimeoutMillis ?? 2000,\n        application_name: this.config.application_name ?? \"cascade\",\n        ssl: this.config.ssl,\n      };\n\n      log.info(\n        \"database.postgres\",\n        \"connection\",\n        `Connecting to database ${colors.bold(colors.yellowBright(this.config.database))}`,\n      );\n\n      this._pool = new pg.Pool(poolConfig);\n\n      // Test the connection\n      const client = await this._pool.connect();\n      client.release();\n\n      log.success(\n        \"database.postgres\",\n        \"connection\",\n        `Connected to database ${colors.bold(colors.yellowBright(this.config.database))}`,\n      );\n\n      this._isConnected = true;\n      this.emit(\"connected\");\n    } catch (error) {\n      // Boot-time database connection failure is unrecoverable in every\n      // realistic caller (app boot, CLI migrations, workers) — `fatal` makes\n      // \"page on fatal only\" alerting clean. Per-query failures stay at error.\n      log.fatal(\"database.postgres\", \"connection\", \"Failed to connect to database\");\n      throw error;\n    }\n  }\n\n  /**\n   * Close the database connection pool.\n   *\n   * Waits for all active queries to complete before closing.\n   * Emits 'disconnected' event on successful disconnection.\n   */\n  public async disconnect(): Promise<void> {\n    if (!this._isConnected || !this._pool) {\n      return;\n    }\n\n    await this._pool.end();\n    this._pool = undefined;\n    this._isConnected = false;\n    this.emit(\"disconnected\");\n  }\n\n  /**\n   * Register an event listener for driver lifecycle events.\n   *\n   * @param event - Event name ('connected', 'disconnected', etc.)\n   * @param listener - Callback function to invoke\n   */\n  public on(event: string, listener: DriverEventListener): void {\n    if (!this._eventListeners.has(event)) {\n      this._eventListeners.set(event, new Set());\n    }\n\n    this._eventListeners.get(event)!.add(listener);\n  }\n\n  /**\n   * Serialize data for storage in PostgreSQL.\n   *\n   * Handles Date objects, BigInt, and other JavaScript types\n   * that need special handling for PostgreSQL storage.\n   *\n   * @param data - The data object to serialize\n   * @returns Serialized data ready for PostgreSQL\n   */\n  public serialize(data: Record<string, unknown>): Record<string, unknown> {\n    const serialized: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(data)) {\n      if (value === undefined) {\n        continue; // Skip undefined values\n      }\n\n      serialized[key] = this.serializeValue(key, value);\n    }\n\n    return serialized;\n  }\n\n  /**\n   * Serialize a single column value into a node-pg bindable parameter.\n   *\n   * Shared by {@link serialize} (INSERT path) and {@link buildUpdateQuery}\n   * `$set` (UPDATE path) so both encode `json` / `jsonb` columns identically.\n   *\n   * Encoding rules (in order):\n   * - `Date` → ISO string.\n   * - `bigint` → decimal string (node-pg has no native bigint binding).\n   * - all-number array → pgvector literal `'[n1,n2,...]'`. node-pg would\n   *   otherwise emit a `{n1,n2,...}` array literal, which the `vector` type\n   *   rejects. This branch is preserved exactly.\n   * - any other array (object-array, string-array, mixed, empty `[]`) →\n   *   `JSON.stringify`. node-pg renders a raw JS array as a PostgreSQL array\n   *   literal `{...}` (and `[]` as `{}`), which a `json` / `jsonb` column\n   *   rejects — so we bind the value as JSON text instead, the form those\n   *   columns accept. Columns listed in `nativeArrayColumns` are exempt:\n   *   their raw array is passed through so node-pg emits the `{...}` literal\n   *   a genuine `JSONB[]` / `TEXT[]` column needs.\n   * - plain object → `JSON.stringify`. Equivalent to node-pg's own object\n   *   handling, made explicit so both write paths agree.\n   * - everything else (scalars: string, number, boolean, null) → untouched.\n   *\n   * Boundary note: the serializer has no access to the table schema, so it\n   * cannot tell a `json` / `jsonb` column from a native-array column purely\n   * from the value. `nativeArrayColumns` is the explicit, opt-in escape hatch\n   * for the latter. No `::jsonb` placeholder cast is added: a JSON-text string\n   * binds correctly to `json` / `jsonb` without one, and a blind cast would\n   * misfire on columns we cannot positively identify as jsonb.\n   *\n   * @param key - Column name (used to honour `nativeArrayColumns`)\n   * @param value - The raw value to serialize (never `undefined`)\n   * @returns The value ready to bind as a query parameter\n   */\n  private serializeValue(key: string, value: unknown): unknown {\n    if (value instanceof Date) {\n      return value.toISOString();\n    }\n\n    if (typeof value === \"bigint\") {\n      return value.toString();\n    }\n\n    if (Array.isArray(value)) {\n      if (value.length > 0 && value.every((v) => typeof v === \"number\")) {\n        // pgvector columns expect the literal '[n1,n2,...]' format.\n        return `[${value.join(\",\")}]`;\n      }\n\n      // Genuine native PostgreSQL array columns (JSONB[], TEXT[], …) must\n      // keep their raw array so node-pg emits a '{...}' array literal.\n      if (this._nativeArrayColumns.has(key)) {\n        return value;\n      }\n\n      // json / jsonb columns: bind as JSON text. Covers object-arrays,\n      // string-arrays, mixed arrays, and empty [] (which would otherwise\n      // store as '{}' instead of '[]').\n      return JSON.stringify(value);\n    }\n\n    if (typeof value === \"object\" && value !== null) {\n      // Plain object → JSONB. Explicit JSON.stringify matches node-pg's own\n      // object encoding while keeping both write paths consistent.\n      return JSON.stringify(value);\n    }\n\n    return value;\n  }\n\n  /**\n   * Get the dirty tracker for this driver.\n   */\n  public getDirtyTracker(data: Record<string, unknown>): SqlDatabaseDirtyTracker {\n    return new SqlDatabaseDirtyTracker(data);\n  }\n\n  /**\n   * Deserialize data retrieved from PostgreSQL.\n   *\n   * Converts PostgreSQL types back to JavaScript equivalents.\n   *\n   * @param data - The data object from PostgreSQL\n   * @returns Deserialized JavaScript object\n   */\n  public deserialize(data: Record<string, unknown>): Record<string, unknown> {\n    // PostgreSQL pg driver handles most type conversions automatically\n    // Special handling can be added here if needed\n    for (const [key, value] of Object.entries(data)) {\n      // Only re-inflate strings — pg already returns Date objects from DB reads\n      if (typeof value !== \"string\") continue;\n\n      if (isValidDateValue(value)) {\n        data[key] = new Date(value);\n        continue;\n      }\n\n      // pgvector columns are returned as '[n1,n2,...]' strings.\n      // charCodeAt is faster than startsWith/endsWith — no string allocation.\n      // '[' = 91, ']' = 93\n      if (value.charCodeAt(0) === 91 && value.charCodeAt(value.length - 1) === 93) {\n        const parts = value.slice(1, -1).split(\",\");\n        const nums = new Array<number>(parts.length);\n        let isNumericVector = parts.length > 0;\n\n        for (let i = 0; i < parts.length; i++) {\n          const n = +parts[i]; // unary + is the fastest string-to-number coercion\n          if (!Number.isFinite(n)) {\n            isNumericVector = false;\n            break; // early-exit — not a numeric vector, leave value untouched\n          }\n          nums[i] = n;\n        }\n\n        if (isNumericVector) {\n          data[key] = nums;\n        }\n      }\n    }\n\n    return data;\n  }\n\n  /**\n   * Insert a single row into a table.\n   *\n   * Uses INSERT ... RETURNING to get the inserted row with generated values.\n   *\n   * @param table - Target table name\n   * @param document - Data to insert\n   * @param options - Optional insertion options\n   * @returns The inserted document\n   */\n  public async insert(\n    table: string,\n    document: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<InsertResult> {\n    const serialized = this.serialize(document);\n\n    // Filter out id if null/undefined to let PostgreSQL SERIAL auto-generate\n    const filteredData = Object.fromEntries(\n      Object.entries(serialized).filter(([key, value]) => {\n        // Exclude id if null/undefined (let SERIAL handle it)\n        if (key === \"id\" && (value === null || value === undefined)) {\n          return false;\n        }\n        return true;\n      }),\n    );\n\n    const columns = Object.keys(filteredData);\n    const values = Object.values(filteredData);\n\n    if (columns.length === 0) {\n      throw new Error(\"Cannot insert empty document\");\n    }\n\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const placeholders = columns.map((_, i) => this.dialect.placeholder(i + 1)).join(\", \");\n    const quotedTable = this.dialect.quoteIdentifier(table);\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES (${placeholders}) RETURNING *`;\n\n    const result = await this.query<Record<string, unknown>>(sql, values);\n\n    return {\n      document: result.rows[0],\n    };\n  }\n\n  /**\n   * Insert multiple rows into a table.\n   *\n   * Uses a single INSERT statement with multiple value sets for efficiency.\n   *\n   * @param table - Target table name\n   * @param documents - Array of documents to insert\n   * @param options - Optional insertion options\n   * @returns Array of inserted documents\n   */\n  public async insertMany(\n    table: string,\n    documents: Record<string, unknown>[],\n    _options?: Record<string, unknown>,\n  ): Promise<InsertResult[]> {\n    if (documents.length === 0) {\n      return [];\n    }\n\n    // Get all unique columns across all documents\n    const allColumns = new Set<string>();\n    for (const doc of documents) {\n      const serialized = this.serialize(doc);\n      Object.keys(serialized).forEach((key) => allColumns.add(key));\n    }\n    const columns = Array.from(allColumns);\n\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const quotedTable = this.dialect.quoteIdentifier(table);\n\n    // Build value sets and params\n    const valueSets: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = 1;\n\n    for (const doc of documents) {\n      const serialized = this.serialize(doc);\n      const rowPlaceholders: string[] = [];\n\n      for (const col of columns) {\n        if (col in serialized) {\n          rowPlaceholders.push(this.dialect.placeholder(paramIndex++));\n          params.push(serialized[col]);\n        } else {\n          rowPlaceholders.push(\"DEFAULT\");\n        }\n      }\n\n      valueSets.push(`(${rowPlaceholders.join(\", \")})`);\n    }\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES ${valueSets.join(\", \")} RETURNING *`;\n\n    const result = await this.query<Record<string, unknown>>(sql, params);\n\n    return result.rows as unknown as InsertResult[];\n  }\n\n  /**\n   * Update a single row matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations ($set, $unset, $inc)\n   * @param options - Optional update options\n   * @returns Update result with modified count\n   */\n  public async update(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update, 1);\n    try {\n      const result = await this.query(sql, params);\n\n      return {\n        modifiedCount: result.rowCount ?? 0,\n      };\n    } catch (error) {\n      console.log(\"PG Query Error in:\", sql, params);\n\n      throw error;\n    }\n  }\n\n  /**\n   * Find one and update a single row matching the filter and return the updated row\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations ($set, $unset, $inc)\n   * @param options - Optional update options\n   * @returns The updated row or null\n   */\n  public async findOneAndUpdate<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update, 1);\n    // Add RETURNING * to get the updated row back\n    const sqlWithReturning = `${sql} RETURNING *`;\n    const result = await this.query<T>(sqlWithReturning, params);\n    return result.rows[0] ?? null;\n  }\n\n  /**\n   * Update multiple rows matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations\n   * @param options - Optional update options\n   * @returns Update result with modified count\n   */\n  public async updateMany(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update);\n\n    const result = await this.query(sql, params);\n\n    return {\n      modifiedCount: result.rowCount ?? 0,\n    };\n  }\n\n  /**\n   * Replace a document matching the filter.\n   *\n   * Completely replaces the document (not a partial update).\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param document - New document data\n   * @param options - Optional options\n   * @returns The replaced document or null\n   */\n  public async replace<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    document: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const serialized = this.serialize(document);\n    const columns = Object.keys(serialized);\n    const values = Object.values(serialized);\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const setClauses = columns\n      .map((col, i) => `${this.dialect.quoteIdentifier(col)} = ${this.dialect.placeholder(i + 1)}`)\n      .join(\", \");\n\n    const { whereClause, whereParams } = this.buildWhereClause(filter, columns.length + 1);\n\n    const sql = `UPDATE ${quotedTable} SET ${setClauses} ${whereClause} RETURNING *`;\n    const params = [...values, ...whereParams];\n\n    const result = await this.query<T>(sql, params);\n\n    return result.rows[0] ?? null;\n  }\n\n  /**\n   * Upsert (insert or update) a single row.\n   *\n   * Uses PostgreSQL's INSERT ... ON CONFLICT ... DO UPDATE syntax.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions to find existing row (used for conflict detection)\n   * @param document - Document data to insert or update\n   * @param options - Upsert options (conflictColumns for conflict target)\n   * @returns The upserted row\n   */\n  public async upsert<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    document: Record<string, unknown>,\n    options?: Record<string, unknown>,\n  ): Promise<T> {\n    const serialized = this.serialize(document);\n    const columns = Object.keys(serialized);\n    const values = Object.values(serialized);\n\n    if (columns.length === 0) {\n      throw new Error(\"Cannot upsert empty document\");\n    }\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const placeholders = columns.map((_, i) => this.dialect.placeholder(i + 1)).join(\", \");\n\n    // Determine conflict columns from options or filter\n    const conflictColumns = (options?.conflictColumns as string[]) ?? Object.keys(filter);\n    if (conflictColumns.length === 0) {\n      throw new Error(\"Upsert requires conflictColumns option or filter with columns\");\n    }\n\n    const quotedConflictColumns = conflictColumns\n      .map((c) => this.dialect.quoteIdentifier(c))\n      .join(\", \");\n\n    // Build UPDATE clause for ON CONFLICT\n    // Update all columns except the conflict columns (they stay the same)\n    const updateColumns = columns.filter((col) => !conflictColumns.includes(col));\n    const setClauses = updateColumns\n      .map((col, i) => {\n        const valueIndex = columns.indexOf(col) + 1;\n        return `${this.dialect.quoteIdentifier(col)} = ${this.dialect.placeholder(valueIndex)}`;\n      })\n      .join(\", \");\n\n    // If there are no columns to update (all columns are conflict columns), use EXCLUDED\n    const updateClause =\n      setClauses.length > 0\n        ? setClauses\n        : columns\n            .map(\n              (col) =>\n                `${this.dialect.quoteIdentifier(col)} = EXCLUDED.${this.dialect.quoteIdentifier(col)}`,\n            )\n            .join(\", \");\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES (${placeholders}) ON CONFLICT (${quotedConflictColumns}) DO UPDATE SET ${updateClause} RETURNING *`;\n\n    const result = await this.query<T>(sql, values);\n\n    return result.rows[0]! as T;\n  }\n\n  /**\n   * Find one and delete a single row matching the filter and return the deleted row.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional delete options\n   * @returns The deleted row or null\n   */\n  public async findOneAndDelete<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter, 1);\n\n    // Use ctid for single row deletion with RETURNING\n    const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1) RETURNING *`;\n\n    const result = await this.query<T>(sql, whereParams);\n\n    return result.rows[0] ? (result.rows[0] as T) : null;\n  }\n\n  /**\n   * Delete a single row matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional options\n   * @returns Number of deleted rows (0 or 1)\n   */\n  public async delete(\n    table: string,\n    filter?: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter ?? {}, 1);\n\n    // Use ctid for single row deletion\n    const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;\n\n    const result = await this.query(sql, whereParams);\n\n    return result.rowCount ?? 0;\n  }\n\n  /**\n   * Delete multiple rows matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional options\n   * @returns Number of deleted rows\n   */\n  public async deleteMany(\n    table: string,\n    filter?: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter ?? {}, 1);\n\n    const sql = `DELETE FROM ${quotedTable} ${whereClause}`;\n\n    const result = await this.query(sql, whereParams);\n\n    return result.rowCount ?? 0;\n  }\n\n  /**\n   * Truncate a table (remove all rows).\n   *\n   * Uses TRUNCATE TABLE for fast deletion with RESTART IDENTITY.\n   *\n   * @param table - Target table name\n   * @param options - Optional options\n   * @param options.cascade - If true, automatically truncate all tables with foreign key references (use with caution)\n   * @returns Number of deleted rows (always 0 for TRUNCATE)\n   */\n  public async truncateTable(table: string, options?: { cascade?: boolean }): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const cascadeClause = options?.cascade ? \" CASCADE\" : \"\";\n    await this.query(`TRUNCATE TABLE ${quotedTable} RESTART IDENTITY${cascadeClause}`);\n    return 0; // TRUNCATE doesn't return row count\n  }\n\n  /**\n   * Get a query builder for the specified table.\n   *\n   * @param table - Target table name\n   * @returns Query builder instance\n   */\n  public queryBuilder<T = unknown>(table: string): QueryBuilderContract<T> {\n    return new PostgresQueryBuilder<T>(table) as unknown as QueryBuilderContract<T>;\n  }\n\n  /**\n   * Begin a new database transaction.\n   *\n   * Acquires a client from the pool and starts a transaction.\n   * The client is stored in AsyncLocalStorage for automatic\n   * participation by subsequent queries.\n   *\n   * @param options - Optional transaction options\n   * @returns Transaction contract with commit/rollback methods\n   */\n  public async beginTransaction(\n    options?: PostgresTransactionOptions,\n  ): Promise<DriverTransactionContract<PgPoolClient>> {\n    const client = await this.pool.connect();\n\n    let beginSql = \"BEGIN\";\n    if (options?.isolationLevel) {\n      beginSql += ` ISOLATION LEVEL ${options.isolationLevel.toUpperCase()}`;\n    }\n    if (options?.readOnly) {\n      beginSql += \" READ ONLY\";\n    }\n    if (options?.deferrable) {\n      beginSql += \" DEFERRABLE\";\n    }\n\n    await client.query(beginSql);\n\n    return {\n      context: client,\n      commit: async () => {\n        await client.query(\"COMMIT\");\n        client.release();\n      },\n      rollback: async () => {\n        await client.query(\"ROLLBACK\");\n        client.release();\n      },\n    };\n  }\n\n  /**\n   * Execute a function within a transaction scope (recommended pattern).\n   *\n   * Automatically commits on success, rolls back on any error, and guarantees\n   * resource cleanup. This is the recommended way to use transactions.\n   *\n   * @param fn - Async function to execute within transaction\n   * @param options - Transaction options (isolation level, read-only, etc.)\n   * @returns The return value of the callback function\n   * @throws {Error} If transaction fails or is explicitly rolled back\n   */\n  public async transaction<T>(\n    fn: (ctx: TransactionContext) => Promise<T>,\n    options?: Record<string, unknown>,\n  ): Promise<T> {\n    // Prevent nested transaction() calls\n    if (databaseTransactionContext.hasActiveTransaction()) {\n      // throw new Error(\n      //   \"Nested transaction() calls are not supported. \" +\n      //     \"Use beginTransaction() with savepoints for advanced transaction patterns.\",\n      // );\n    }\n\n    const tx = await this.beginTransaction(options);\n\n    // Set transaction context for queries within callback\n    databaseTransactionContext.enter({ session: tx.context });\n\n    try {\n      // Create transaction context with rollback method\n      const ctx: TransactionContext = {\n        rollback(reason?: string): never {\n          throw new TransactionRollbackError(reason);\n        },\n      };\n\n      // Execute callback\n      const result = await fn(ctx);\n\n      // Auto-commit on success\n      await tx.commit();\n\n      return result;\n    } catch (error) {\n      // Auto-rollback on any error (including explicit rollback)\n      await tx.rollback();\n      log.error(\n        `database.postgress`,\n        \"transaction\",\n        \"Transaction operation failed, rolled back everything\",\n      );\n      throw error;\n    } finally {\n      // Guaranteed cleanup\n      databaseTransactionContext.exit();\n    }\n  }\n\n  /**\n   * Perform an atomic update operation.\n   *\n   * Builds and executes an UPDATE query for the given filter and operations.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param operations - Update operations\n   * @param options - Optional options\n   * @returns Update result\n   */\n  public async atomic(\n    table: string,\n    filter: Record<string, unknown>,\n    operations: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, operations, 1);\n\n    const result = await this.query(sql, params);\n\n    return {\n      modifiedCount: result.rowCount ?? 0,\n    };\n  }\n\n  /**\n   * Get the sync adapter for bulk denormalized updates.\n   *\n   * @returns Sync adapter instance\n   */\n  public syncAdapter(): SyncAdapterContract {\n    if (!this._syncAdapter) {\n      this._syncAdapter = new PostgresSyncAdapter(this);\n    }\n    return this._syncAdapter;\n  }\n\n  /**\n   * Get the migration driver for schema operations.\n   *\n   * @returns Migration driver instance\n   */\n  public migrationDriver(): MigrationDriverContract {\n    if (!this._migrationDriver) {\n      this._migrationDriver = new PostgresMigrationDriver(this);\n    }\n\n    return this._migrationDriver;\n  }\n\n  /**\n   * Return a SQL serializer for this driver's dialect.\n   * Used by Migration.toSQL() to convert pending operations to SQL strings.\n   */\n  public getSQLSerializer(): SQLSerializer {\n    return new PostgresSQLSerializer(this.dialect);\n  }\n\n  /**\n   * Execute a raw SQL query.\n   *\n   * Automatically uses the transaction client if one is active.\n   *\n   * @param sql - SQL query string\n   * @param params - Query parameters\n   * @returns Query result\n   */\n  public async query<T = Record<string, unknown>>(\n    sql: string,\n    params: unknown[] = [],\n  ): Promise<PostgresQueryResult<T>> {\n    // Check for active transaction client\n    const txClient = databaseTransactionContext.getSession() as PgPoolClient | undefined;\n\n    const startTime = this.config.logging ? performance.now() : 0;\n\n    let paramsString = \"\";\n    if (this.config.logging && params.length > 0) {\n      paramsString = JSON.stringify(params);\n      if (paramsString.length > 300) {\n        paramsString = paramsString.substring(0, 300) + \"...\";\n      }\n      paramsString = ` | Params: ${paramsString}`;\n    }\n\n    try {\n      let result;\n      if (this.config.logging) {\n        log.info({\n          module: \"database.postgres\",\n          action: \"query.executing\",\n          message: `${sql}${paramsString}`,\n          context: { params, sql },\n        });\n      }\n      if (txClient) {\n        result = await txClient.query(sql, params);\n      } else {\n        result = await this.pool.query(sql, params);\n      }\n\n      if (this.config.logging) {\n        const duration = (performance.now() - startTime).toFixed(2);\n        log.success({\n          module: \"database.postgres\",\n          action: \"query.executed\",\n          message: `[${duration}ms] ${sql}${paramsString}`,\n          context: { params, sql, duration },\n        });\n      }\n\n      return result as PostgresQueryResult<T>;\n    } catch (error) {\n      if (this.config.logging) {\n        const duration = (performance.now() - startTime).toFixed(2);\n        log.error({\n          module: \"database.postgres\",\n          action: \"query.error\",\n          message: `[${duration}ms] ${sql}${paramsString}`,\n          context: {\n            sql,\n            params,\n            error: error instanceof Error ? error.message : String(error),\n          },\n        });\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Emit an event to all registered listeners.\n   *\n   * @param event - Event name\n   * @param args - Event arguments\n   */\n  private emit(event: string, ...args: unknown[]): void {\n    const listeners = this._eventListeners.get(event);\n    if (listeners) {\n      for (const listener of listeners) {\n        listener(...args);\n      }\n    }\n  }\n\n  /**\n   * Build a simple WHERE clause from a filter object.\n   *\n   * @param filter - Filter conditions\n   * @param startParamIndex - Starting parameter index\n   * @returns Object with WHERE clause string and parameters\n   */\n  private buildWhereClause(\n    filter: Record<string, unknown>,\n    startParamIndex: number,\n  ): { whereClause: string; whereParams: unknown[] } {\n    const conditions: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = startParamIndex;\n\n    for (const [key, value] of Object.entries(filter)) {\n      const quotedKey = this.dialect.quoteIdentifier(key);\n\n      if (value === null) {\n        conditions.push(`${quotedKey} IS NULL`);\n      } else {\n        conditions.push(`${quotedKey} = ${this.dialect.placeholder(paramIndex++)}`);\n        params.push(value);\n      }\n    }\n\n    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    return { whereClause, whereParams: params };\n  }\n\n  /**\n   * Build an UPDATE query from update operations.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations\n   * @param limit - Optional limit (for single row update)\n   * @returns Object with SQL and parameters\n   */\n  private buildUpdateQuery(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    limit?: number,\n  ): { sql: string; params: unknown[] } {\n    const setClauses: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = 1;\n\n    // Handle $set\n    if (update.$set) {\n      for (const [key, value] of Object.entries(update.$set)) {\n        setClauses.push(\n          `${this.dialect.quoteIdentifier(key)} = ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        // Apply the same json/jsonb-aware serialization used on the INSERT\n        // path so object/array $set values aren't corrupted into Postgres\n        // array literals. undefined is skipped — never bind it.\n        params.push(value === undefined ? value : this.serializeValue(key, value));\n      }\n    }\n\n    // Handle $unset (set to NULL)\n    if (update.$unset) {\n      for (const key of Object.keys(update.$unset)) {\n        setClauses.push(`${this.dialect.quoteIdentifier(key)} = NULL`);\n      }\n    }\n\n    // Handle $inc\n    if (update.$inc) {\n      for (const [key, amount] of Object.entries(update.$inc)) {\n        const quotedKey = this.dialect.quoteIdentifier(key);\n        setClauses.push(\n          `${quotedKey} = COALESCE(${quotedKey}, 0) + ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        params.push(amount);\n      }\n    }\n\n    // Handle $dec\n    if (update.$dec) {\n      for (const [key, amount] of Object.entries(update.$dec)) {\n        const quotedKey = this.dialect.quoteIdentifier(key);\n        setClauses.push(\n          `${quotedKey} = COALESCE(${quotedKey}, 0) - ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        params.push(amount);\n      }\n    }\n\n    if (setClauses.length === 0) {\n      throw new Error(\"No update operations specified\");\n    }\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter, paramIndex);\n    params.push(...whereParams);\n\n    let sql = `UPDATE ${quotedTable} SET ${setClauses.join(\", \")} ${whereClause}`;\n\n    // For single row update, use ctid subquery\n    if (limit === 1 && whereClause) {\n      sql = `UPDATE ${quotedTable} SET ${setClauses.join(\", \")} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;\n    }\n\n    return { sql, params };\n  }\n\n  // ============================================================\n  // Database Lifecycle Operations\n  // ============================================================\n\n  /**\n   * Create a new database.\n   *\n   * Note: This requires connecting to a system database (like 'postgres')\n   * since you cannot create a database while connected to it.\n   *\n   * @param name - Database name to create\n   * @param options - Creation options (encoding, template, etc.)\n   * @returns true if created, false if already exists\n   */\n  public async createDatabase(name: string, options?: CreateDatabaseOptions): Promise<boolean> {\n    // Check if database already exists\n    if (await this.databaseExists(name)) {\n      return false;\n    }\n\n    // Build CREATE DATABASE statement\n    const quotedName = this.dialect.quoteIdentifier(name);\n    let sql = `CREATE DATABASE ${quotedName}`;\n\n    const withClauses: string[] = [];\n\n    if (options?.encoding) {\n      withClauses.push(`ENCODING = '${options.encoding}'`);\n    }\n    if (options?.template) {\n      withClauses.push(`TEMPLATE = ${this.dialect.quoteIdentifier(options.template)}`);\n    }\n    if (options?.locale) {\n      withClauses.push(`LC_COLLATE = '${options.locale}'`);\n      withClauses.push(`LC_CTYPE = '${options.locale}'`);\n    }\n    if (options?.owner) {\n      withClauses.push(`OWNER = ${this.dialect.quoteIdentifier(options.owner)}`);\n    }\n\n    if (withClauses.length > 0) {\n      sql += ` WITH ${withClauses.join(\" \")}`;\n    }\n\n    try {\n      await this.query(sql);\n      log.success(\"database\", \"lifecycle\", `Created database ${name}`);\n      return true;\n    } catch (error) {\n      log.error(\"database\", \"lifecycle\", `Failed to create database ${name}: ${error}`);\n      throw error;\n    }\n  }\n\n  /**\n   * Drop a database.\n   *\n   * @param name - Database name to drop\n   * @param options - Drop options\n   * @returns true if dropped, false if didn't exist\n   */\n  public async dropDatabase(name: string, options?: DropDatabaseOptions): Promise<boolean> {\n    // Check if database exists first (if ifExists option not set)\n    if (!options?.ifExists && !(await this.databaseExists(name))) {\n      return false;\n    }\n\n    const quotedName = this.dialect.quoteIdentifier(name);\n    let sql = \"DROP DATABASE\";\n\n    if (options?.ifExists) {\n      sql += \" IF EXISTS\";\n    }\n\n    sql += ` ${quotedName}`;\n\n    // PostgreSQL 13+ supports WITH (FORCE) to terminate active connections\n    if (options?.force) {\n      sql += \" WITH (FORCE)\";\n    }\n\n    try {\n      await this.query(sql);\n      log.success(\"database\", \"lifecycle\", `Dropped database ${name}`);\n      return true;\n    } catch (error) {\n      log.error(\"database\", \"lifecycle\", `Failed to drop database ${name}: ${error}`);\n      throw error;\n    }\n  }\n\n  /**\n   * Check if a database exists.\n   *\n   * @param name - Database name to check\n   * @returns true if database exists\n   */\n  public async databaseExists(name: string): Promise<boolean> {\n    const result = await this.query<{ exists: boolean }>(\n      `SELECT EXISTS(SELECT 1 FROM pg_database WHERE datname = $1) as exists`,\n      [name],\n    );\n\n    return result.rows[0]?.exists ?? false;\n  }\n\n  /**\n   * List all databases.\n   *\n   * @returns Array of database names\n   */\n  public async listDatabases(): Promise<string[]> {\n    const result = await this.query<{ datname: string }>(\n      `SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname`,\n    );\n\n    return result.rows.map((row) => row.datname);\n  }\n\n  // ============================================================\n  // Table Management Operations\n  // ============================================================\n\n  /**\n   * Drop a table.\n   *\n   * @param name - Table name to drop\n   * @throws Error if table doesn't exist\n   */\n  public async dropTable(name: string): Promise<void> {\n    const quotedName = this.dialect.quoteIdentifier(name);\n    await this.query(`DROP TABLE ${quotedName}`);\n    log.success(\"database\", \"table\", `Dropped table ${name}`);\n  }\n\n  /**\n   * Drop a table if it exists.\n   *\n   * @param name - Table name to drop\n   */\n  public async dropTableIfExists(name: string): Promise<void> {\n    const quotedName = this.dialect.quoteIdentifier(name);\n    await this.query(`DROP TABLE IF EXISTS ${quotedName}`);\n  }\n\n  /**\n   * Drop all tables in the current database.\n   *\n   * Uses CASCADE to handle foreign key dependencies.\n   * Useful for `migrate:fresh` command.\n   */\n  public async dropAllTables(): Promise<void> {\n    // Get all tables from blueprint\n    const tables = await this.blueprint.listTables();\n\n    if (tables.length === 0) {\n      return;\n    }\n\n    // Drop all tables with CASCADE to handle foreign keys\n    for (const table of tables) {\n      const quotedName = this.dialect.quoteIdentifier(table);\n      await this.query(`DROP TABLE IF EXISTS ${quotedName} CASCADE`);\n    }\n\n    log.success(\"database\", \"table\", `Dropped ${tables.length} tables`);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"postgres-driver.mjs","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/drivers/postgres/postgres-driver.ts"],"sourcesContent":["/**\n * PostgreSQL Driver\n *\n * Main driver implementation for PostgreSQL database operations.\n * Implements the DriverContract interface to provide a unified API\n * for CRUD operations, transactions, and query building.\n *\n * Uses the `pg` package for database connectivity with connection pooling.\n *\n * @module cascade/drivers/postgres\n */\n\nimport { colors } from \"@mongez/copper\";\nimport { log } from \"@warlock.js/logger\";\nimport { databaseTransactionContext } from \"../../context/database-transaction-context\";\nimport type {\n  CreateDatabaseOptions,\n  DriverContract,\n  DriverEventListener,\n  DriverTransactionContract,\n  DropDatabaseOptions,\n  InsertResult,\n  TransactionContext,\n  UpdateOperations,\n  UpdateResult,\n} from \"../../contracts/database-driver.contract\";\nimport type { DriverBlueprintContract } from \"../../contracts/driver-blueprint.contract\";\nimport type { MigrationDriverContract } from \"../../contracts/migration-driver.contract\";\nimport type { QueryBuilderContract } from \"../../contracts/query-builder.contract\";\nimport type { SyncAdapterContract } from \"../../contracts/sync-adapter.contract\";\nimport { TransactionRollbackError } from \"../../errors/transaction-rollback.error\";\nimport { SQLSerializer } from \"../../migration/sql-serializer\";\nimport { SqlDatabaseDirtyTracker } from \"../../sql-database-dirty-tracker\";\nimport type { ModelDefaults } from \"../../types\";\nimport { DatabaseDriver } from \"../../utils/connect-to-database\";\nimport { isValidDateValue } from \"../../utils/is-valid-date-value\";\nimport { PostgresBlueprint } from \"./postgres-blueprint\";\nimport { PostgresDialect } from \"./postgres-dialect\";\nimport { PostgresMigrationDriver } from \"./postgres-migration-driver\";\nimport { PostgresQueryBuilder } from \"./postgres-query-builder\";\nimport { PostgresSQLSerializer } from \"./postgres-sql-serializer\";\nimport { PostgresSyncAdapter } from \"./postgres-sync-adapter\";\nimport type { PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions } from \"./types\";\n\n/**\n * Lazily loaded pg module types.\n */\ntype PgPool = import(\"pg\").Pool;\ntype PgPoolClient = import(\"pg\").PoolClient;\ntype PgPoolConfig = import(\"pg\").PoolConfig;\n\n/**\n * Cached pg module reference.\n */\nlet pgModule: typeof import(\"pg\") | undefined;\n\n/**\n * Lazily load the pg package.\n *\n * @returns The pg module\n * @throws Error if pg is not installed\n */\nasync function loadPg(): Promise<typeof import(\"pg\")> {\n  if (pgModule) {\n    return pgModule;\n  }\n\n  try {\n    pgModule = await import(\"pg\");\n    return pgModule;\n  } catch {\n    throw new Error(\n      'The \"pg\" package is required for PostgreSQL support. ' + \"Please install it: npm install pg\",\n    );\n  }\n}\n\n/**\n * PostgreSQL database driver implementing the Cascade DriverContract.\n *\n * Provides connection pooling, CRUD operations, transactions, and\n * integration with Cascade's query builder and migration systems.\n *\n * @example\n * ```typescript\n * const driver = new PostgresDriver({\n *   host: 'localhost',\n *   port: 5432,\n *   database: 'myapp',\n *   user: 'postgres',\n *   password: 'secret'\n * });\n *\n * await driver.connect();\n *\n * // Insert a document\n * const result = await driver.insert('users', { name: 'Alice', email: 'alice@example.com' });\n *\n * // Query using the query builder\n * const users = await driver.queryBuilder('users')\n *   .where('name', 'Alice')\n *   .get();\n *\n * await driver.disconnect();\n * ```\n */\nexport class PostgresDriver implements DriverContract {\n  /**\n   * Driver name identifier.\n   */\n  public readonly name = \"postgres\" as DatabaseDriver;\n\n  /**\n   * SQL dialect for PostgreSQL-specific syntax.\n   */\n  public readonly dialect = new PostgresDialect();\n\n  /**\n   * PostgreSQL driver model defaults.\n   *\n   * PostgreSQL follows SQL conventions:\n   * - snake_case naming for columns (created_at, updated_at, deleted_at)\n   * - Native AUTO_INCREMENT for IDs (no manual generation)\n   * - Timestamps enabled by default\n   * - Permanent delete strategy (hard deletes)\n   */\n  public readonly modelDefaults: Partial<ModelDefaults> = {\n    namingConvention: \"snake_case\",\n    createdAtColumn: \"created_at\",\n    updatedAtColumn: \"updated_at\",\n    deletedAtColumn: \"deleted_at\",\n    timestamps: true,\n    autoGenerateId: false, // PostgreSQL uses SERIAL/BIGSERIAL\n    strictMode: \"fail\",\n    deleteStrategy: \"permanent\",\n  };\n\n  /**\n   * Connection pool instance.\n   */\n  private _pool: PgPool | undefined;\n\n  /**\n   * Event listeners for driver lifecycle events.\n   */\n  private readonly _eventListeners = new Map<string, Set<DriverEventListener>>();\n\n  /**\n   * Whether the driver is currently connected.\n   */\n  private _isConnected = false;\n\n  /**\n   * Blueprint instance (lazy-loaded).\n   */\n  private _blueprint: DriverBlueprintContract | undefined;\n\n  /**\n   * Migration driver instance (lazy-loaded).\n   */\n  private _migrationDriver: MigrationDriverContract | undefined;\n\n  /**\n   * Sync adapter instance (lazy-loaded).\n   */\n  private _syncAdapter: SyncAdapterContract | undefined;\n\n  /**\n   * Explicit, table-agnostic override list of column names that hold native\n   * PostgreSQL arrays (`JSONB[]`, `TEXT[]`, …) and must NOT be JSON-text\n   * encoded. Merged with (and superseded per-table by) the schema\n   * introspection below; kept as a manual escape hatch.\n   *\n   * @see PostgresPoolConfig.nativeArrayColumns\n   */\n  private readonly _nativeArrayColumns: ReadonlySet<string>;\n\n  /**\n   * Native-array columns discovered by introspecting the live schema on\n   * connect, keyed `table → { column, … }`. Authoritative and table-scoped, so\n   * a column that is `TEXT[]` in one table and `jsonb` in another is encoded\n   * correctly for each — no app configuration required.\n   */\n  private _introspectedArrayColumns: ReadonlyMap<string, ReadonlySet<string>> = new Map();\n\n  /**\n   * Create a new PostgreSQL driver instance.\n   *\n   * @param config - PostgreSQL connection configuration\n   */\n  public constructor(private readonly config: PostgresPoolConfig) {\n    this._nativeArrayColumns = new Set(config.nativeArrayColumns ?? []);\n  }\n\n  /**\n   * Get the connection pool instance.\n   *\n   * @throws Error if not connected\n   */\n  public get pool(): PgPool {\n    if (!this._pool) {\n      throw new Error(\"PostgreSQL driver is not connected. Call connect() first.\");\n    }\n    return this._pool;\n  }\n\n  /**\n   * Get database native client\n   */\n  public getClient<Client = PgPool>(): Client {\n    return this.pool as Client;\n  }\n\n  /**\n   * Check if the driver is currently connected.\n   */\n  public get isConnected(): boolean {\n    return this._isConnected;\n  }\n\n  /**\n   * Get the driver blueprint (information schema).\n   */\n  public get blueprint(): DriverBlueprintContract {\n    if (!this._blueprint) {\n      this._blueprint = new PostgresBlueprint(this);\n    }\n    return this._blueprint;\n  }\n\n  /**\n   * Establish connection to the PostgreSQL database.\n   *\n   * Creates a connection pool with the configured options.\n   * Emits 'connected' event on successful connection.\n   */\n  public async connect(): Promise<void> {\n    if (this._isConnected) {\n      return;\n    }\n\n    const pg = await loadPg();\n\n    try {\n      const poolConfig: PgPoolConfig = {\n        host: this.config.host ?? \"localhost\",\n        port: this.config.port ?? 5432,\n        database: this.config.database,\n        user: this.config.user,\n        password: this.config.password,\n        connectionString: this.config.connectionString,\n        max: this.config.max ?? 10,\n        min: this.config.min ?? 0,\n        idleTimeoutMillis: this.config.idleTimeoutMillis ?? 30000,\n        connectionTimeoutMillis: this.config.connectionTimeoutMillis ?? 2000,\n        application_name: this.config.application_name ?? \"cascade\",\n        ssl: this.config.ssl,\n      };\n\n      log.info(\n        \"database.postgres\",\n        \"connection\",\n        `Connecting to database ${colors.bold(colors.yellowBright(this.config.database))}`,\n      );\n\n      this._pool = new pg.Pool(poolConfig);\n\n      // Test the connection\n      const client = await this._pool.connect();\n      client.release();\n\n      log.success(\n        \"database.postgres\",\n        \"connection\",\n        `Connected to database ${colors.bold(colors.yellowBright(this.config.database))}`,\n      );\n\n      this._isConnected = true;\n\n      // Learn which columns are native arrays straight from the live schema so\n      // the value serializer encodes them correctly with zero app config.\n      await this.loadNativeArrayColumns();\n\n      this.emit(\"connected\");\n    } catch (error) {\n      // Boot-time database connection failure is unrecoverable in every\n      // realistic caller (app boot, CLI migrations, workers) — `fatal` makes\n      // \"page on fatal only\" alerting clean. Per-query failures stay at error.\n      log.fatal(\"database.postgres\", \"connection\", \"Failed to connect to database\");\n      throw error;\n    }\n  }\n\n  /**\n   * Close the database connection pool.\n   *\n   * Waits for all active queries to complete before closing.\n   * Emits 'disconnected' event on successful disconnection.\n   */\n  public async disconnect(): Promise<void> {\n    if (!this._isConnected || !this._pool) {\n      return;\n    }\n\n    await this._pool.end();\n    this._pool = undefined;\n    this._isConnected = false;\n    this.emit(\"disconnected\");\n  }\n\n  /**\n   * Register an event listener for driver lifecycle events.\n   *\n   * @param event - Event name ('connected', 'disconnected', etc.)\n   * @param listener - Callback function to invoke\n   */\n  public on(event: string, listener: DriverEventListener): void {\n    if (!this._eventListeners.has(event)) {\n      this._eventListeners.set(event, new Set());\n    }\n\n    this._eventListeners.get(event)!.add(listener);\n  }\n\n  /**\n   * Serialize data for storage in PostgreSQL.\n   *\n   * Handles Date objects, BigInt, and other JavaScript types\n   * that need special handling for PostgreSQL storage.\n   *\n   * @param data - The data object to serialize\n   * @param table - Optional table name; when given, columns introspected as\n   *   native arrays on that table are bound raw (see {@link serializeValue}).\n   * @returns Serialized data ready for PostgreSQL\n   */\n  public serialize(\n    data: Record<string, unknown>,\n    table?: string,\n  ): Record<string, unknown> {\n    const serialized: Record<string, unknown> = {};\n\n    for (const [key, value] of Object.entries(data)) {\n      if (value === undefined) {\n        continue; // Skip undefined values\n      }\n\n      serialized[key] = this.serializeValue(key, value, table);\n    }\n\n    return serialized;\n  }\n\n  /**\n   * Serialize a single column value into a node-pg bindable parameter.\n   *\n   * Shared by {@link serialize} (INSERT path) and {@link buildUpdateQuery}\n   * `$set` (UPDATE path) so both encode `json` / `jsonb` columns identically.\n   *\n   * Encoding rules (in order):\n   * - `Date` → ISO string.\n   * - `bigint` → decimal string (node-pg has no native bigint binding).\n   * - all-number array → pgvector literal `'[n1,n2,...]'`. node-pg would\n   *   otherwise emit a `{n1,n2,...}` array literal, which the `vector` type\n   *   rejects. This branch is preserved exactly.\n   * - any other array (object-array, string-array, mixed, empty `[]`) →\n   *   `JSON.stringify`. node-pg renders a raw JS array as a PostgreSQL array\n   *   literal `{...}` (and `[]` as `{}`), which a `json` / `jsonb` column\n   *   rejects — so we bind the value as JSON text instead, the form those\n   *   columns accept. Columns known to be native arrays — via schema\n   *   introspection or the `nativeArrayColumns` config — are exempt: their raw\n   *   array is passed through so node-pg emits the `{...}` literal a genuine\n   *   `JSONB[]` / `TEXT[]` column needs.\n   * - plain object → `JSON.stringify`. Equivalent to node-pg's own object\n   *   handling, made explicit so both write paths agree.\n   * - everything else (scalars: string, number, boolean, null) → untouched.\n   *\n   * Distinguishing native-array from `json` / `jsonb` columns: a value alone\n   * can't tell them apart, so the driver introspects the live schema on connect\n   * (see {@link loadNativeArrayColumns}) and consults that per-table map here\n   * via {@link isNativeArrayColumn}. The explicit `nativeArrayColumns` config\n   * still works as a table-agnostic override. No `::jsonb` placeholder cast is\n   * added: a JSON-text string binds correctly to `json` / `jsonb` without one,\n   * and a blind cast would misfire on columns we cannot positively identify as\n   * jsonb.\n   *\n   * @param key - Column name (used to resolve native-array columns)\n   * @param value - The raw value to serialize (never `undefined`)\n   * @param table - Optional table name; enables the per-table native-array lookup\n   * @returns The value ready to bind as a query parameter\n   */\n  private serializeValue(key: string, value: unknown, table?: string): unknown {\n    if (value instanceof Date) {\n      return value.toISOString();\n    }\n\n    if (typeof value === \"bigint\") {\n      return value.toString();\n    }\n\n    if (Array.isArray(value)) {\n      if (value.length > 0 && value.every((v) => typeof v === \"number\")) {\n        // pgvector columns expect the literal '[n1,n2,...]' format.\n        return `[${value.join(\",\")}]`;\n      }\n\n      // Genuine native PostgreSQL array columns (JSONB[], TEXT[], …) must\n      // keep their raw array so node-pg emits a '{...}' array literal.\n      if (this.isNativeArrayColumn(table, key)) {\n        return value;\n      }\n\n      // json / jsonb columns: bind as JSON text. Covers object-arrays,\n      // string-arrays, mixed arrays, and empty [] (which would otherwise\n      // store as '{}' instead of '[]').\n      return JSON.stringify(value);\n    }\n\n    if (typeof value === \"object\" && value !== null) {\n      // Plain object → JSONB. Explicit JSON.stringify matches node-pg's own\n      // object encoding while keeping both write paths consistent.\n      return JSON.stringify(value);\n    }\n\n    return value;\n  }\n\n  /**\n   * Whether `column` on `table` is a native PostgreSQL array. True when the\n   * connect-time schema introspection saw it as `data_type = 'ARRAY'` for that\n   * table (authoritative, per-table), or when it's listed in the table-agnostic\n   * `nativeArrayColumns` config override.\n   */\n  private isNativeArrayColumn(table: string | undefined, column: string): boolean {\n    if (table && this._introspectedArrayColumns.get(table)?.has(column)) {\n      return true;\n    }\n\n    return this._nativeArrayColumns.has(column);\n  }\n\n  /**\n   * Introspect the live schema for native-array columns so array values bind\n   * correctly with zero app configuration.\n   *\n   * A JS array must be bound two opposite ways depending on the column: as JSON\n   * text for a `json` / `jsonb` column, but as a raw array (which node-pg\n   * renders `{...}`) for a native `TEXT[]` / `JSONB[]` / `INTEGER[]` column. The\n   * serializer sees values, not types, so without this it JSON-stringifies\n   * every array — which a native-array column rejects with \"malformed array\n   * literal\". One `information_schema` query at connect, cached for the\n   * connection lifetime, removes the need to hand-list `nativeArrayColumns`.\n   *\n   * Best-effort: any failure (e.g. restricted catalog access) is logged and\n   * leaves the map empty so the config override still applies — it never blocks\n   * connect. A schema change made within a live connection isn't reflected\n   * until the next connect.\n   */\n  private async loadNativeArrayColumns(): Promise<void> {\n    try {\n      const result = await this.query<{ table_name: string; column_name: string }>(\n        `SELECT table_name, column_name\n         FROM information_schema.columns\n         WHERE table_schema = ANY (current_schemas(false))\n           AND data_type = 'ARRAY'`,\n      );\n\n      const map = new Map<string, Set<string>>();\n\n      for (const { table_name, column_name } of result.rows) {\n        let columns = map.get(table_name);\n\n        if (!columns) {\n          columns = new Set<string>();\n          map.set(table_name, columns);\n        }\n\n        columns.add(column_name);\n      }\n\n      this._introspectedArrayColumns = map;\n    } catch {\n      // Introspection is an optimization, never a hard dependency — fall back\n      // to the `nativeArrayColumns` config so a locked-down catalog or an\n      // unusual search_path can't break connect.\n      log.warn(\n        \"database.postgres\",\n        \"introspection\",\n        \"Could not introspect native-array columns; using the nativeArrayColumns config only\",\n      );\n    }\n  }\n\n  /**\n   * Get the dirty tracker for this driver.\n   */\n  public getDirtyTracker(data: Record<string, unknown>): SqlDatabaseDirtyTracker {\n    return new SqlDatabaseDirtyTracker(data);\n  }\n\n  /**\n   * Deserialize data retrieved from PostgreSQL.\n   *\n   * Converts PostgreSQL types back to JavaScript equivalents.\n   *\n   * @param data - The data object from PostgreSQL\n   * @returns Deserialized JavaScript object\n   */\n  public deserialize(data: Record<string, unknown>): Record<string, unknown> {\n    // PostgreSQL pg driver handles most type conversions automatically\n    // Special handling can be added here if needed\n    for (const [key, value] of Object.entries(data)) {\n      // Only re-inflate strings — pg already returns Date objects from DB reads\n      if (typeof value !== \"string\") continue;\n\n      if (isValidDateValue(value)) {\n        data[key] = new Date(value);\n        continue;\n      }\n\n      // pgvector columns are returned as '[n1,n2,...]' strings.\n      // charCodeAt is faster than startsWith/endsWith — no string allocation.\n      // '[' = 91, ']' = 93\n      if (value.charCodeAt(0) === 91 && value.charCodeAt(value.length - 1) === 93) {\n        const parts = value.slice(1, -1).split(\",\");\n        const nums = new Array<number>(parts.length);\n        let isNumericVector = parts.length > 0;\n\n        for (let i = 0; i < parts.length; i++) {\n          const n = +parts[i]; // unary + is the fastest string-to-number coercion\n          if (!Number.isFinite(n)) {\n            isNumericVector = false;\n            break; // early-exit — not a numeric vector, leave value untouched\n          }\n          nums[i] = n;\n        }\n\n        if (isNumericVector) {\n          data[key] = nums;\n        }\n      }\n    }\n\n    return data;\n  }\n\n  /**\n   * Insert a single row into a table.\n   *\n   * Uses INSERT ... RETURNING to get the inserted row with generated values.\n   *\n   * @param table - Target table name\n   * @param document - Data to insert\n   * @param options - Optional insertion options\n   * @returns The inserted document\n   */\n  public async insert(\n    table: string,\n    document: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<InsertResult> {\n    const serialized = this.serialize(document, table);\n\n    // Filter out id if null/undefined to let PostgreSQL SERIAL auto-generate\n    const filteredData = Object.fromEntries(\n      Object.entries(serialized).filter(([key, value]) => {\n        // Exclude id if null/undefined (let SERIAL handle it)\n        if (key === \"id\" && (value === null || value === undefined)) {\n          return false;\n        }\n        return true;\n      }),\n    );\n\n    const columns = Object.keys(filteredData);\n    const values = Object.values(filteredData);\n\n    if (columns.length === 0) {\n      throw new Error(\"Cannot insert empty document\");\n    }\n\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const placeholders = columns.map((_, i) => this.dialect.placeholder(i + 1)).join(\", \");\n    const quotedTable = this.dialect.quoteIdentifier(table);\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES (${placeholders}) RETURNING *`;\n\n    const result = await this.query<Record<string, unknown>>(sql, values);\n\n    return {\n      document: result.rows[0],\n    };\n  }\n\n  /**\n   * Insert multiple rows into a table.\n   *\n   * Uses a single INSERT statement with multiple value sets for efficiency.\n   *\n   * @param table - Target table name\n   * @param documents - Array of documents to insert\n   * @param options - Optional insertion options\n   * @returns Array of inserted documents\n   */\n  public async insertMany(\n    table: string,\n    documents: Record<string, unknown>[],\n    _options?: Record<string, unknown>,\n  ): Promise<InsertResult[]> {\n    if (documents.length === 0) {\n      return [];\n    }\n\n    // Get all unique columns across all documents\n    const allColumns = new Set<string>();\n    for (const doc of documents) {\n      const serialized = this.serialize(doc, table);\n      Object.keys(serialized).forEach((key) => allColumns.add(key));\n    }\n    const columns = Array.from(allColumns);\n\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const quotedTable = this.dialect.quoteIdentifier(table);\n\n    // Build value sets and params\n    const valueSets: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = 1;\n\n    for (const doc of documents) {\n      const serialized = this.serialize(doc, table);\n      const rowPlaceholders: string[] = [];\n\n      for (const col of columns) {\n        if (col in serialized) {\n          rowPlaceholders.push(this.dialect.placeholder(paramIndex++));\n          params.push(serialized[col]);\n        } else {\n          rowPlaceholders.push(\"DEFAULT\");\n        }\n      }\n\n      valueSets.push(`(${rowPlaceholders.join(\", \")})`);\n    }\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES ${valueSets.join(\", \")} RETURNING *`;\n\n    const result = await this.query<Record<string, unknown>>(sql, params);\n\n    return result.rows as unknown as InsertResult[];\n  }\n\n  /**\n   * Update a single row matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations ($set, $unset, $inc)\n   * @param options - Optional update options\n   * @returns Update result with modified count\n   */\n  public async update(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update, 1);\n    try {\n      const result = await this.query(sql, params);\n\n      return {\n        modifiedCount: result.rowCount ?? 0,\n      };\n    } catch (error) {\n      console.log(\"PG Query Error in:\", sql, params);\n\n      throw error;\n    }\n  }\n\n  /**\n   * Find one and update a single row matching the filter and return the updated row\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations ($set, $unset, $inc)\n   * @param options - Optional update options\n   * @returns The updated row or null\n   */\n  public async findOneAndUpdate<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update, 1);\n    // Add RETURNING * to get the updated row back\n    const sqlWithReturning = `${sql} RETURNING *`;\n    const result = await this.query<T>(sqlWithReturning, params);\n    return result.rows[0] ?? null;\n  }\n\n  /**\n   * Update multiple rows matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations\n   * @param options - Optional update options\n   * @returns Update result with modified count\n   */\n  public async updateMany(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, update);\n\n    const result = await this.query(sql, params);\n\n    return {\n      modifiedCount: result.rowCount ?? 0,\n    };\n  }\n\n  /**\n   * Replace a document matching the filter.\n   *\n   * Completely replaces the document (not a partial update).\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param document - New document data\n   * @param options - Optional options\n   * @returns The replaced document or null\n   */\n  public async replace<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    document: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const serialized = this.serialize(document, table);\n    const columns = Object.keys(serialized);\n    const values = Object.values(serialized);\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const setClauses = columns\n      .map((col, i) => `${this.dialect.quoteIdentifier(col)} = ${this.dialect.placeholder(i + 1)}`)\n      .join(\", \");\n\n    const { whereClause, whereParams } = this.buildWhereClause(filter, columns.length + 1);\n\n    const sql = `UPDATE ${quotedTable} SET ${setClauses} ${whereClause} RETURNING *`;\n    const params = [...values, ...whereParams];\n\n    const result = await this.query<T>(sql, params);\n\n    return result.rows[0] ?? null;\n  }\n\n  /**\n   * Upsert (insert or update) a single row.\n   *\n   * Uses PostgreSQL's INSERT ... ON CONFLICT ... DO UPDATE syntax.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions to find existing row (used for conflict detection)\n   * @param document - Document data to insert or update\n   * @param options - Upsert options (conflictColumns for conflict target)\n   * @returns The upserted row\n   */\n  public async upsert<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    document: Record<string, unknown>,\n    options?: Record<string, unknown>,\n  ): Promise<T> {\n    const serialized = this.serialize(document, table);\n    const columns = Object.keys(serialized);\n    const values = Object.values(serialized);\n\n    if (columns.length === 0) {\n      throw new Error(\"Cannot upsert empty document\");\n    }\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const quotedColumns = columns.map((c) => this.dialect.quoteIdentifier(c)).join(\", \");\n    const placeholders = columns.map((_, i) => this.dialect.placeholder(i + 1)).join(\", \");\n\n    // Determine conflict columns from options or filter\n    const conflictColumns = (options?.conflictColumns as string[]) ?? Object.keys(filter);\n    if (conflictColumns.length === 0) {\n      throw new Error(\"Upsert requires conflictColumns option or filter with columns\");\n    }\n\n    const quotedConflictColumns = conflictColumns\n      .map((c) => this.dialect.quoteIdentifier(c))\n      .join(\", \");\n\n    // Build UPDATE clause for ON CONFLICT\n    // Update all columns except the conflict columns (they stay the same)\n    const updateColumns = columns.filter((col) => !conflictColumns.includes(col));\n    const setClauses = updateColumns\n      .map((col, i) => {\n        const valueIndex = columns.indexOf(col) + 1;\n        return `${this.dialect.quoteIdentifier(col)} = ${this.dialect.placeholder(valueIndex)}`;\n      })\n      .join(\", \");\n\n    // If there are no columns to update (all columns are conflict columns), use EXCLUDED\n    const updateClause =\n      setClauses.length > 0\n        ? setClauses\n        : columns\n            .map(\n              (col) =>\n                `${this.dialect.quoteIdentifier(col)} = EXCLUDED.${this.dialect.quoteIdentifier(col)}`,\n            )\n            .join(\", \");\n\n    const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES (${placeholders}) ON CONFLICT (${quotedConflictColumns}) DO UPDATE SET ${updateClause} RETURNING *`;\n\n    const result = await this.query<T>(sql, values);\n\n    return result.rows[0]! as T;\n  }\n\n  /**\n   * Find one and delete a single row matching the filter and return the deleted row.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional delete options\n   * @returns The deleted row or null\n   */\n  public async findOneAndDelete<T = unknown>(\n    table: string,\n    filter: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<T | null> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter, 1);\n\n    // Use ctid for single row deletion with RETURNING\n    const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1) RETURNING *`;\n\n    const result = await this.query<T>(sql, whereParams);\n\n    return result.rows[0] ? (result.rows[0] as T) : null;\n  }\n\n  /**\n   * Delete a single row matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional options\n   * @returns Number of deleted rows (0 or 1)\n   */\n  public async delete(\n    table: string,\n    filter?: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter ?? {}, 1);\n\n    // Use ctid for single row deletion\n    const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;\n\n    const result = await this.query(sql, whereParams);\n\n    return result.rowCount ?? 0;\n  }\n\n  /**\n   * Delete multiple rows matching the filter.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param options - Optional options\n   * @returns Number of deleted rows\n   */\n  public async deleteMany(\n    table: string,\n    filter?: Record<string, unknown>,\n    _options?: Record<string, unknown>,\n  ): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter ?? {}, 1);\n\n    const sql = `DELETE FROM ${quotedTable} ${whereClause}`;\n\n    const result = await this.query(sql, whereParams);\n\n    return result.rowCount ?? 0;\n  }\n\n  /**\n   * Truncate a table (remove all rows).\n   *\n   * Uses TRUNCATE TABLE for fast deletion with RESTART IDENTITY.\n   *\n   * @param table - Target table name\n   * @param options - Optional options\n   * @param options.cascade - If true, automatically truncate all tables with foreign key references (use with caution)\n   * @returns Number of deleted rows (always 0 for TRUNCATE)\n   */\n  public async truncateTable(table: string, options?: { cascade?: boolean }): Promise<number> {\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const cascadeClause = options?.cascade ? \" CASCADE\" : \"\";\n    await this.query(`TRUNCATE TABLE ${quotedTable} RESTART IDENTITY${cascadeClause}`);\n    return 0; // TRUNCATE doesn't return row count\n  }\n\n  /**\n   * Get a query builder for the specified table.\n   *\n   * @param table - Target table name\n   * @returns Query builder instance\n   */\n  public queryBuilder<T = unknown>(table: string): QueryBuilderContract<T> {\n    return new PostgresQueryBuilder<T>(table) as unknown as QueryBuilderContract<T>;\n  }\n\n  /**\n   * Begin a new database transaction.\n   *\n   * Acquires a client from the pool and starts a transaction.\n   * The client is stored in AsyncLocalStorage for automatic\n   * participation by subsequent queries.\n   *\n   * @param options - Optional transaction options\n   * @returns Transaction contract with commit/rollback methods\n   */\n  public async beginTransaction(\n    options?: PostgresTransactionOptions,\n  ): Promise<DriverTransactionContract<PgPoolClient>> {\n    const client = await this.pool.connect();\n\n    let beginSql = \"BEGIN\";\n    if (options?.isolationLevel) {\n      beginSql += ` ISOLATION LEVEL ${options.isolationLevel.toUpperCase()}`;\n    }\n    if (options?.readOnly) {\n      beginSql += \" READ ONLY\";\n    }\n    if (options?.deferrable) {\n      beginSql += \" DEFERRABLE\";\n    }\n\n    await client.query(beginSql);\n\n    return {\n      context: client,\n      commit: async () => {\n        await client.query(\"COMMIT\");\n        client.release();\n      },\n      rollback: async () => {\n        await client.query(\"ROLLBACK\");\n        client.release();\n      },\n    };\n  }\n\n  /**\n   * Execute a function within a transaction scope (recommended pattern).\n   *\n   * Automatically commits on success, rolls back on any error, and guarantees\n   * resource cleanup. This is the recommended way to use transactions.\n   *\n   * @param fn - Async function to execute within transaction\n   * @param options - Transaction options (isolation level, read-only, etc.)\n   * @returns The return value of the callback function\n   * @throws {Error} If transaction fails or is explicitly rolled back\n   */\n  public async transaction<T>(\n    fn: (ctx: TransactionContext) => Promise<T>,\n    options?: Record<string, unknown>,\n  ): Promise<T> {\n    const ctx: TransactionContext = {\n      rollback(reason?: string): never {\n        throw new TransactionRollbackError(reason);\n      },\n    };\n\n    // Flat nesting: a transaction() called while one is already active JOINS it\n    // instead of opening a second, independent transaction on another pool\n    // connection. An independent inner transaction can't see the outer's\n    // uncommitted writes (a row inserted moments earlier), so a service that\n    // opens its own transaction — correct when called standalone — would hit\n    // phantom FK violations when called inside an outer transaction (e.g. a\n    // seeder that creates a row, then calls a service that references it). The\n    // outermost transaction owns BEGIN / COMMIT / ROLLBACK; the inner block\n    // runs on the same session, and a throw still unwinds the whole outer\n    // transaction. (Savepoint-based partial rollback is a separate, explicit\n    // concern — use `beginTransaction()` directly for that.)\n    if (databaseTransactionContext.hasActiveTransaction()) {\n      return fn(ctx);\n    }\n\n    const tx = await this.beginTransaction(options);\n\n    // Set transaction context for queries within callback\n    databaseTransactionContext.enter({ session: tx.context });\n\n    try {\n      // Execute callback\n      const result = await fn(ctx);\n\n      // Auto-commit on success\n      await tx.commit();\n\n      return result;\n    } catch (error) {\n      // Auto-rollback on any error (including explicit rollback)\n      await tx.rollback();\n      log.error(\n        `database.postgress`,\n        \"transaction\",\n        \"Transaction operation failed, rolled back everything\",\n      );\n      throw error;\n    } finally {\n      // Guaranteed cleanup\n      databaseTransactionContext.exit();\n    }\n  }\n\n  /**\n   * Perform an atomic update operation.\n   *\n   * Builds and executes an UPDATE query for the given filter and operations.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param operations - Update operations\n   * @param options - Optional options\n   * @returns Update result\n   */\n  public async atomic(\n    table: string,\n    filter: Record<string, unknown>,\n    operations: UpdateOperations,\n    _options?: Record<string, unknown>,\n  ): Promise<UpdateResult> {\n    const { sql, params } = this.buildUpdateQuery(table, filter, operations, 1);\n\n    const result = await this.query(sql, params);\n\n    return {\n      modifiedCount: result.rowCount ?? 0,\n    };\n  }\n\n  /**\n   * Get the sync adapter for bulk denormalized updates.\n   *\n   * @returns Sync adapter instance\n   */\n  public syncAdapter(): SyncAdapterContract {\n    if (!this._syncAdapter) {\n      this._syncAdapter = new PostgresSyncAdapter(this);\n    }\n    return this._syncAdapter;\n  }\n\n  /**\n   * Get the migration driver for schema operations.\n   *\n   * @returns Migration driver instance\n   */\n  public migrationDriver(): MigrationDriverContract {\n    if (!this._migrationDriver) {\n      this._migrationDriver = new PostgresMigrationDriver(this);\n    }\n\n    return this._migrationDriver;\n  }\n\n  /**\n   * Return a SQL serializer for this driver's dialect.\n   * Used by Migration.toSQL() to convert pending operations to SQL strings.\n   */\n  public getSQLSerializer(): SQLSerializer {\n    return new PostgresSQLSerializer(this.dialect);\n  }\n\n  /**\n   * Execute a raw SQL query.\n   *\n   * Automatically uses the transaction client if one is active.\n   *\n   * @param sql - SQL query string\n   * @param params - Query parameters\n   * @returns Query result\n   */\n  public async query<T = Record<string, unknown>>(\n    sql: string,\n    params: unknown[] = [],\n  ): Promise<PostgresQueryResult<T>> {\n    // Check for active transaction client\n    const txClient = databaseTransactionContext.getSession() as PgPoolClient | undefined;\n\n    const startTime = this.config.logging ? performance.now() : 0;\n\n    let paramsString = \"\";\n    if (this.config.logging && params.length > 0) {\n      paramsString = JSON.stringify(params);\n      if (paramsString.length > 300) {\n        paramsString = paramsString.substring(0, 300) + \"...\";\n      }\n      paramsString = ` | Params: ${paramsString}`;\n    }\n\n    try {\n      let result;\n      if (this.config.logging) {\n        log.info({\n          module: \"database.postgres\",\n          action: \"query.executing\",\n          message: `${sql}${paramsString}`,\n          context: { params, sql },\n        });\n      }\n      if (txClient) {\n        result = await txClient.query(sql, params);\n      } else {\n        result = await this.pool.query(sql, params);\n      }\n\n      if (this.config.logging) {\n        const duration = (performance.now() - startTime).toFixed(2);\n        log.success({\n          module: \"database.postgres\",\n          action: \"query.executed\",\n          message: `[${duration}ms] ${sql}${paramsString}`,\n          context: { params, sql, duration },\n        });\n      }\n\n      return result as PostgresQueryResult<T>;\n    } catch (error) {\n      if (this.config.logging) {\n        const duration = (performance.now() - startTime).toFixed(2);\n        log.error({\n          module: \"database.postgres\",\n          action: \"query.error\",\n          message: `[${duration}ms] ${sql}${paramsString}`,\n          context: {\n            sql,\n            params,\n            error: error instanceof Error ? error.message : String(error),\n          },\n        });\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Emit an event to all registered listeners.\n   *\n   * @param event - Event name\n   * @param args - Event arguments\n   */\n  private emit(event: string, ...args: unknown[]): void {\n    const listeners = this._eventListeners.get(event);\n    if (listeners) {\n      for (const listener of listeners) {\n        listener(...args);\n      }\n    }\n  }\n\n  /**\n   * Build a simple WHERE clause from a filter object.\n   *\n   * @param filter - Filter conditions\n   * @param startParamIndex - Starting parameter index\n   * @returns Object with WHERE clause string and parameters\n   */\n  private buildWhereClause(\n    filter: Record<string, unknown>,\n    startParamIndex: number,\n  ): { whereClause: string; whereParams: unknown[] } {\n    const conditions: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = startParamIndex;\n\n    for (const [key, value] of Object.entries(filter)) {\n      const quotedKey = this.dialect.quoteIdentifier(key);\n\n      if (value === null) {\n        conditions.push(`${quotedKey} IS NULL`);\n      } else {\n        conditions.push(`${quotedKey} = ${this.dialect.placeholder(paramIndex++)}`);\n        params.push(value);\n      }\n    }\n\n    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    return { whereClause, whereParams: params };\n  }\n\n  /**\n   * Build an UPDATE query from update operations.\n   *\n   * @param table - Target table name\n   * @param filter - Filter conditions\n   * @param update - Update operations\n   * @param limit - Optional limit (for single row update)\n   * @returns Object with SQL and parameters\n   */\n  private buildUpdateQuery(\n    table: string,\n    filter: Record<string, unknown>,\n    update: UpdateOperations,\n    limit?: number,\n  ): { sql: string; params: unknown[] } {\n    const setClauses: string[] = [];\n    const params: unknown[] = [];\n    let paramIndex = 1;\n\n    // Handle $set\n    if (update.$set) {\n      for (const [key, value] of Object.entries(update.$set)) {\n        setClauses.push(\n          `${this.dialect.quoteIdentifier(key)} = ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        // Apply the same json/jsonb-aware serialization used on the INSERT\n        // path so object/array $set values aren't corrupted into Postgres\n        // array literals. undefined is skipped — never bind it.\n        params.push(value === undefined ? value : this.serializeValue(key, value, table));\n      }\n    }\n\n    // Handle $unset (set to NULL)\n    if (update.$unset) {\n      for (const key of Object.keys(update.$unset)) {\n        setClauses.push(`${this.dialect.quoteIdentifier(key)} = NULL`);\n      }\n    }\n\n    // Handle $inc\n    if (update.$inc) {\n      for (const [key, amount] of Object.entries(update.$inc)) {\n        const quotedKey = this.dialect.quoteIdentifier(key);\n        setClauses.push(\n          `${quotedKey} = COALESCE(${quotedKey}, 0) + ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        params.push(amount);\n      }\n    }\n\n    // Handle $dec\n    if (update.$dec) {\n      for (const [key, amount] of Object.entries(update.$dec)) {\n        const quotedKey = this.dialect.quoteIdentifier(key);\n        setClauses.push(\n          `${quotedKey} = COALESCE(${quotedKey}, 0) - ${this.dialect.placeholder(paramIndex++)}`,\n        );\n        params.push(amount);\n      }\n    }\n\n    if (setClauses.length === 0) {\n      throw new Error(\"No update operations specified\");\n    }\n\n    const quotedTable = this.dialect.quoteIdentifier(table);\n    const { whereClause, whereParams } = this.buildWhereClause(filter, paramIndex);\n    params.push(...whereParams);\n\n    let sql = `UPDATE ${quotedTable} SET ${setClauses.join(\", \")} ${whereClause}`;\n\n    // For single row update, use ctid subquery\n    if (limit === 1 && whereClause) {\n      sql = `UPDATE ${quotedTable} SET ${setClauses.join(\", \")} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;\n    }\n\n    return { sql, params };\n  }\n\n  // ============================================================\n  // Database Lifecycle Operations\n  // ============================================================\n\n  /**\n   * Create a new database.\n   *\n   * Note: This requires connecting to a system database (like 'postgres')\n   * since you cannot create a database while connected to it.\n   *\n   * @param name - Database name to create\n   * @param options - Creation options (encoding, template, etc.)\n   * @returns true if created, false if already exists\n   */\n  public async createDatabase(name: string, options?: CreateDatabaseOptions): Promise<boolean> {\n    // Check if database already exists\n    if (await this.databaseExists(name)) {\n      return false;\n    }\n\n    // Build CREATE DATABASE statement\n    const quotedName = this.dialect.quoteIdentifier(name);\n    let sql = `CREATE DATABASE ${quotedName}`;\n\n    const withClauses: string[] = [];\n\n    if (options?.encoding) {\n      withClauses.push(`ENCODING = '${options.encoding}'`);\n    }\n    if (options?.template) {\n      withClauses.push(`TEMPLATE = ${this.dialect.quoteIdentifier(options.template)}`);\n    }\n    if (options?.locale) {\n      withClauses.push(`LC_COLLATE = '${options.locale}'`);\n      withClauses.push(`LC_CTYPE = '${options.locale}'`);\n    }\n    if (options?.owner) {\n      withClauses.push(`OWNER = ${this.dialect.quoteIdentifier(options.owner)}`);\n    }\n\n    if (withClauses.length > 0) {\n      sql += ` WITH ${withClauses.join(\" \")}`;\n    }\n\n    try {\n      await this.query(sql);\n      log.success(\"database\", \"lifecycle\", `Created database ${name}`);\n      return true;\n    } catch (error) {\n      log.error(\"database\", \"lifecycle\", `Failed to create database ${name}: ${error}`);\n      throw error;\n    }\n  }\n\n  /**\n   * Drop a database.\n   *\n   * @param name - Database name to drop\n   * @param options - Drop options\n   * @returns true if dropped, false if didn't exist\n   */\n  public async dropDatabase(name: string, options?: DropDatabaseOptions): Promise<boolean> {\n    // Check if database exists first (if ifExists option not set)\n    if (!options?.ifExists && !(await this.databaseExists(name))) {\n      return false;\n    }\n\n    const quotedName = this.dialect.quoteIdentifier(name);\n    let sql = \"DROP DATABASE\";\n\n    if (options?.ifExists) {\n      sql += \" IF EXISTS\";\n    }\n\n    sql += ` ${quotedName}`;\n\n    // PostgreSQL 13+ supports WITH (FORCE) to terminate active connections\n    if (options?.force) {\n      sql += \" WITH (FORCE)\";\n    }\n\n    try {\n      await this.query(sql);\n      log.success(\"database\", \"lifecycle\", `Dropped database ${name}`);\n      return true;\n    } catch (error) {\n      log.error(\"database\", \"lifecycle\", `Failed to drop database ${name}: ${error}`);\n      throw error;\n    }\n  }\n\n  /**\n   * Check if a database exists.\n   *\n   * @param name - Database name to check\n   * @returns true if database exists\n   */\n  public async databaseExists(name: string): Promise<boolean> {\n    const result = await this.query<{ exists: boolean }>(\n      `SELECT EXISTS(SELECT 1 FROM pg_database WHERE datname = $1) as exists`,\n      [name],\n    );\n\n    return result.rows[0]?.exists ?? false;\n  }\n\n  /**\n   * List all databases.\n   *\n   * @returns Array of database names\n   */\n  public async listDatabases(): Promise<string[]> {\n    const result = await this.query<{ datname: string }>(\n      `SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname`,\n    );\n\n    return result.rows.map((row) => row.datname);\n  }\n\n  // ============================================================\n  // Table Management Operations\n  // ============================================================\n\n  /**\n   * Drop a table.\n   *\n   * @param name - Table name to drop\n   * @throws Error if table doesn't exist\n   */\n  public async dropTable(name: string): Promise<void> {\n    const quotedName = this.dialect.quoteIdentifier(name);\n    await this.query(`DROP TABLE ${quotedName}`);\n    log.success(\"database\", \"table\", `Dropped table ${name}`);\n  }\n\n  /**\n   * Drop a table if it exists.\n   *\n   * @param name - Table name to drop\n   */\n  public async dropTableIfExists(name: string): Promise<void> {\n    const quotedName = this.dialect.quoteIdentifier(name);\n    await this.query(`DROP TABLE IF EXISTS ${quotedName}`);\n  }\n\n  /**\n   * Drop all tables in the current database.\n   *\n   * Uses CASCADE to handle foreign key dependencies.\n   * Useful for `migrate:fresh` command.\n   */\n  public async dropAllTables(): Promise<void> {\n    // Get all tables from blueprint\n    const tables = await this.blueprint.listTables();\n\n    if (tables.length === 0) {\n      return;\n    }\n\n    // Drop all tables with CASCADE to handle foreign keys\n    for (const table of tables) {\n      const quotedName = this.dialect.quoteIdentifier(table);\n      await this.query(`DROP TABLE IF EXISTS ${quotedName} CASCADE`);\n    }\n\n    log.success(\"database\", \"table\", `Dropped ${tables.length} tables`);\n  }\n}\n"],"mappings":"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"}

package/llms-full.txt

@@ -1432,7 +1432,7 @@ There is no `has(name)` / `list()` / `setDefault()` — guard with a `try/catch`
 
 ---
 name: manage-transactions
-description: 'Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and the Postgres `nativeArrayColumns` connection option. Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.'
+description: 'Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and Postgres native-array column handling (`JSONB[]` / `TEXT[]` / `INTEGER[]` auto-detected via schema introspection on connect; `nativeArrayColumns` is an optional override). Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested transaction, flat nesting, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column", "malformed array literal", "array column not saving", "nested transaction not visible", "foreign key violation on insert inside transaction", "service transaction inside seeder"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.'
 ---
 
 # Use transactions
@@ -1500,7 +1500,9 @@ Postgres has no such requirement — transactions work out of the box.
 
 ## Nesting
 
-The function-shaped `transaction(fn)` is **not** nestable — calling it inside an already-open transaction is not supported. For nested scope on Postgres, drop to the manual API (`driver.beginTransaction()`) and use savepoints explicitly. For most app code, keep a single top-level `transaction(fn)` and let any inner failure abort the whole flow.
+`transaction(fn)` **flat-nests**: calling it inside an already-open transaction JOINS the outer one instead of opening a second, independent transaction. The inner block runs on the **same** session — so it sees the outer's uncommitted writes — and the **outermost** `transaction()` owns commit/rollback. A service that opens its own `transaction()` for standalone atomicity therefore also works unchanged when called inside a larger transaction — e.g. a seeder that creates a row, then calls a service that opens a transaction to insert a child referencing it (an independent inner transaction couldn't see the parent's uncommitted row, and the child insert would fail its foreign key).
+
+A throw anywhere inside unwinds the **whole** outer transaction — Postgres aborts a transaction on the first error, so there is no automatic per-block savepoint. For independent partial rollback of an inner block, drop to the manual API (`driver.beginTransaction()`) and use savepoints explicitly.
 
 ## Explicit rollback
 
@@ -1557,21 +1559,23 @@ const { rows: counts } = await dataSource.raw<{ count: number }>(
 
 `Model.raw<T>(sql, params?)` and `DataSource.raw<T>(sql, params?)` both return `Promise<RawQueryResult<T>>` — `{ rows: T[]; rowCount: number }`, **not** hydrated model instances. MongoDB drivers **throw**: there is no raw SQL on Mongo.
 
-### `nativeArrayColumns` (Postgres connection option)
+### Native-array columns (`JSONB[]` / `TEXT[]` / `INTEGER[]`)
+
+From a value alone the serializer can't tell a `json` / `jsonb` column (which needs JSON text) from a genuine **native-array** column (`arrayJson()` → `JSONB[]`, `arrayText()` → `TEXT[]`, …, which needs the raw JS array so node-pg emits a `{...}` literal). Guess wrong and Postgres rejects the insert with *"malformed array literal"*.
 
-The Postgres serializer can't see the table schema, so by default it `JSON.stringify`s every non-vector array (and plain object) to bind it as JSON text — the correct form for a `json` / `jsonb` column. For a genuine **native-array** column (`JSONB[]` / `TEXT[]` / `INTEGER[]`, e.g. from `arrayJson()` / `arrayText()`) that's wrong: node-pg must receive the raw JS array so it emits a `{...}` array literal. List those columns in the connection's `nativeArrayColumns` to opt them out of JSON-text encoding:
+**This is handled automatically.** On connect the driver introspects `information_schema` once and remembers which columns are native arrays **per table**, so `arrayText()` / `arrayJson()` columns just work with **no configuration**. Because it's per-table, the same column name being `TEXT[]` in one table and `jsonb` in another is encoded correctly for each; the pgvector all-number array form is still preserved.
+
+`nativeArrayColumns` remains as an optional, table-agnostic **override** — for a column created outside a migration, or an environment where `information_schema` can't be read:
 
 ```ts
 connectToDatabase({
   name: "default",
   driver: "postgres",
   // ...
-  nativeArrayColumns: ["tags", "category_ids"], // genuine TEXT[] / INTEGER[] columns
+  nativeArrayColumns: ["tags", "category_ids"], // optional manual override
 });
 ```
 
-The pgvector all-number array form is preserved automatically — you only need this for non-vector native arrays.
-
 ## Side effects after commit — the outbox pattern
 
 For "side effects must only happen if the transaction succeeded" (publish to a queue, send an email, write to a search index), don't run them inside the transaction. Use the outbox pattern: write a row to an outbox table inside the transaction, dispatch from the outbox in a separate worker after commit.

package/llms.txt

@@ -13,7 +13,7 @@
 - [define-model](@warlock.js/cascade/define-model/SKILL.md): Define a Cascade model — `@RegisterModel()`, class extends `Model<TSchema>`, `static table`, `static schema`, three update idioms (`.set` / `.merge` / `.save`), `.unset`, `.destroy`, `static toJsonColumns` / `resource` for output shaping. Triggers: `Model`, `RegisterModel`, `static schema`, `.set`, `.merge`, `.save`, `.unset`, `.destroy`, `toJsonColumns`, `resource`; "how do I define a model", "shape the JSON output", "remove a field"; typical import `import { Model, RegisterModel } from "@warlock.js/cascade"`. Skip: querying — `@warlock.js/cascade/query-data/SKILL.md`; relations — `@warlock.js/cascade/define-relations/SKILL.md`; competing libs `mongoose`, `prisma`, `typeorm` `@Entity`.
 - [define-relations](@warlock.js/cascade/define-relations/SKILL.md): Define and query relations — `@BelongsTo` / `@HasMany` / `@BelongsToMany`, `.with("relation")` eager loading, `.whereHas(relation, cb)` filter-by-related, `setRelation` on save, `.joinWith` for SQL joins, `loadRelation`, `lazy(() => Model)`. Triggers: `@BelongsTo`, `@HasMany`, `@BelongsToMany`, `.with`, `.whereHas`, `setRelation`, `.joinWith`, `lazy`; "define a relation", "avoid N+1", "eager load posts", "filter parents by child"; typical import `import { BelongsTo, HasMany, BelongsToMany } from "@warlock.js/cascade"`. Skip: model basics — `@warlock.js/cascade/define-model/SKILL.md`; competing libs `mongoose populate`, `prisma include`, `typeorm relations`.
 - [manage-data-sources](@warlock.js/cascade/manage-data-sources/SKILL.md): Configure multiple databases — register each via `connectToDatabase({ name, driver, database, isDefault })`, assign a model with `static dataSource = "name"`, route a migration with `dataSource` on the migration class, inspect via `dataSourceRegistry.get(name)` / `getAllDataSources()`. The first (or `isDefault: true`) source is the default. Triggers: `connectToDatabase`, `dataSourceRegistry`, `dataSourceRegistry.get`, `getAllDataSources`, `static dataSource`; "multi-database app", "per-tenant DB", "analytics on separate DB"; typical import `import { connectToDatabase, dataSourceRegistry } from "@warlock.js/cascade"`. Skip: per-source migrations — `@warlock.js/cascade/write-migration/SKILL.md`; transaction scope — `@warlock.js/cascade/manage-transactions/SKILL.md`; competing patterns `mongoose.createConnection`, `typeorm` `DataSource`, `prisma` multi-schema.
-- [manage-transactions](@warlock.js/cascade/manage-transactions/SKILL.md): Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and the Postgres `nativeArrayColumns` connection option. Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.
+- [manage-transactions](@warlock.js/cascade/manage-transactions/SKILL.md): Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and Postgres native-array column handling (`JSONB[]` / `TEXT[]` / `INTEGER[]` auto-detected via schema introspection on connect; `nativeArrayColumns` is an optional override). Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested transaction, flat nesting, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column", "malformed array literal", "array column not saving", "nested transaction not visible", "foreign key violation on insert inside transaction", "service transaction inside seeder"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.
 - [paginate-results](@warlock.js/cascade/paginate-results/SKILL.md): Paginate query results — `.paginate({page, limit, filter?})` for offset (returns `data` + `pagination` total/page/limit/pages), `.cursorPaginate({limit, cursor})` for very large datasets, `.chunk(size, callback)` for streaming. Triggers: `.paginate`, `.cursorPaginate`, `.chunk`, `nextCursor`, `hasMore`, `pagination.total`; "paginate the list", "infinite scroll / load more", "stream a large table", "page 2 of users"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: filter chain — `@warlock.js/cascade/query-data/SKILL.md`; eager loading on pages — `@warlock.js/cascade/define-relations/SKILL.md`; competing libs `mongoose-paginate-v2`, `prisma` cursor, `typeorm-pagination`.
 - [perform-atomic-ops](@warlock.js/cascade/perform-atomic-ops/SKILL.md): Avoid races on concurrent writes — `Model.increase(filter, field, n)` / `Model.decrease` for atomic counters, `Model.atomic(filter, ops)` for arbitrary mutations (`$set` / `$inc` / `$push` / `$pull`), `Model.createMany` / `Model.findAndUpdate` / `Model.delete` for bulk. Triggers: `Model.increase`, `Model.decrease`, `Model.atomic`, `Model.createMany`, `createMany bulk`, `batchSize`, `Model.findAndUpdate`, `Model.delete`, `$inc`, `$set`; "increment counter under concurrency", "bulk insert without N+1", "fast bulk insert", "insert thousands of rows", "atomic update without loading"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: multi-row atomicity — `@warlock.js/cascade/manage-transactions/SKILL.md`; competing patterns `mongoose findOneAndUpdate`, `pg` `UPDATE ... SET x = x + 1`.
 - [query-data](@warlock.js/cascade/query-data/SKILL.md): Query records via the model — `.where(field, value)` / `.where(field, op, value)`, `.find(id)` / `.first` / `.all`, `.orderBy`, `.count` / `.exists`, plus `.whereIn` / `.whereBetween` / `.whereLike` / `.pluck` / `.firstOrFail` / scopes via `addScope`. Triggers: `.where`, `.find`, `.first`, `.firstOrFail`, `.all`, `.get`, `.orderBy`, `.exists`, `.whereIn`, `.whereBetween`, `addScope`; "filter by status", "find by id", "fetch active users", "check existence"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: pagination — `@warlock.js/cascade/paginate-results/SKILL.md`; aggregates — `@warlock.js/cascade/aggregate-data/SKILL.md`.

package/package.json

@@ -27,9 +27,9 @@
     "@mongez/events": "^2.2.6",
     "@mongez/reinforcements": "^3.3.0",
     "@mongez/supportive-is": "^2.1.3",
-    "@warlock.js/context": "4.6.0",
-    "@warlock.js/logger": "4.6.0",
-    "@warlock.js/seal": "4.6.0",
+    "@warlock.js/context": "4.6.1",
+    "@warlock.js/logger": "4.6.1",
+    "@warlock.js/seal": "4.6.1",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -40,7 +40,7 @@
   "bin": {
     "cascade": "bin/cascade.js"
   },
-  "version": "4.6.0",
+  "version": "4.6.1",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/manage-transactions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-transactions
-description: 'Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and the Postgres `nativeArrayColumns` connection option. Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.'
+description: 'Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Also the home for transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and Postgres native-array column handling (`JSONB[]` / `TEXT[]` / `INTEGER[]` auto-detected via schema introspection on connect; `nativeArrayColumns` is an optional override). Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested transaction, flat nesting, nested savepoints, `Model.raw`, `DataSource.raw`, raw SQL, `RawQueryResult`, `nativeArrayColumns`, `JSONB[]`, `TEXT[]`; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions", "run raw SQL", "native array column", "malformed array literal", "array column not saving", "nested transaction not visible", "foreign key violation on insert inside transaction", "service transaction inside seeder"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.'
 ---
 
 # Use transactions
@@ -68,7 +68,9 @@ Postgres has no such requirement — transactions work out of the box.
 
 ## Nesting
 
-The function-shaped `transaction(fn)` is **not** nestable — calling it inside an already-open transaction is not supported. For nested scope on Postgres, drop to the manual API (`driver.beginTransaction()`) and use savepoints explicitly. For most app code, keep a single top-level `transaction(fn)` and let any inner failure abort the whole flow.
+`transaction(fn)` **flat-nests**: calling it inside an already-open transaction JOINS the outer one instead of opening a second, independent transaction. The inner block runs on the **same** session — so it sees the outer's uncommitted writes — and the **outermost** `transaction()` owns commit/rollback. A service that opens its own `transaction()` for standalone atomicity therefore also works unchanged when called inside a larger transaction — e.g. a seeder that creates a row, then calls a service that opens a transaction to insert a child referencing it (an independent inner transaction couldn't see the parent's uncommitted row, and the child insert would fail its foreign key).
+
+A throw anywhere inside unwinds the **whole** outer transaction — Postgres aborts a transaction on the first error, so there is no automatic per-block savepoint. For independent partial rollback of an inner block, drop to the manual API (`driver.beginTransaction()`) and use savepoints explicitly.
 
 ## Explicit rollback
 
@@ -125,21 +127,23 @@ const { rows: counts } = await dataSource.raw<{ count: number }>(
 
 `Model.raw<T>(sql, params?)` and `DataSource.raw<T>(sql, params?)` both return `Promise<RawQueryResult<T>>` — `{ rows: T[]; rowCount: number }`, **not** hydrated model instances. MongoDB drivers **throw**: there is no raw SQL on Mongo.
 
-### `nativeArrayColumns` (Postgres connection option)
+### Native-array columns (`JSONB[]` / `TEXT[]` / `INTEGER[]`)
+
+From a value alone the serializer can't tell a `json` / `jsonb` column (which needs JSON text) from a genuine **native-array** column (`arrayJson()` → `JSONB[]`, `arrayText()` → `TEXT[]`, …, which needs the raw JS array so node-pg emits a `{...}` literal). Guess wrong and Postgres rejects the insert with *"malformed array literal"*.
 
-The Postgres serializer can't see the table schema, so by default it `JSON.stringify`s every non-vector array (and plain object) to bind it as JSON text — the correct form for a `json` / `jsonb` column. For a genuine **native-array** column (`JSONB[]` / `TEXT[]` / `INTEGER[]`, e.g. from `arrayJson()` / `arrayText()`) that's wrong: node-pg must receive the raw JS array so it emits a `{...}` array literal. List those columns in the connection's `nativeArrayColumns` to opt them out of JSON-text encoding:
+**This is handled automatically.** On connect the driver introspects `information_schema` once and remembers which columns are native arrays **per table**, so `arrayText()` / `arrayJson()` columns just work with **no configuration**. Because it's per-table, the same column name being `TEXT[]` in one table and `jsonb` in another is encoded correctly for each; the pgvector all-number array form is still preserved.
+
+`nativeArrayColumns` remains as an optional, table-agnostic **override** — for a column created outside a migration, or an environment where `information_schema` can't be read:
 
 ```ts
 connectToDatabase({
   name: "default",
   driver: "postgres",
   // ...
-  nativeArrayColumns: ["tags", "category_ids"], // genuine TEXT[] / INTEGER[] columns
+  nativeArrayColumns: ["tags", "category_ids"], // optional manual override
 });
 ```
 
-The pgvector all-number array form is preserved automatically — you only need this for non-vector native arrays.
-
 ## Side effects after commit — the outbox pattern
 
 For "side effects must only happen if the transaction succeeded" (publish to a queue, send an email, write to a search index), don't run them inside the transaction. Use the outbox pattern: write a row to an outbox table inside the transaction, dispatch from the outbox in a separate worker after commit.