@workglow/postgres 0.2.31 → 0.2.33

package/dist/storage/node.js

@@ -38,26 +38,55 @@ import { createServiceToken as createServiceToken2 } from "@workglow/util";
 import { createServiceToken } from "@workglow/util";
 import {
   BaseSqlTabularStorage,
-  isSearchCondition,
+  buildSearchWhere,
+  MIGRATIONS_TABLE,
+  PostgresDialect,
+  SqlTabularMigrationApplier,
   pickCoveringIndex
 } from "@workglow/storage";
 var POSTGRES_TABULAR_REPOSITORY = createServiceToken("storage.tabularRepository.postgres");
+function assertPositiveInt(value, label) {
+  if (value === undefined)
+    return;
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new Error(`VectorIndexOptions.${label} must be a positive integer; received ${String(value)}`);
+  }
+}
 
 class PostgresTabularStorage extends BaseSqlTabularStorage {
   db;
-  constructor(db, table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
-    super(table, schema, primaryKeyNames, indexes, clientProvidedKeys);
+  constructor(db, table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing", tabularMigrations) {
+    super(table, schema, primaryKeyNames, indexes, clientProvidedKeys, tabularMigrations, table);
     this.db = db;
   }
   async setupDatabase() {
+    if (this.tabularMigrations && this.tabularMigrations.length > 0) {
+      const exists = await this.tableExistsAsync();
+      await this.createTableAndIndexes();
+      await this.applyTabularMigrations({ freshTable: !exists });
+      if (exists) {
+        await this.createDeclaredIndexes();
+      }
+      return;
+    }
+    await this.createTableAndIndexes();
+  }
+  async tableExistsAsync() {
+    const r = await this.db.query(`SELECT 1 AS x FROM information_schema.tables WHERE table_name = $1 LIMIT 1`, [this.table]);
+    return r.rows.length > 0;
+  }
+  async createTableAndIndexes() {
     const sql = `
       CREATE TABLE IF NOT EXISTS "${this.table}" (
         ${this.constructPrimaryKeyColumns('"')} ${this.constructValueColumns('"')},
-        PRIMARY KEY (${this.primaryKeyColumnList()}) 
+        PRIMARY KEY (${this.primaryKeyColumnList()})
       )
     `;
     await this.db.query(sql);
     await this.createVectorIndexes();
+    await this.createDeclaredIndexes();
+  }
+  async createDeclaredIndexes() {
     const pkColumns = this.primaryKeyColumns();
     const createdIndexes = new Set;
     for (const columns of this.indexes) {
@@ -81,6 +110,15 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
       }
     }
   }
+  async runMigrationDdl(sql) {
+    await this.db.query(sql);
+  }
+  async recordMigrationApplied(component, version, description) {
+    await this.db.query(`INSERT INTO ${MIGRATIONS_TABLE}(component, version, description) VALUES ($1, $2, $3)`, [component, version, description]);
+  }
+  getMigrationApplier() {
+    return new PostgresTabularMigrationApplierImpl(this);
+  }
   isVectorFormat(format) {
     if (!format)
       return false;
@@ -292,32 +330,73 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     }
     return vectorColumns;
   }
