@mastra/pg 1.16.1-alpha.0 → 1.17.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mastra/pg
 
+## 1.17.0-alpha.1
+
+### Minor Changes
+
+- Added PgFactoryStorage for persisting Mastra agent state and lifecycle-managed application domains through one PostgreSQL pool. ([#19681](https://github.com/mastra-ai/mastra/pull/19681))
+
+  ```ts
+  import { PgFactoryStorage } from '@mastra/pg';
+
+  const storage = new PgFactoryStorage({ connectionString: process.env.DATABASE_URL! });
+  await storage.init();
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`3b77e77`](https://github.com/mastra-ai/mastra/commit/3b77e7704936522e4769d29de1b5ea6901f302bd), [`6b1bf3b`](https://github.com/mastra-ai/mastra/commit/6b1bf3b9494bd51aa8f654c68c9355d6046fa2a1), [`72e437c`](https://github.com/mastra-ai/mastra/commit/72e437c515942c80b9def5b026e0bdee61b469d9)]:
+  - @mastra/core@1.52.0-alpha.8
+
 ## 1.16.1-alpha.0
 
 ### Patch Changes
@@ -1080,9 +1098,7 @@
   **Example**
 
   ```ts
-  const storage = new LibSQLStore({
-    /* config */
-  });
+  const storage = new LibSQLStore({/* config */});
   const favorites = await storage.getStore('favorites');
 
   await favorites?.favorite({
@@ -1110,9 +1126,7 @@
   **Example**
 
   ```ts
-  const storage = new LibSQLStore({
-    /* config */
-  });
+  const storage = new LibSQLStore({/* config */});
   const favorites = await storage.getStore('favorites');
 
   await favorites?.favorite({

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.16.1-alpha.0"
+  version: "1.17.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.16.1-alpha.0",
+  "version": "1.17.0-alpha.1",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -269,6 +269,28 @@ const chromaQueryTool = createVectorQueryTool({
 - **whereDocument**: Filter by document content
 - **Use Cases**: Advanced filtering, content-based search
 
+**Turbopuffer**:
+
+### Turbopuffer Configuration
+
+```typescript
+const turbopufferQueryTool = createVectorQueryTool({
+  vectorStoreName: 'turbopuffer',
+  indexName: 'docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  databaseConfig: {
+    turbopuffer: {
+      consistency: 'eventual', // Lower latency, recently written data may not be visible yet
+    },
+  },
+})
+```
+
+**Turbopuffer Features:**
+
+- **consistency**: Choose between `strong` (default, read-your-writes) and `eventual` (lower latency)
+- **Use Cases**: Latency-sensitive queries where slightly stale data is acceptable
+
 **Multiple Configs**:
 
 ### Multiple Database Configurations

package/dist/index.cjs

@@ -20197,6 +20197,435 @@ var WorkspacesPG = class _WorkspacesPG extends storage.WorkspacesStorage {
     };
   }
 };
+var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PG_UNIQUE_VIOLATION = "23505";
+var COLUMN_DDL = {
+  text: "TEXT",
+  bigint: "BIGINT",
+  integer: "INTEGER",
+  boolean: "BOOLEAN",
+  json: "JSONB",
+  timestamp: "TIMESTAMPTZ",
+  "uuid-pk": "UUID"
+};
+function assertIdentifier(kind, name) {
+  if (!IDENTIFIER_RE.test(name)) {
+    throw new Error(`PgFactoryStorage: invalid ${kind} identifier '${name}'`);
+  }
+}
+function isUniqueViolation(error) {
+  return typeof error === "object" && error !== null && error.code === PG_UNIQUE_VIOLATION;
+}
+function primaryKeyOf(schema) {
+  const pks = Object.entries(schema.columns).filter(([, spec]) => spec.type === "uuid-pk" || spec.primaryKey);
+  if (pks.length !== 1) {
+    throw new Error(
+      `PgFactoryStorage: collection '${schema.name}' must declare exactly one primary key (found ${pks.length})`
+    );
+  }
+  return pks[0][0];
+}
+function assertUpsertConflict(schema, conflictKeys, row) {
+  const keys = new Set(conflictKeys);
+  if (keys.size !== conflictKeys.length || conflictKeys.some((key) => row[key] === void 0)) {
+    throw new Error(
+      `PgFactoryStorage: upsert conflict keys for '${schema.name}' must be unique and present in the row`
+    );
+  }
+  const primaryKey = primaryKeyOf(schema);
+  const candidates = [{ columns: [primaryKey] }, ...schema.uniqueIndexes ?? []];
+  const matches = candidates.some((candidate) => {
+    if (candidate.columns.length !== keys.size || candidate.columns.some((column) => !keys.has(column))) return false;
+    if ("whereNotNull" in candidate && candidate.whereNotNull && row[candidate.whereNotNull] == null) return false;
+    if ("whereNull" in candidate && candidate.whereNull && row[candidate.whereNull] != null) return false;
+    return true;
+  });
+  if (!matches) {
+    throw new Error(
+      `PgFactoryStorage: upsert conflict keys [${conflictKeys.join(", ")}] do not match an applicable primary key or unique index on '${schema.name}'`
+    );
+  }
+}
+function serializeDefault(value) {
+  if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+  return String(value);
+}
+function hashAdvisoryLockKey(key) {
+  const digest = crypto$1.createHash("sha256").update(key).digest();
+  return [digest.readInt32BE(0), digest.readInt32BE(4)];
+}
+var PgFactoryStorageOps = class {
+  #pool;
+  #schemas;
+  constructor(pool, schemas) {
+    this.#pool = pool;
+    this.#schemas = schemas;
+  }
+  #schema(collection) {
+    const schema = this.#schemas.get(collection);
+    if (!schema) {
+      throw new Error(
+        `PgFactoryStorage: unknown collection '${collection}' \u2014 register it via ensureCollections() first`
+      );
+    }
+    return schema;
+  }
+  #column(schema, column) {
+    const spec = schema.columns[column];
+    if (!spec) {
+      throw new Error(`PgFactoryStorage: unknown column '${column}' on collection '${schema.name}'`);
+    }
+    return spec;
+  }
+  #serialize(spec, value) {
+    if (value === null || value === void 0) return null;
+    switch (spec.type) {
+      case "timestamp":
+        return value instanceof Date ? value : new Date(String(value));
+      case "boolean":
+        return Boolean(value);
+      case "json":
+        return JSON.stringify(value);
+      case "bigint":
+      case "integer":
+        return Number(value);
+      default:
+        return String(value);
+    }
+  }
+  #deserializeRow(schema, raw) {
+    const row = {};
+    for (const [name, spec] of Object.entries(schema.columns)) {
+      const value = raw[name];
+      if (value === null || value === void 0) {
+        row[name] = null;
+        continue;
+      }
+      switch (spec.type) {
+        case "timestamp":
+          row[name] = value instanceof Date ? value : new Date(String(value));
+          break;
+        case "boolean":
+          row[name] = Boolean(value);
+          break;
+        case "json":
+          row[name] = typeof value === "string" ? JSON.parse(value) : value;
+          break;
+        case "bigint":
+        case "integer":
+          row[name] = Number(value);
+          break;
+        default:
+          row[name] = String(value);
+      }
+    }
+    return row;
+  }
+  /** Builds `WHERE` SQL (without the keyword). `{}` yields a match-all clause. */
+  #buildWhere(schema, where, startIndex = 1) {
+    const clauses = [];
+    const args = [];
+    let index = startIndex;
+    for (const [column, condition] of Object.entries(where)) {
+      const spec = this.#column(schema, column);
+      if (condition !== null && typeof condition === "object" && !(condition instanceof Date) && "in" in condition) {
+        if (condition.in.length === 0) {
+          clauses.push("FALSE");
+          continue;
+        }
+        const nonNull = condition.in.filter((value) => value !== null);
+        const includesNull = nonNull.length !== condition.in.length;
+        const inClause = nonNull.length > 0 ? `"${column}" IN (${nonNull.map(() => `$${index++}`).join(", ")})` : void 0;
+        clauses.push(
+          inClause && includesNull ? `(${inClause} OR "${column}" IS NULL)` : inClause ?? `"${column}" IS NULL`
+        );
+        args.push(...nonNull.map((value) => this.#serialize(spec, value)));
+      } else if (condition === null) {
+        clauses.push(`"${column}" IS NULL`);
+      } else {
+        clauses.push(`"${column}" = $${index++}`);
+        args.push(this.#serialize(spec, condition));
+      }
+    }
+    return { sql: clauses.length > 0 ? clauses.join(" AND ") : "TRUE", args, nextIndex: index };
+  }
+  /** Keyset condition: rows strictly after `cursor.values` in the `orderBy` order. */
+  #buildCursor(schema, orderBy, values, startIndex) {
+    if (values.length !== orderBy.length) {
+      throw new Error(`PgFactoryStorage: cursor has ${values.length} values but orderBy has ${orderBy.length} columns`);
+    }
+    const branches = [];
+    const args = [];
+    let index = startIndex;
+    for (let i = 0; i < orderBy.length; i++) {
+      const parts = [];
+      for (let j = 0; j < i; j++) {
+        const [column2] = orderBy[j];
+        parts.push(`"${column2}" = $${index++}`);
+        args.push(this.#serialize(this.#column(schema, column2), values[j]));
+      }
+      const [column, dir] = orderBy[i];
+      parts.push(`"${column}" ${dir === "desc" ? "<" : ">"} $${index++}`);
+      args.push(this.#serialize(this.#column(schema, column), values[i]));
+      branches.push(`(${parts.join(" AND ")})`);
+    }
+    return { sql: `(${branches.join(" OR ")})`, args, nextIndex: index };
+  }
+  #buildSelect(schema, where, opts, forUpdate = false) {
+    const filter = this.#buildWhere(schema, where);
+    let sql = `SELECT * FROM "${schema.name}" WHERE ${filter.sql}`;
+    const args = [...filter.args];
+    let index = filter.nextIndex;
+    if (opts?.cursor) {
+      if (!opts.orderBy || opts.orderBy.length === 0) {
+        throw new Error("PgFactoryStorage: cursor pagination requires orderBy");
+      }
+      const cursor = this.#buildCursor(schema, opts.orderBy, opts.cursor.values, index);
+      sql += ` AND ${cursor.sql}`;
+      args.push(...cursor.args);
+      index = cursor.nextIndex;
+    }
+    if (opts?.orderBy && opts.orderBy.length > 0) {
+      const order = opts.orderBy.map(([column, dir]) => {
+        this.#column(schema, column);
+        return `"${column}" ${dir === "desc" ? "DESC" : "ASC"}`;
+      }).join(", ");
+      sql += ` ORDER BY ${order}`;
+    }
+    if (opts?.limit !== void 0) {
+      sql += ` LIMIT $${index++}`;
+      args.push(opts.limit);
+    }
+    if (forUpdate) sql += " FOR UPDATE";
+    return { sql, args };
+  }
+  async #select(queryable, collection, where, opts, forUpdate = false) {
+    const schema = this.#schema(collection);
+    const { sql, args } = this.#buildSelect(schema, where, opts, forUpdate);
+    const result = await queryable.query(sql, args);
+    return result.rows.map((raw) => this.#deserializeRow(schema, raw));
+  }
+  async findOne(collection, where) {
+    const rows = await this.#select(this.#pool, collection, where, { limit: 1 });
+    return rows[0] ?? null;
+  }
+  async findMany(collection, where, opts) {
+    return this.#select(this.#pool, collection, where, opts);
+  }
+  async insertOne(collection, row) {
+    const schema = this.#schema(collection);
+    const pk = primaryKeyOf(schema);
+    const values = { ...row };
+    if (schema.columns[pk].type === "uuid-pk" && values[pk] === void 0) {
+      values[pk] = crypto$1.randomUUID();
+    }
+    const columns = Object.keys(values).filter((column) => values[column] !== void 0);
+    for (const column of columns) this.#column(schema, column);
+    const sql = `INSERT INTO "${schema.name}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${columns.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING *`;
+    const args = columns.map((column) => this.#serialize(this.#column(schema, column), values[column]));
+    try {
+      const result = await this.#pool.query(sql, args);
+      return this.#deserializeRow(schema, result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error)) throw new storage.UniqueViolationError(collection, { cause: error });
+      throw error;
+    }
+  }
+  async upsertOne(collection, conflictKeys, row) {
+    const schema = this.#schema(collection);
+    const pk = primaryKeyOf(schema);
+    assertUpsertConflict(schema, conflictKeys, row);
+    const keyWhere = Object.fromEntries(conflictKeys.map((key) => [key, row[key]]));
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const existing = await this.findOne(collection, keyWhere);
+      if (existing) {
+        const set = Object.fromEntries(
+          Object.entries(row).filter(
+            ([column, value]) => value !== void 0 && column !== pk && !conflictKeys.includes(column)
+          )
+        );
+        if (Object.keys(set).length > 0) {
+          await this.updateMany(collection, { [pk]: existing[pk] }, set);
+        }
+        const updated = await this.findOne(collection, { [pk]: existing[pk] });
+        if (!updated) continue;
+        return updated;
+      }
+      try {
+        return await this.insertOne(collection, row);
+      } catch (error) {
+        if (!(error instanceof storage.UniqueViolationError)) throw error;
+        lastError = error;
+      }
+    }
+    throw lastError ?? new Error(`PgFactoryStorage: upsert into '${collection}' did not converge`);
+  }
+  async updateMany(collection, where, set) {
+    return this.#updateMany(this.#pool, collection, where, set);
+  }
+  async #updateMany(queryable, collection, where, set) {
+    const schema = this.#schema(collection);
+    const columns = Object.keys(set).filter((column) => set[column] !== void 0);
+    if (columns.length === 0) return 0;
+    const assignments = columns.map((column, i) => `"${column}" = $${i + 1}`).join(", ");
+    const filter = this.#buildWhere(schema, where, columns.length + 1);
+    const args = [...columns.map((column) => this.#serialize(this.#column(schema, column), set[column])), ...filter.args];
+    const result = await queryable.query(`UPDATE "${schema.name}" SET ${assignments} WHERE ${filter.sql}`, args);
+    return result.rowCount ?? 0;
+  }
+  async deleteMany(collection, where) {
+    const schema = this.#schema(collection);
+    const filter = this.#buildWhere(schema, where);
+    const result = await this.#pool.query(`DELETE FROM "${schema.name}" WHERE ${filter.sql}`, filter.args);
+    return result.rowCount ?? 0;
+  }
+  async updateAtomic(collection, where, fn) {
+    const schema = this.#schema(collection);
+    const pk = primaryKeyOf(schema);
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      try {
+        const rows = await this.#select(client, collection, where, { limit: 1 }, true);
+        const row = rows[0];
+        if (!row) {
+          await client.query("COMMIT");
+          return null;
+        }
+        const patch = await fn(row);
+        let result = row;
+        if (patch !== null) {
+          const pkWhere = { [pk]: row[pk] };
+          await this.#updateMany(client, collection, pkWhere, patch);
+          const updated = await this.#select(client, collection, pkWhere, { limit: 1 });
+          result = updated[0] ?? null;
+        }
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    } finally {
+      client.release();
+    }
+  }
+};
+var PgFactoryStorage = class extends storage.FactoryStorage {
+  ops;
+  #pool;
+  #ownsPool;
+  #config;
+  #schemas = /* @__PURE__ */ new Map();
+  #mastraStorage;
+  constructor(config) {
+    super();
+    this.#config = config;
+    if ("store" in config) {
+      this.#pool = config.store.pool;
+      this.#ownsPool = false;
+      this.#mastraStorage = config.store;
+    } else {
+      this.#pool = new pg__namespace.default.Pool({ connectionString: config.connectionString });
+      this.#ownsPool = true;
+    }
+    this.ops = new PgFactoryStorageOps(this.#pool, this.#schemas);
+  }
+  getMastraStorage() {
+    if (!this.#mastraStorage) {
+      const config = this.#config;
+      this.#mastraStorage = new PostgresStore({
+        id: config.id ?? "pg-factory",
+        pool: this.#pool,
+        ...config.retention ? { retention: config.retention } : {}
+      });
+    }
+    return this.#mastraStorage;
+  }
+  async initStorage() {
+    await this.#pool.query("SELECT 1");
+  }
+  async ensureCollections(schemas) {
+    for (const schema of schemas) {
+      await this.#ensureCollection(schema);
+      this.#schemas.set(schema.name, schema);
+    }
+  }
+  async close() {
+    if (this.#ownsPool) {
+      await this.#pool.end();
+    } else {
+      await this.#mastraStorage?.close();
+    }
+  }
+  authDatabase() {
+    return { dialect: "postgres", pool: this.#pool };
+  }
+  /**
+   * Run `fn` while holding a Postgres transaction-scoped advisory lock for
+   * `key`, serializing callers across replicas. The lock releases when the
+   * transaction ends (commit, rollback, or connection loss), so a crashed
+   * replica can never hold it forever.
+   */
+  async withDistributedLock(key, fn) {
+    const [k1, k2] = hashAdvisoryLockKey(key);
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock($1, $2)", [k1, k2]);
+      try {
+        const result = await fn();
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    } finally {
+      client.release();
+    }
+  }
+  #columnDdl(name, spec) {
+    assertIdentifier("column", name);
+    let ddl = `"${name}" ${COLUMN_DDL[spec.type]}`;
+    if (spec.type === "uuid-pk" || spec.primaryKey) ddl += " PRIMARY KEY";
+    if (!spec.nullable && spec.type !== "uuid-pk" && !spec.primaryKey) ddl += " NOT NULL";
+    if (spec.default !== void 0) ddl += ` DEFAULT ${serializeDefault(spec.default)}`;
+    return ddl;
+  }
+  async #ensureCollection(schema) {
+    assertIdentifier("collection", schema.name);
+    primaryKeyOf(schema);
+    const columns = Object.entries(schema.columns).map(([name, spec]) => this.#columnDdl(name, spec));
+    await this.#pool.query(`CREATE TABLE IF NOT EXISTS "${schema.name}" (${columns.join(", ")})`);
+    for (const [name, spec] of Object.entries(schema.columns)) {
+      await this.#pool.query(`ALTER TABLE "${schema.name}" ADD COLUMN IF NOT EXISTS ${this.#columnDdl(name, spec)}`);
+    }
+    for (const index of schema.uniqueIndexes ?? []) {
+      assertIdentifier("index", index.name);
+      index.columns.forEach((column) => assertIdentifier("column", column));
+      let where = "";
+      if (index.whereNotNull) {
+        assertIdentifier("column", index.whereNotNull);
+        where = ` WHERE "${index.whereNotNull}" IS NOT NULL`;
+      } else if (index.whereNull) {
+        assertIdentifier("column", index.whereNull);
+        where = ` WHERE "${index.whereNull}" IS NULL`;
+      }
+      await this.#pool.query(
+        `CREATE UNIQUE INDEX IF NOT EXISTS "${index.name}" ON "${schema.name}" (${index.columns.map((c) => `"${c}"`).join(", ")})${where}`
+      );
+    }
+    for (const index of schema.indexes ?? []) {
+      assertIdentifier("index", index.name);
+      index.columns.forEach((column) => assertIdentifier("column", column));
+      await this.#pool.query(
+        `CREATE INDEX IF NOT EXISTS "${index.name}" ON "${schema.name}" (${index.columns.map((c) => `"${c}"`).join(", ")})`
+      );
+    }
+  }
+};
 
 // src/storage/index.ts
 var DEFAULT_MAX_CONNECTIONS = 20;
@@ -20602,6 +21031,7 @@ exports.NotificationsPG = NotificationsPG;
 exports.ObservabilityPG = ObservabilityPG;
 exports.ObservabilityStoragePostgresVNext = ObservabilityStoragePostgresVNext;
 exports.PGVECTOR_PROMPT = PGVECTOR_PROMPT;
+exports.PgFactoryStorage = PgFactoryStorage;
 exports.PgVector = PgVector;
 exports.PoolAdapter = PoolAdapter;
 exports.PostgresStore = PostgresStore;
@@ -20615,5 +21045,6 @@ exports.ToolProviderConnectionsPG = ToolProviderConnectionsPG;
 exports.WorkflowsPG = WorkflowsPG;
 exports.WorkspacesPG = WorkspacesPG;
 exports.exportSchemas = exportSchemas;
+exports.hashAdvisoryLockKey = hashAdvisoryLockKey;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map