@mastra/pg 0.15.2 → 0.15.3-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mastra/pg
 
+## 0.15.3-alpha.1
+
+### Patch Changes
+
+- Postgresql Storage Query Index Performance: Adds index operations and automatic indexing for Postgresql ([#7757](https://github.com/mastra-ai/mastra/pull/7757))
+
+- Updated dependencies [[`60c9cec`](https://github.com/mastra-ai/mastra/commit/60c9cec7048a79a87440f7840c383875bd710d93), [`897995e`](https://github.com/mastra-ai/mastra/commit/897995e630d572fe2891e7ede817938cabb43251)]:
+  - @mastra/core@0.16.4-alpha.2
+
+## 0.15.3-alpha.0
+
+### Patch Changes
+
+- Add resource id to workflow run snapshots ([#7740](https://github.com/mastra-ai/mastra/pull/7740))
+
+- Updated dependencies [[`547c621`](https://github.com/mastra-ai/mastra/commit/547c62104af3f7a551b3754e9cbdf0a3fbba15e4)]:
+  - @mastra/core@0.16.4-alpha.1
+
 ## 0.15.2
 
 ### Patch Changes

package/README.md

@@ -160,6 +160,129 @@ Example filter:
 - `getMessages(threadId)`: Get all messages for a thread
 - `deleteMessages(messageIds)`: Delete specific messages
 
+## Index Management
+
+The PostgreSQL store provides comprehensive index management capabilities to optimize query performance.
+
+### Automatic Performance Indexes
+
+PostgreSQL storage automatically creates composite indexes during initialization for common query patterns:
+
+- `mastra_threads_resourceid_createdat_idx`: (resourceId, createdAt DESC)
+- `mastra_messages_thread_id_createdat_idx`: (thread_id, createdAt DESC)
+- `mastra_traces_name_starttime_idx`: (name, startTime DESC)
+- `mastra_evals_agent_name_created_at_idx`: (agent_name, created_at DESC)
+
+These indexes significantly improve performance for filtered queries with sorting.
+
+### Creating Custom Indexes
+
+Create additional indexes to optimize specific query patterns:
+
+```typescript
+// Basic index for common queries
+await store.createIndex({
+  name: 'idx_threads_resource',
+  table: 'mastra_threads',
+  columns: ['resourceId'],
+});
+
+// Composite index with sort order for filtering + sorting
+await store.createIndex({
+  name: 'idx_messages_composite',
+  table: 'mastra_messages',
+  columns: ['thread_id', 'createdAt DESC'],
+});
+
+// GIN index for JSONB columns (fast JSON queries)
+await store.createIndex({
+  name: 'idx_traces_attributes',
+  table: 'mastra_traces',
+  columns: ['attributes'],
+  method: 'gin',
+});
+```
+
+For more advanced use cases, you can also use:
+
+- `unique: true` for unique constraints
+- `where: 'condition'` for partial indexes
+- `method: 'brin'` for time-series data
+- `storage: { fillfactor: 90 }` for update-heavy tables
+- `concurrent: true` for non-blocking creation (default)
+
+### Managing Indexes
+
+```typescript
+// List all indexes
+const allIndexes = await store.listIndexes();
+
+// List indexes for specific table
+const threadIndexes = await store.listIndexes('mastra_threads');
+
+// Get detailed statistics for an index
+const stats = await store.describeIndex('idx_threads_resource');
+console.log(stats);
+// {
+//   name: 'idx_threads_resource',
+//   table: 'mastra_threads',
+//   columns: ['resourceId', 'createdAt'],
+//   unique: false,
+//   size: '128 KB',
+//   definition: 'CREATE INDEX idx_threads_resource...',
+//   method: 'btree',
+//   scans: 1542,           // Number of index scans
+//   tuples_read: 45230,    // Tuples read via index
+//   tuples_fetched: 12050  // Tuples fetched via index
+// }
+
+// Drop an index
+await store.dropIndex('idx_threads_status');
+```
+
+### Index Types and Use Cases
+
+| Index Type          | Best For                                | Storage    | Speed                      |
+| ------------------- | --------------------------------------- | ---------- | -------------------------- |
+| **btree** (default) | Range queries, sorting, general purpose | Moderate   | Fast                       |
+| **hash**            | Equality comparisons only               | Small      | Very fast for `=`          |
+| **gin**             | JSONB, arrays, full-text search         | Large      | Fast for contains          |
+| **gist**            | Geometric data, full-text search        | Moderate   | Fast for nearest-neighbor  |
+| **spgist**          | Non-balanced data, text patterns        | Small      | Fast for specific patterns |
+| **brin**            | Large tables with natural ordering      | Very small | Fast for ranges            |
+
+### Index Options
+
+- `name` (required): Index name
+- `table` (required): Table name
+- `columns` (required): Array of column names (can include DESC/ASC)
+- `unique`: Create unique index (default: false)
+- `concurrent`: Non-blocking index creation (default: true)
+- `where`: Partial index condition
+- `method`: Index type ('btree' | 'hash' | 'gin' | 'gist' | 'spgist' | 'brin')
+- `opclass`: Operator class for GIN/GIST indexes
+- `storage`: Storage parameters (e.g., { fillfactor: 90 })
+- `tablespace`: Tablespace name for index placement
+
+### Monitoring Index Performance
+
+```typescript
+// Check index usage statistics
+const stats = await store.describeIndex('idx_threads_resource');
+
+// Identify unused indexes
+if (stats.scans === 0) {
+  console.log(`Index ${stats.name} is unused - consider removing`);
+  await store.dropIndex(stats.name);
+}
+
+// Monitor index efficiency
+const efficiency = stats.tuples_fetched / stats.tuples_read;
+if (efficiency < 0.5) {
+  console.log(`Index ${stats.name} has low efficiency: ${efficiency}`);
+}
+```
+
 ## Related Links
 
 - [pgvector Documentation](https://github.com/pgvector/pgvector)

package/dist/index.cjs

@@ -2374,6 +2374,303 @@ var StoreOperationsPG = class extends storage.StoreOperations {
       );
     }
   }
+  /**
+   * Create a new index on a table
+   */
+  async createIndex(options) {
+    try {
+      const {
+        name,
+        table,
+        columns,
+        unique = false,
+        concurrent = true,
+        where,
+        method = "btree",
+        opclass,
+        storage,
+        tablespace
+      } = options;
+      const schemaName = this.schemaName || "public";
+      const fullTableName = getTableName({
+        indexName: table,
+        schemaName: getSchemaName(this.schemaName)
+      });
+      const indexExists = await this.client.oneOrNone(
+        `SELECT 1 FROM pg_indexes 
+         WHERE indexname = $1 
+         AND schemaname = $2`,
+        [name, schemaName]
+      );
+      if (indexExists) {
+        return;
+      }
+      const uniqueStr = unique ? "UNIQUE " : "";
+      const concurrentStr = concurrent ? "CONCURRENTLY " : "";
+      const methodStr = method !== "btree" ? `USING ${method} ` : "";
+      const columnsStr = columns.map((col) => {
+        if (col.includes(" DESC") || col.includes(" ASC")) {
+          const [colName, ...modifiers] = col.split(" ");
+          if (!colName) {
+            throw new Error(`Invalid column specification: ${col}`);
+          }
+          const quotedCol2 = `"${utils.parseSqlIdentifier(colName, "column name")}" ${modifiers.join(" ")}`;
+          return opclass ? `${quotedCol2} ${opclass}` : quotedCol2;
+        }
+        const quotedCol = `"${utils.parseSqlIdentifier(col, "column name")}"`;
+        return opclass ? `${quotedCol} ${opclass}` : quotedCol;
+      }).join(", ");
+      const whereStr = where ? ` WHERE ${where}` : "";
+      const tablespaceStr = tablespace ? ` TABLESPACE ${tablespace}` : "";
+      let withStr = "";
+      if (storage && Object.keys(storage).length > 0) {
+        const storageParams = Object.entries(storage).map(([key, value]) => `${key} = ${value}`).join(", ");
+        withStr = ` WITH (${storageParams})`;
+      }
+      const sql = `CREATE ${uniqueStr}INDEX ${concurrentStr}${name} ON ${fullTableName} ${methodStr}(${columnsStr})${withStr}${tablespaceStr}${whereStr}`;
+      await this.client.none(sql);
+    } catch (error$1) {
+      if (error$1 instanceof Error && error$1.message.includes("CONCURRENTLY")) {
+        const retryOptions = { ...options, concurrent: false };
+        return this.createIndex(retryOptions);
+      }
+      throw new error.MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_INDEX_CREATE_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName: options.name,
+            tableName: options.table
+          }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Drop an existing index
+   */
+  async dropIndex(indexName) {
+    try {
+      const schemaName = this.schemaName || "public";
+      const indexExists = await this.client.oneOrNone(
+        `SELECT 1 FROM pg_indexes 
+         WHERE indexname = $1 
+         AND schemaname = $2`,
+        [indexName, schemaName]
+      );
+      if (!indexExists) {
+        return;
+      }
+      const sql = `DROP INDEX IF EXISTS ${getSchemaName(this.schemaName)}.${indexName}`;
+      await this.client.none(sql);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_INDEX_DROP_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName
+          }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * List indexes for a specific table or all tables
+   */
+  async listIndexes(tableName) {
+    try {
+      const schemaName = this.schemaName || "public";
+      let query;
+      let params;
+      if (tableName) {
+        query = `
+          SELECT 
+            i.indexname as name,
+            i.tablename as table,
+            i.indexdef as definition,
+            ix.indisunique as is_unique,
+            pg_size_pretty(pg_relation_size(c.oid)) as size,
+            array_agg(a.attname ORDER BY array_position(ix.indkey, a.attnum)) as columns
+          FROM pg_indexes i
+          JOIN pg_class c ON c.relname = i.indexname AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = i.schemaname)
+          JOIN pg_index ix ON ix.indexrelid = c.oid
+          JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = ANY(ix.indkey)
+          WHERE i.schemaname = $1 
+          AND i.tablename = $2
+          GROUP BY i.indexname, i.tablename, i.indexdef, ix.indisunique, c.oid
+        `;
+        params = [schemaName, tableName];
+      } else {
+        query = `
+          SELECT 
+            i.indexname as name,
+            i.tablename as table,
+            i.indexdef as definition,
+            ix.indisunique as is_unique,
+            pg_size_pretty(pg_relation_size(c.oid)) as size,
+            array_agg(a.attname ORDER BY array_position(ix.indkey, a.attnum)) as columns
+          FROM pg_indexes i
+          JOIN pg_class c ON c.relname = i.indexname AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = i.schemaname)
+          JOIN pg_index ix ON ix.indexrelid = c.oid
+          JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = ANY(ix.indkey)
+          WHERE i.schemaname = $1
+          GROUP BY i.indexname, i.tablename, i.indexdef, ix.indisunique, c.oid
+        `;
+        params = [schemaName];
+      }
+      const results = await this.client.manyOrNone(query, params);
+      return results.map((row) => {
+        let columns = [];
+        if (typeof row.columns === "string" && row.columns.startsWith("{") && row.columns.endsWith("}")) {
+          const arrayContent = row.columns.slice(1, -1);
+          columns = arrayContent ? arrayContent.split(",") : [];
+        } else if (Array.isArray(row.columns)) {
+          columns = row.columns;
+        }
+        return {
+          name: row.name,
+          table: row.table,
+          columns,
+          unique: row.is_unique || false,
+          size: row.size || "0",
+          definition: row.definition || ""
+        };
+      });
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_INDEX_LIST_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: tableName ? {
+            tableName
+          } : {}
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Creates automatic indexes for optimal query performance
+   * These composite indexes cover both filtering and sorting in single index
+   */
+  async createAutomaticIndexes() {
+    try {
+      const schemaPrefix = this.schemaName ? `${this.schemaName}_` : "";
+      const indexes = [
+        // Composite index for threads (filter + sort)
+        {
+          name: `${schemaPrefix}mastra_threads_resourceid_createdat_idx`,
+          table: storage.TABLE_THREADS,
+          columns: ["resourceId", "createdAt DESC"]
+        },
+        // Composite index for messages (filter + sort)
+        {
+          name: `${schemaPrefix}mastra_messages_thread_id_createdat_idx`,
+          table: storage.TABLE_MESSAGES,
+          columns: ["thread_id", "createdAt DESC"]
+        },
+        // Composite index for traces (filter + sort)
+        {
+          name: `${schemaPrefix}mastra_traces_name_starttime_idx`,
+          table: storage.TABLE_TRACES,
+          columns: ["name", "startTime DESC"]
+        },
+        // Composite index for evals (filter + sort)
+        {
+          name: `${schemaPrefix}mastra_evals_agent_name_created_at_idx`,
+          table: storage.TABLE_EVALS,
+          columns: ["agent_name", "created_at DESC"]
+        }
+      ];
+      for (const indexOptions of indexes) {
+        try {
+          await this.createIndex(indexOptions);
+        } catch (error) {
+          this.logger?.warn?.(`Failed to create index ${indexOptions.name}:`, error);
+        }
+      }
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_CREATE_PERFORMANCE_INDEXES_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Get detailed statistics for a specific index
+   */
+  async describeIndex(indexName) {
+    try {
+      const schemaName = this.schemaName || "public";
+      const query = `
+        SELECT 
+          i.indexname as name,
+          i.tablename as table,
+          i.indexdef as definition,
+          ix.indisunique as is_unique,
+          pg_size_pretty(pg_relation_size(c.oid)) as size,
+          array_agg(a.attname ORDER BY array_position(ix.indkey, a.attnum)) as columns,
+          am.amname as method,
+          s.idx_scan as scans,
+          s.idx_tup_read as tuples_read,
+          s.idx_tup_fetch as tuples_fetched
+        FROM pg_indexes i
+        JOIN pg_class c ON c.relname = i.indexname AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = i.schemaname)
+        JOIN pg_index ix ON ix.indexrelid = c.oid
+        JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = ANY(ix.indkey)
+        JOIN pg_am am ON c.relam = am.oid
+        LEFT JOIN pg_stat_user_indexes s ON s.indexrelname = i.indexname AND s.schemaname = i.schemaname
+        WHERE i.schemaname = $1 
+        AND i.indexname = $2
+        GROUP BY i.indexname, i.tablename, i.indexdef, ix.indisunique, c.oid, am.amname, s.idx_scan, s.idx_tup_read, s.idx_tup_fetch
+      `;
+      const result = await this.client.oneOrNone(query, [schemaName, indexName]);
+      if (!result) {
+        throw new Error(`Index "${indexName}" not found in schema "${schemaName}"`);
+      }
+      let columns = [];
+      if (typeof result.columns === "string" && result.columns.startsWith("{") && result.columns.endsWith("}")) {
+        const arrayContent = result.columns.slice(1, -1);
+        columns = arrayContent ? arrayContent.split(",") : [];
+      } else if (Array.isArray(result.columns)) {
+        columns = result.columns;
+      }
+      return {
+        name: result.name,
+        table: result.table,
+        columns,
+        unique: result.is_unique || false,
+        size: result.size || "0",
+        definition: result.definition || "",
+        method: result.method || "btree",
+        scans: parseInt(result.scans) || 0,
+        tuples_read: parseInt(result.tuples_read) || 0,
+        tuples_fetched: parseInt(result.tuples_fetched) || 0
+      };
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_INDEX_DESCRIBE_FAILED",
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName
+          }
+        },
+        error$1
+      );
+    }
+  }
 };
 function transformScoreRow(row) {
   return {
@@ -2808,16 +3105,17 @@ var WorkflowsPG = class extends storage.WorkflowsStorage {
   async persistWorkflowSnapshot({
     workflowName,
     runId,
+    resourceId,
     snapshot
   }) {
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
       await this.client.none(
-        `INSERT INTO ${getTableName({ indexName: storage.TABLE_WORKFLOW_SNAPSHOT, schemaName: this.schema })} (workflow_name, run_id, snapshot, "createdAt", "updatedAt")
-                 VALUES ($1, $2, $3, $4, $5)
+        `INSERT INTO ${getTableName({ indexName: storage.TABLE_WORKFLOW_SNAPSHOT, schemaName: this.schema })} (workflow_name, run_id, "resourceId", snapshot, "createdAt", "updatedAt")
+                 VALUES ($1, $2, $3, $4, $5, $6)
                  ON CONFLICT (workflow_name, run_id) DO UPDATE
-                 SET snapshot = $3, "updatedAt" = $5`,
-        [workflowName, runId, JSON.stringify(snapshot), now, now]
+                 SET "resourceId" = $3, snapshot = $4, "updatedAt" = $6`,
+        [workflowName, runId, resourceId, JSON.stringify(snapshot), now, now]
       );
     } catch (error$1) {
       throw new error.MastraError(
@@ -2979,37 +3277,68 @@ var PostgresStore = class extends storage.MastraStorage {
   isConnected = false;
   stores;
   constructor(config) {
+    const isConnectionStringConfig = (cfg) => {
+      return "connectionString" in cfg;
+    };
+    const isHostConfig = (cfg) => {
+      return "host" in cfg && "database" in cfg && "user" in cfg && "password" in cfg;
+    };
+    const isCloudSqlConfig = (cfg) => {
+      return "stream" in cfg || "password" in cfg && typeof cfg.password === "function";
+    };
     try {
-      if ("connectionString" in config) {
+      if (isConnectionStringConfig(config)) {
         if (!config.connectionString || typeof config.connectionString !== "string" || config.connectionString.trim() === "") {
           throw new Error(
             "PostgresStore: connectionString must be provided and cannot be empty. Passing an empty string may cause fallback to local Postgres defaults."
           );
         }
-      } else {
+      } else if (isCloudSqlConfig(config)) ; else if (isHostConfig(config)) {
         const required = ["host", "database", "user", "password"];
         for (const key of required) {
-          if (!(key in config) || typeof config[key] !== "string" || config[key].trim() === "") {
+          if (!config[key] || typeof config[key] !== "string" || config[key].trim() === "") {
             throw new Error(
               `PostgresStore: ${key} must be provided and cannot be empty. Passing an empty string may cause fallback to local Postgres defaults.`
             );
           }
         }
+      } else {
+        throw new Error(
+          "PostgresStore: invalid config. Provide either {connectionString}, {host,port,database,user,password}, or a pg ClientConfig (e.g., Cloud SQL connector with `stream`)."
+        );
       }
       super({ name: "PostgresStore" });
       this.schema = config.schemaName || "public";
-      this.#config = {
-        max: config.max,
-        idleTimeoutMillis: config.idleTimeoutMillis,
-        ...`connectionString` in config ? { connectionString: config.connectionString } : {
+      if (isConnectionStringConfig(config)) {
+        this.#config = {
+          connectionString: config.connectionString,
+          max: config.max,
+          idleTimeoutMillis: config.idleTimeoutMillis
+        };
+      } else if (isCloudSqlConfig(config)) {
+        this.#config = {
+          ...config,
+          max: config.max,
+          idleTimeoutMillis: config.idleTimeoutMillis
+        };
+      } else if (isHostConfig(config)) {
+        this.#config = {
           host: config.host,
           port: config.port,
           database: config.database,
           user: config.user,
           password: config.password,
-          ssl: config.ssl
-        }
-      };
+          ssl: config.ssl,
+          max: config.max,
+          idleTimeoutMillis: config.idleTimeoutMillis
+        };
+      } else {
+        this.#config = {
+          ...config,
+          max: config.max,
+          idleTimeoutMillis: config.idleTimeoutMillis
+        };
+      }
       this.stores = {};
     } catch (e) {
       throw new error.MastraError(
@@ -3045,6 +3374,11 @@ var PostgresStore = class extends storage.MastraStorage {
         memory
       };
       await super.init();
+      try {
+        await operations.createAutomaticIndexes();
+      } catch (indexError) {
+        console.warn("Failed to create indexes:", indexError);
+      }
     } catch (error$1) {
       this.isConnected = false;
       throw new error.MastraError(
@@ -3075,7 +3409,9 @@ var PostgresStore = class extends storage.MastraStorage {
       resourceWorkingMemory: true,
       hasColumn: true,
       createTable: true,
-      deleteMessages: true
+      deleteMessages: true,
+      aiTracing: false,
+      indexManagement: true
     };
   }
   /** @deprecated use getEvals instead */
@@ -3211,9 +3547,10 @@ var PostgresStore = class extends storage.MastraStorage {
   async persistWorkflowSnapshot({
     workflowName,
     runId,
+    resourceId,
     snapshot
   }) {
-    return this.stores.workflows.persistWorkflowSnapshot({ workflowName, runId, snapshot });
+    return this.stores.workflows.persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot });
   }
   async loadWorkflowSnapshot({
     workflowName,