+  getVectorIndexOptions() {
+    return {};
+  }
   async createVectorIndexes() {
     const vectorColumns = this.getVectorColumns();
     if (vectorColumns.length === 0) {
       return;
     }
+    const opts = this.getVectorIndexOptions();
+    if (opts.hnsw && opts.ivfflat) {
+      throw new Error("VectorIndexOptions: only one of `hnsw` or `ivfflat` may be set; received both.");
+    }
+    assertPositiveInt(opts.hnsw?.m, "hnsw.m");
+    assertPositiveInt(opts.hnsw?.efConstruction, "hnsw.efConstruction");
+    assertPositiveInt(opts.hnsw?.efSearch, "hnsw.efSearch");
+    assertPositiveInt(opts.ivfflat?.lists, "ivfflat.lists");
+    assertPositiveInt(opts.ivfflat?.probes, "ivfflat.probes");
     try {
       await this.db.query("CREATE EXTENSION IF NOT EXISTS vector");
     } catch (error) {
       console.warn("pgvector extension not available, vector columns will use TEXT fallback:", error);
       return;
     }
+    const distance = opts.distance ?? "cosine";
+    const opClass = distance === "l2" ? "vector_l2_ops" : distance === "ip" ? "vector_ip_ops" : "vector_cosine_ops";
+    const tableId = PostgresDialect.quoteId(this.table);
+    if (opts.ivfflat) {
+      const { lists } = opts.ivfflat;
+      for (const { column } of vectorColumns) {
+        const indexId = PostgresDialect.quoteId(`${this.table}_${column}_ivfflat_idx`);
+        const columnId = PostgresDialect.quoteId(column);
+        try {
+          await this.db.query(`
+            CREATE INDEX IF NOT EXISTS ${indexId}
+            ON ${tableId}
+            USING ivfflat (${columnId} ${opClass})
+            WITH (lists = ${lists})
+          `);
+        } catch (error) {
+          console.warn(`Failed to create IVFFlat index on ${column}:`, error);
+        }
+      }
+      return;
+    }
+    const hnsw = opts.hnsw ?? {};
+    const buildParams = [];
+    if (typeof hnsw.m === "number")
+      buildParams.push(`m = ${hnsw.m}`);
+    if (typeof hnsw.efConstruction === "number") {
+      buildParams.push(`ef_construction = ${hnsw.efConstruction}`);
+    }
+    const withClause = buildParams.length > 0 ? ` WITH (${buildParams.join(", ")})` : "";
     for (const { column } of vectorColumns) {
-      const indexName = `${this.table}_${column}_hnsw_idx`;
+      const indexId = PostgresDialect.quoteId(`${this.table}_${column}_hnsw_idx`);
+      const columnId = PostgresDialect.quoteId(column);
       try {
         await this.db.query(`
-          CREATE INDEX IF NOT EXISTS "${indexName}"
-          ON "${this.table}"
-          USING hnsw ("${column}" vector_cosine_ops)
+          CREATE INDEX IF NOT EXISTS ${indexId}
+          ON ${tableId}
+          USING hnsw (${columnId} ${opClass})${withClause}
         `);
       } catch (error) {
         console.warn(`Failed to create HNSW index on ${column}:`, error);
       }
     }
   }
-  async put(entity) {
-    const db = this.db;
+  buildPutSql(entity) {
     const columnsToInsert = [];
     const paramsToInsert = [];
     const pkColumns = this.primaryKeyColumns();
@@ -359,7 +438,7 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     const placeholders = columnsToInsert.map((_, i) => `$${i + 1}`).join(", ");
     const conflictClause = valueColumns.length > 0 ? `
       ON CONFLICT (${this.primaryKeyColumnList('"')}) DO UPDATE
-      SET 
+      SET
       ${valueColumns.map((col) => {
       const colIdx = columnsToInsert.indexOf(String(col));
       return `"${col}" = $${colIdx + 1}`;
@@ -371,22 +450,177 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
       ${conflictClause}
       RETURNING *
     `;
-    const params = paramsToInsert;
-    const result = await db.query(sql, params);
-    const updatedEntity = result.rows[0];
-    const updatedRecord = updatedEntity;
+    return { sql, params: paramsToInsert };
+  }
+  hydrateRow(row) {
+    const entity = row;
+    const record = entity;
     for (const key in this.schema.properties) {
-      updatedRecord[key] = this.sqlToJsValue(key, updatedRecord[key]);
+      record[key] = this.sqlToJsValue(key, record[key]);
+    }
+    return entity;
+  }
+  async acquireConnection() {
+    const supportsConnect = typeof this.db.connect === "function";
+    if (supportsConnect) {
+      return await this.db.connect();
+    }
+    const dbAny = this.db;
+    const ctorName = dbAny.constructor?.name;
+    const looksLikePGlite = typeof dbAny.exec === "function" && dbAny.waitReady !== undefined;
+    const looksLikePGLitePool = ctorName === "PGLitePool";
+    if (!looksLikePGlite && !looksLikePGLitePool) {
+      throw new Error(`PostgresTabularStorage.putBulk requires a pg.Pool with connect() or a known single-connection wrapper (PGLitePool, PGlite); got ${ctorName ?? typeof this.db}. A multi-connection pool without connect() would dispatch BEGIN and the bracketed INSERTs to different sessions, breaking atomicity.`);
     }
-    this.events.emit("put", updatedEntity);
+    return {
+      query: this.db.query.bind(this.db),
+      release: () => {}
+    };
+  }
+  mutexChain = Promise.resolve();
+  get serializeOps() {
+    return typeof this.db.connect !== "function";
+  }
+  async mutex(fn) {
+    if (!this.serializeOps)
+      return fn();
+    const prev = this.mutexChain;
+    let release;
+    this.mutexChain = new Promise((resolve) => {
+      release = resolve;
+    });
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  inTransaction = false;
+  emitPut(entity) {
+    this.events.emit("put", entity);
+  }
+  async put(entity) {
+    return this.mutex(() => this._putInternal(entity));
+  }
+  async _putInternal(entity) {
+    const { sql, params } = this.buildPutSql(entity);
+    const result = await this.db.query(sql, params);
+    const updatedEntity = this.hydrateRow(result.rows[0]);
+    this.emitPut(updatedEntity);
     return updatedEntity;
   }
   async putBulk(entities) {
+    return this.mutex(() => this._putBulkInternal(entities));
+  }
+  async _putBulkInternal(entities) {
     if (entities.length === 0)
       return [];
-    return await Promise.all(entities.map((entity) => this.put(entity)));
+    if (this.inTransaction) {
+      const updated = [];
+      for (const entity of entities) {
+        const { sql, params } = this.buildPutSql(entity);
+        const result = await this.db.query(sql, params);
+        updated.push(this.hydrateRow(result.rows[0]));
+      }
+      for (const entity of updated)
+        this.emitPut(entity);
+      return updated;
+    }
+    const conn = await this.acquireConnection();
+    const updatedEntities = [];
+    try {
+      await conn.query("BEGIN");
+      try {
+        for (const entity of entities) {
+          const { sql, params } = this.buildPutSql(entity);
+          const result = await conn.query(sql, params);
+          updatedEntities.push(this.hydrateRow(result.rows[0]));
+        }
+        await conn.query("COMMIT");
+      } catch (err) {
+        try {
+          await conn.query("ROLLBACK");
+        } catch {}
+        throw err;
+      }
+    } finally {
+      conn.release();
+    }
+    for (const entity of updatedEntities)
+      this.emitPut(entity);
+    return updatedEntities;
+  }
+  createTxView(txDb, deferredPutEvents) {
+    const target = this;
+    return new Proxy(target, {
+      get(t, prop, receiver) {
+        if (prop === "withTransaction") {
+          return () => {
+            throw new Error("PostgresTabularStorage.withTransaction does not support nesting. " + "Use SAVEPOINT directly or refactor to a single transaction.");
+          };
+        }
+        if (prop === "db")
+          return txDb;
+        if (prop === "inTransaction")
+          return true;
+        if (prop === "emitPut") {
+          return (entity) => deferredPutEvents.push(entity);
+        }
+        if (typeof prop === "string") {
+          const internal = t[`_${prop}Internal`];
+          if (typeof internal === "function") {
+            return (...args) => internal.apply(receiver, args);
+          }
+        }
+        const value = Reflect.get(t, prop, receiver);
+        return typeof value === "function" ? value.bind(receiver) : value;
+      }
+    });
+  }
+  async withTransaction(fn) {
+    const supportsConnect = typeof this.db.connect === "function";
+    if (supportsConnect) {
+      const client = await this.db.connect();
+      try {
+        return await this.runInTransaction(fn, { query: client.query.bind(client) });
+      } finally {
+        client.release();
+      }
+    }
+    if (this.inTransaction) {
+      throw new Error("PostgresTabularStorage.withTransaction does not support nesting. " + "Use SAVEPOINT directly or refactor to a single transaction.");
+    }
+    return this.mutex(async () => {
+      this.inTransaction = true;
+      try {
+        return await this.runInTransaction(fn, { query: this.db.query.bind(this.db) });
+      } finally {
+        this.inTransaction = false;
+      }
+    });
+  }
+  async runInTransaction(fn, txDb) {
+    const deferredPutEvents = [];
+    await txDb.query("BEGIN");
+    let result;
+    try {
+      result = await fn(this.createTxView(txDb, deferredPutEvents));
+      await txDb.query("COMMIT");
+    } catch (err) {
+      try {
+        await txDb.query("ROLLBACK");
+      } catch {}
+      throw err;
+    }
+    for (const entity of deferredPutEvents)
+      this.events.emit("put", entity);
+    return result;
   }
   async get(key) {
+    return this.mutex(() => this._getInternal(key));
+  }
+  async _getInternal(key) {
     const db = this.db;
     const whereClauses = this.primaryKeyColumns().map((discriminatorKey, i) => `"${discriminatorKey}" = $${i + 1}`).join(" AND ");
     const sql = `SELECT * FROM "${this.table}" WHERE ${whereClauses}`;
@@ -406,6 +640,9 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     return val;
   }
   async delete(value) {
+    return this.mutex(() => this._deleteInternal(value));
+  }
+  async _deleteInternal(value) {
     const db = this.db;
     const { key } = this.separateKeyValueFromCombined(value);
     const whereClauses = this.primaryKeyColumns().map((key2, i) => `${key2} = $${i + 1}`).join(" AND ");
@@ -414,6 +651,9 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     this.events.emit("delete", key);
   }
   async getAll(options) {
+    return this.mutex(() => this._getAllInternal(options));
+  }
+  async _getAllInternal(options) {
     this.validateGetAllOptions(options);
     const db = this.db;
     let sql = `SELECT * FROM "${this.table}"`;
@@ -443,18 +683,27 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     return;
   }
   async deleteAll() {
+    return this.mutex(() => this._deleteAllInternal());
+  }
+  async _deleteAllInternal() {
     const db = this.db;
     await db.query(`DELETE FROM "${this.table}"`);
     this.events.emit("clearall");
   }
   async size() {
+    return this.mutex(() => this._sizeInternal());
+  }
+  async _sizeInternal() {
     const db = this.db;
     const result = await db.query(`SELECT COUNT(*) FROM "${this.table}"`);
     return parseInt(result.rows[0].count, 10);
   }
   async count(criteria) {
+    return this.mutex(() => this._countInternal(criteria));
+  }
+  async _countInternal(criteria) {
     if (!criteria || Object.keys(criteria).length === 0) {
-      return await this.size();
+      return await this._sizeInternal();
     }
     this.validateQueryParams(criteria);
     const db = this.db;
@@ -463,6 +712,9 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     return parseInt(result.rows[0].count, 10);
   }
   async getBulk(offset, limit) {
+    return this.mutex(() => this._getBulkInternal(offset, limit));
+  }
+  async _getBulkInternal(offset, limit) {
     const db = this.db;
     const orderByClause = this.primaryKeyColumns().map((col) => `"${String(col)}"`).join(", ");
     const result = await db.query(`SELECT * FROM "${this.table}" ORDER BY ${orderByClause} LIMIT $1 OFFSET $2`, [limit, offset]);
@@ -478,32 +730,52 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     return result.rows;
   }
   buildDeleteSearchWhere(criteria) {
-    const conditions = [];
-    const params = [];
-    let paramIndex = 1;
-    for (const column of Object.keys(criteria)) {
-      if (!(column in this.schema.properties)) {
-        throw new Error(`Schema must have a ${String(column)} field to use deleteSearch`);
-      }
-      const criterion = criteria[column];
-      let operator = "=";
-      let value;
-      if (isSearchCondition(criterion)) {
-        operator = criterion.operator;
-        value = criterion.value;
-      } else {
-        value = criterion;
-      }
-      conditions.push(`"${String(column)}" ${operator} $${paramIndex}`);
-      params.push(this.jsToSqlValue(column, value));
-      paramIndex++;
-    }
+    const built = buildSearchWhere(PostgresDialect, criteria, this.schema.properties, (column, value) => this.jsToSqlValue(column, value));
+    return { whereClause: built.whereClause, params: built.params };
+  }
+  async getPage(request = {}) {
+    return this.mutex(() => this._getPageInternal(request));
+  }
+  async _getPageInternal(request) {
+    return this.runSqlPage(undefined, request, this.postgresDialect());
+  }
+  async queryPage(criteria, request = {}) {
+    return this.mutex(() => this._queryPageInternal(criteria, request));
+  }
+  async _queryPageInternal(criteria, request) {
+    this.validateQueryParams(criteria, undefined);
+    return this.runSqlPage(criteria, request, this.postgresDialect());
+  }
+  postgresDialect() {
+    return {
+      quote: '"',
+      placeholder: (index) => `$${index}`,
+      buildSearchWhere: (criteria, startIndex) => this.buildSearchWhereWithIndex(criteria, startIndex),
+      executeSelect: async (sql, params) => {
+        const result = await this.db.query(sql, params);
+        const rows = result.rows ?? [];
+        for (const row of rows) {
+          const record = row;
+          for (const k in this.schema.properties) {
+            record[k] = this.sqlToJsValue(k, record[k]);
+          }
+        }
+        return rows;
+      }
+    };
+  }
+  buildSearchWhereWithIndex(criteria, startIndex) {
+    const built = buildSearchWhere(PostgresDialect, criteria, this.schema.properties, (column, value) => this.jsToSqlValue(column, value), startIndex);
     return {
-      whereClause: conditions.join(" AND "),
-      params
+      whereClause: built.whereClause,
+      params: built.params,
+      nextIndex: startIndex + built.params.length
     };
   }
   async deleteSearch(criteria) {
+    return this.mutex(() => this._deleteSearchInternal(criteria));
+  }
+  async _deleteSearchInternal(criteria) {
     const criteriaKeys = Object.keys(criteria);
     if (criteriaKeys.length === 0) {
       return;
@@ -514,6 +786,9 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     this.events.emit("delete", criteriaKeys[0]);
   }
   async query(criteria, options) {
+    return this.mutex(() => this._queryInternal(criteria, options));
+  }
+  async _queryInternal(criteria, options) {
     this.validateQueryParams(criteria, options);
     const db = this.db;
     let sql = `SELECT * FROM "${this.table}"`;
@@ -546,6 +821,9 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
     return;
   }
   async queryIndex(criteria, options) {
+    return this.mutex(() => this._queryIndexInternal(criteria, options));
+  }
+  async _queryIndexInternal(criteria, options) {
     this.validateSelect(options);
     this.validateQueryParams(criteria, options);
     const registered = this.indexes.map((cols2, i) => {
@@ -596,6 +874,51 @@ class PostgresTabularStorage extends BaseSqlTabularStorage {
   }
 }
 
+class PostgresTabularMigrationApplierImpl extends SqlTabularMigrationApplier {
+  host;
+  constructor(host) {
+    super();
+    this.host = host;
+  }
+  dialectName() {
+    return "postgres";
+  }
+  table() {
+    return this.host.table;
+  }
+  storage() {
+    return this.host;
+  }
+  mapTypeToSQL(typeDef) {
+    return this.host.mapTypeToSQL(typeDef);
+  }
+  isNullableSchema(typeDef) {
+    return this.host.isNullable(typeDef);
+  }
+  async executeSql(sql) {
+    await this.host.db.query(sql);
+  }
+  async executeSqlTx(sql, tx) {
+    await tx.runMigrationDdl(sql);
+  }
+  async recordAppliedTx(component, version, description, tx) {
+    await tx.recordMigrationApplied(component, version, description ?? null);
+  }
+  async recordApplied(component, version, description) {
+    await this.host.db.query(`INSERT INTO ${MIGRATIONS_TABLE}(component, version, description) VALUES ($1, $2, $3)`, [component, version, description ?? null]);
+  }
+  async queryAppliedVersions(component) {
+    const r = await this.host.db.query(`SELECT version FROM ${MIGRATIONS_TABLE} WHERE component = $1`, [component]);
+    return new Set(r.rows.map((row) => Number(row.version)));
+  }
+  async probeTableExists() {
+    const r = await this.host.db.query(`SELECT 1 FROM information_schema.tables WHERE table_name = $1 LIMIT 1`, [
+      this.host.table
+    ]);
+    return r.rows.length > 0;
+  }
+}
+
 // src/storage/PostgresKvStorage.ts
 import {
   DefaultKeyValueKey,
@@ -617,7 +940,12 @@ class PostgresKvStorage extends KvViaTabularStorage {
 }
 // src/storage/PostgresVectorStorage.ts
 import { cosineSimilarity } from "@workglow/util/schema";
-import { StorageValidationError, getMetadataProperty, getVectorProperty } from "@workglow/storage";
+import {
+  PostgresDialect as PostgresDialect2,
+  StorageValidationError,
+  getMetadataProperty,
+  getVectorProperty
+} from "@workglow/storage";
 var SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
 class PostgresVectorStorage extends PostgresTabularStorage {
@@ -625,10 +953,12 @@ class PostgresVectorStorage extends PostgresTabularStorage {
   vectorCtor;
   vectorPropertyName;
   metadataPropertyName;
-  constructor(db, table, schema, primaryKeyNames, indexes = [], dimensions, vectorCtor = Float32Array) {
+  indexOptions;
+  constructor(db, table, schema, primaryKeyNames, indexes = [], dimensions, vectorCtor = Float32Array, indexOptions = {}) {
     super(db, table, schema, primaryKeyNames, indexes);
     this.vectorDimensions = dimensions;
     this.vectorCtor = vectorCtor;
+    this.indexOptions = indexOptions;
     const vectorProp = getVectorProperty(schema);
     if (!vectorProp) {
       throw new Error("Schema must have a property with type array and format TypedArray");
@@ -639,20 +969,58 @@ class PostgresVectorStorage extends PostgresTabularStorage {
   getVectorDimensions() {
     return this.vectorDimensions;
   }
+  getVectorIndexOptions() {
+    return this.indexOptions;
+  }
+  get distance() {
+    return this.indexOptions.distance ?? "cosine";
+  }
+  get distanceOperator() {
+    switch (this.distance) {
+      case "l2":
+        return "<->";
+      case "ip":
+        return "<#>";
+      default:
+        return "<=>";
+    }
+  }
+  buildScoreExpr(vectorExpr, queryParam) {
+    const op = this.distanceOperator;
+    switch (this.distance) {
+      case "l2":
+        return `(1.0 / (1.0 + (${vectorExpr} ${op} ${queryParam}::vector)))`;
+      case "ip":
+        return `(-1.0 * (${vectorExpr} ${op} ${queryParam}::vector))`;
+      default:
+        return `(1 - (${vectorExpr} ${op} ${queryParam}::vector))`;
+    }
+  }
+  getQueryTuning() {
+    return {
+      efSearch: this.indexOptions.hnsw?.efSearch,
+      probes: this.indexOptions.ivfflat?.probes
+    };
+  }
   async similaritySearch(query, options = {}) {
     const { topK = 10, filter, scoreThreshold = 0 } = options;
     try {
       const queryVector = `[${Array.from(query).join(",")}]`;
-      const vectorCol = String(this.vectorPropertyName);
-      const metadataCol = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      const vectorColRaw = String(this.vectorPropertyName);
+      const vectorCol = PostgresDialect2.quoteId(vectorColRaw);
+      const metadataColRaw = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      const metadataCol = metadataColRaw ? PostgresDialect2.quoteId(metadataColRaw) : null;
+      const distOp = this.distanceOperator;
+      const scoreExpr = this.buildScoreExpr(vectorCol, "$1");
       let sql = `
-        SELECT 
+        SELECT
           *,
-          1 - (${vectorCol} <=> $1::vector) as score
+          ${scoreExpr} as score
         FROM "${this.table}"
       `;
       const params = [queryVector];
       let paramIndex = 2;
+      let hasWhere = false;
       if (filter && Object.keys(filter).length > 0 && metadataCol) {
         const conditions = [];
         for (const [key, value] of Object.entries(filter)) {
@@ -663,21 +1031,22 @@ class PostgresVectorStorage extends PostgresTabularStorage {
           params.push(String(value));
           paramIndex++;
         }
-        sql += ` WHERE ${conditions.join(" AND ")}`;
-      }
-      if (scoreThreshold > 0) {
-        sql += filter ? " AND" : " WHERE";
-        sql += ` (1 - (${vectorCol} <=> $1::vector)) >= $${paramIndex}`;
-        params.push(scoreThreshold);
-        paramIndex++;
+        if (conditions.length > 0) {
+          sql += ` WHERE ${conditions.join(" AND ")}`;
+          hasWhere = true;
+        }
       }
-      sql += ` ORDER BY ${vectorCol} <=> $1::vector LIMIT $${paramIndex}`;
+      sql += hasWhere ? " AND" : " WHERE";
+      sql += ` ${scoreExpr} >= $${paramIndex}`;
+      params.push(scoreThreshold);
+      paramIndex++;
+      sql += ` ORDER BY ${vectorCol} ${distOp} $1::vector LIMIT $${paramIndex}`;
       params.push(topK);
       const result = await this.db.query(sql, params);
       const results = [];
       for (const row of result.rows) {
         const vectorResult = await this.db.query(`SELECT ${vectorCol}::text FROM "${this.table}" WHERE ${this.getPrimaryKeyWhereClause()}`, this.getPrimaryKeyValues(row));
-        const vectorStr = vectorResult.rows[0]?.[vectorCol] || "[]";
+        const vectorStr = vectorResult.rows[0]?.[vectorColRaw] || "[]";
         const vectorArray = JSON.parse(vectorStr);
         results.push({
           ...row,
@@ -702,19 +1071,24 @@ class PostgresVectorStorage extends PostgresTabularStorage {
     try {
       const queryVector = `[${Array.from(query).join(",")}]`;
       const tsQueryText = textQuery;
-      const vectorCol = String(this.vectorPropertyName);
-      const metadataCol = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      const vectorColRaw = String(this.vectorPropertyName);
+      const vectorCol = PostgresDialect2.quoteId(vectorColRaw);
+      const metadataColRaw = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      const metadataCol = metadataColRaw ? PostgresDialect2.quoteId(metadataColRaw) : null;
+      const vectorScoreExpr = this.buildScoreExpr(vectorCol, "$1");
+      const combinedScoreExpr = `(
+            $2 * ${vectorScoreExpr} +
+            $3 * ts_rank(to_tsvector('english', ${metadataCol || "''"}::text), plainto_tsquery('english', $4))
+          )`;
       let sql = `
-        SELECT 
+        SELECT
           *,
-          (
-            $2 * (1 - (${vectorCol} <=> $1::vector)) +
-            $3 * ts_rank(to_tsvector('english', ${metadataCol || "''"}::text), plainto_tsquery('english', $4))
-          ) as score
+          ${combinedScoreExpr} as score
         FROM "${this.table}"
       `;
       const params = [queryVector, vectorWeight, 1 - vectorWeight, tsQueryText];
       let paramIndex = 5;
+      let hasWhere = false;
       if (filter && Object.keys(filter).length > 0 && metadataCol) {
         const conditions = [];
         for (const [key, value] of Object.entries(filter)) {
@@ -725,24 +1099,22 @@ class PostgresVectorStorage extends PostgresTabularStorage {
           params.push(String(value));
           paramIndex++;
         }
-        sql += ` WHERE ${conditions.join(" AND ")}`;
-      }
-      if (scoreThreshold > 0) {
-        sql += filter ? " AND" : " WHERE";
-        sql += ` (
-          $2 * (1 - (${vectorCol} <=> $1::vector)) +
-          $3 * ts_rank(to_tsvector('english', ${metadataCol || "''"}::text), plainto_tsquery('english', $4))
-        ) >= $${paramIndex}`;
-        params.push(scoreThreshold);
-        paramIndex++;
+        if (conditions.length > 0) {
+          sql += ` WHERE ${conditions.join(" AND ")}`;
+          hasWhere = true;
+        }
       }
+      sql += hasWhere ? " AND" : " WHERE";
+      sql += ` ${combinedScoreExpr} >= $${paramIndex}`;
+      params.push(scoreThreshold);
+      paramIndex++;
       sql += ` ORDER BY score DESC LIMIT $${paramIndex}`;
       params.push(topK);
       const result = await this.db.query(sql, params);
       const results = [];
       for (const row of result.rows) {
         const vectorResult = await this.db.query(`SELECT ${vectorCol}::text FROM "${this.table}" WHERE ${this.getPrimaryKeyWhereClause()}`, this.getPrimaryKeyValues(row));
-        const vectorStr = vectorResult.rows[0]?.[vectorCol] || "[]";
+        const vectorStr = vectorResult.rows[0]?.[vectorColRaw] || "[]";
         const vectorArray = JSON.parse(vectorStr);
         results.push({
           ...row,
@@ -759,7 +1131,13 @@ class PostgresVectorStorage extends PostgresTabularStorage {
       return this.hybridSearchFallback(query, options);
     }
   }
+  assertFallbackSupportsDistance() {
+    if (this.distance !== "cosine") {
+      throw new Error(`PostgresVectorStorage: pgvector is unavailable and the in-memory ` + `fallback only supports cosine distance (configured: "${this.distance}"). ` + `Install pgvector or switch the storage to cosine distance.`);
+    }
+  }
   async searchFallback(query, options) {
+    this.assertFallbackSupportsDistance();
     const { topK = 10, filter, scoreThreshold = 0 } = options;
     const allRows = await this.getAll() || [];
     const results = [];
@@ -779,6 +1157,7 @@ class PostgresVectorStorage extends PostgresTabularStorage {
     return topResults;
   }
   async hybridSearchFallback(query, options) {
+    this.assertFallbackSupportsDistance();
     const { topK = 10, filter, scoreThreshold = 0, textQuery, vectorWeight = 0.7 } = options;
     const allRows = await this.getAll() || [];
     const results = [];
@@ -827,16 +1206,126 @@ class PostgresVectorStorage extends PostgresTabularStorage {
     return true;
   }
 }
+// src/migrations/PostgresMigrationRunner.ts
+import {
+  MIGRATIONS_TABLE as MIGRATIONS_TABLE2,
+  sortMigrations
+} from "@workglow/storage";
+
+class PostgresMigrationRunner {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  async ensureBookkeepingTable() {
+    await this.db.query(`
+      CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE2} (
+        component TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        description TEXT,
+        applied_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        PRIMARY KEY (component, version)
+      )
+    `);
+  }
+  async appliedVersions(component) {
+    const result = await this.db.query(`SELECT version FROM ${MIGRATIONS_TABLE2} WHERE component = $1`, [component]);
+    return new Set(result.rows.map((r) => Number(r.version)));
+  }
+  async acquireClient() {
+    const pool = this.db;
+    if (typeof pool.connect === "function") {
+      const client = await pool.connect();
+      return { client, release: () => client.release() };
+    }
+    return { client: this.db, release: () => {
+      return;
+    } };
+  }
+  async run(migrations, options = {}) {
+    await this.ensureBookkeepingTable();
+    const sorted = sortMigrations(migrations);
+    const applied = [];
+    const cache = new Map;
+    const onProgress = options.onProgress;
+    for (const m of sorted) {
+      let seen = cache.get(m.component);
+      if (!seen) {
+        seen = await this.appliedVersions(m.component);
+        cache.set(m.component, seen);
+      }
+      if (seen.has(m.version))
+        continue;
+      onProgress?.({
+        component: m.component,
+        version: m.version,
+        phase: "starting",
+        description: m.description
+      });
+      const { client, release } = await this.acquireClient();
+      try {
+        await client.query("BEGIN");
+        await m.up(client, (fraction) => {
+          onProgress?.({
+            component: m.component,
+            version: m.version,
+            phase: "running",
+            description: m.description,
+            fraction
+          });
+        });
+        await client.query(`INSERT INTO ${MIGRATIONS_TABLE2}(component, version, description) VALUES ($1, $2, $3)`, [m.component, m.version, m.description ?? null]);
+        await client.query("COMMIT");
+        seen.add(m.version);
+        applied.push(m);
+        onProgress?.({
+          component: m.component,
+          version: m.version,
+          phase: "completed",
+          description: m.description,
+          fraction: 1
+        });
+      } catch (err) {
+        await client.query("ROLLBACK").catch(() => {
+          return;
+        });
+        if (err?.code === "23505") {
+          seen.add(m.version);
+          onProgress?.({
+            component: m.component,
+            version: m.version,
+            phase: "completed",
+            description: m.description,
+            fraction: 1
+          });
+          continue;
+        }
+        onProgress?.({
+          component: m.component,
+          version: m.version,
+          phase: "failed",
+          description: m.description,
+          error: err
+        });
+        throw err;
+      } finally {
+        release();
+      }
+    }
+    return applied;
+  }
+}
 export {
   loadPostgres,
   getPostgres,
   createPool,
   PostgresVectorStorage,
   PostgresTabularStorage,
+  PostgresMigrationRunner,
   PostgresKvStorage,
   Postgres,
   POSTGRES_TABULAR_REPOSITORY,
   POSTGRES_KV_REPOSITORY
 };
 
-//# debugId=EAED4AF57300AAC364756E2164756E21
+//# debugId=1C3E72F1BE3B8A0064756E2164756E21