@mastra/pg 1.23.0-alpha.6 → 1.23.0

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.23.0-alpha.6"
+  version: "1.23.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.23.0-alpha.6",
+  "version": "1.23.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -584,6 +584,8 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	indexMetadataCache = /* @__PURE__ */ new Map();
 	createdIndexes = /* @__PURE__ */ new Map();
 	namespaceReadyIndexes = /* @__PURE__ */ new Set();
+	/** In-flight lazy namespace migrations, keyed by index name (see {@link ensureNamespaceReady}). */
+	namespaceReadyCache = /* @__PURE__ */ new Map();
 	indexVectorTypes = /* @__PURE__ */ new Map();
 	mutexesByName = /* @__PURE__ */ new Map();
 	schema;
@@ -828,8 +830,10 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
          AND attnum > 0
          AND NOT attisdropped`, [tableName])).rowCount === 0) return;
 		await client.query(`ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS namespace VARCHAR(255) NOT NULL DEFAULT '${DEFAULT_NAMESPACE}'`);
-		const namespaceIndexName = this.getNamespaceIndexName(parsedIndexName);
-		await client.query(`CREATE UNIQUE INDEX IF NOT EXISTS "${namespaceIndexName}" ON ${tableName} (namespace, vector_id)`);
+		if (!(await this.getNamespaceSchemaState(tableName, client)).composite_index) {
+			const namespaceIndexName = this.getNamespaceIndexName(parsedIndexName);
+			await client.query(`CREATE UNIQUE INDEX IF NOT EXISTS "${namespaceIndexName}" ON ${tableName} (namespace, vector_id)`);
+		}
 		const legacyConstraints = await client.query(`SELECT c.conname
        FROM pg_constraint c
        WHERE c.conrelid = to_regclass($1)
@@ -840,21 +844,84 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			await client.query(`ALTER TABLE ${tableName} DROP CONSTRAINT "${parsedConstraintName}"`);
 		}
 	}
-	/**
-	* Name of the unique (namespace, vector_id) index for a table.
-	*
-	* The full `<index>_namespace_vector_id_idx` name is kept whenever it fits so tables that
-	* were already migrated keep matching `IF NOT EXISTS`. Longer index names would exceed
-	* Postgres' 63-char identifier limit, so those fall back to a truncated prefix plus a hash
-	* of the index name to distinguish tables that
-	* share a long prefix.
-	*/
 	getNamespaceIndexName(parsedIndexName) {
 		const fullName = `${parsedIndexName}_namespace_vector_id_idx`;
 		if (fullName.length <= 63) return fullName;
 		const suffix = `_ns_${(0, crypto$1.createHash)("sha256").update(parsedIndexName).digest("hex").slice(0, 32)}_idx`;
 		return `${parsedIndexName.slice(0, 63 - suffix.length)}${suffix}`;
 	}
+	async getNamespaceSchemaState(tableName, client) {
+		return (await client.query(`SELECT
+         EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = to_regclass($1)
+           AND attname = 'vector_id' AND attnum > 0 AND NOT attisdropped) AS vector_id,
+         EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = to_regclass($1)
+           AND attname = 'namespace' AND attnum > 0 AND NOT attisdropped) AS namespace,
+         EXISTS (
+           SELECT 1 FROM pg_index i
+           WHERE i.indrelid = to_regclass($1)
+             AND i.indisunique AND i.indisvalid AND i.indisready AND i.indimmediate
+             AND i.indpred IS NULL AND i.indexprs IS NULL AND i.indnkeyatts = 2
+             AND (SELECT array_agg(a.attname::text ORDER BY a.attname)
+                  FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, position)
+                  JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+                  WHERE k.position <= i.indnkeyatts) = ARRAY['namespace', 'vector_id']
+         ) AS composite_index,
+         EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass($1)
+           AND contype = 'u' AND pg_get_constraintdef(oid) = 'UNIQUE (vector_id)') AS legacy_constraint`, [tableName])).rows[0];
+	}
+	async reconcileNamespace(indexName, client) {
+		const { tableName } = this.getTableName(indexName);
+		await client.query("BEGIN");
+		try {
+			await client.query("SELECT pg_advisory_xact_lock((1936876916::bigint << 32) | to_regclass($1)::oid::bigint)", [tableName]);
+			const state = await this.getNamespaceSchemaState(tableName, client);
+			if (!state.vector_id) {
+				await client.query("ROLLBACK");
+				return false;
+			}
+			if (!state.namespace || !state.composite_index || state.legacy_constraint) {
+				if (this.disableInit || process.env.MASTRA_DISABLE_STORAGE_INIT === "true") throw new _mastra_core_error.MastraError({
+					id: (0, _mastra_core_storage.createVectorErrorId)("PG", "ENSURE_NAMESPACE", "MIGRATION_REQUIRED"),
+					domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
+					category: _mastra_core_error.ErrorCategory.USER,
+					text: `Vector index "${indexName}" requires namespace migration and schema changes are disabled. Call createIndex({ indexName: "${indexName}", dimension }) with init enabled, or apply the namespace migration SQL from the @mastra/pg changelog.`,
+					details: { indexName }
+				});
+				await this.ensureNamespaceSchema(indexName, client);
+				const migrated = await this.getNamespaceSchemaState(tableName, client);
+				if (!migrated.namespace || !migrated.composite_index || migrated.legacy_constraint) throw new _mastra_core_error.MastraError({
+					id: (0, _mastra_core_storage.createVectorErrorId)("PG", "ENSURE_NAMESPACE", "MIGRATION_REQUIRED"),
+					domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
+					category: _mastra_core_error.ErrorCategory.USER,
+					text: `Vector index "${indexName}" requires a valid unique (namespace, vector_id) index. Resolve conflicting index names and retry the namespace migration.`,
+					details: { indexName }
+				});
+			}
+			await client.query("COMMIT");
+			return true;
+		} catch (error) {
+			await client.query("ROLLBACK");
+			throw error;
+		}
+	}
+	/**
+	* Every data path filters on `namespace`, but tables created before that column existed are
+	* only migrated by `createIndex()`, which callers are not required to invoke before reading.
+	* Run the migration lazily instead, once per index per process.
+	*/
+	ensureNamespaceReady(indexName) {
+		if (this.namespaceReadyIndexes.has(indexName)) return Promise.resolve();
+		return this.memoize(this.namespaceReadyCache, indexName, () => this.getMutexByName(`create-${indexName}`).runExclusive(async () => {
+			if (this.namespaceReadyIndexes.has(indexName)) return;
+			const client = await this.pool.connect();
+			try {
+				if (await this.reconcileNamespace(indexName, client)) this.namespaceReadyIndexes.add(indexName);
+				else this.namespaceReadyCache.delete(indexName);
+			} finally {
+				client.release();
+			}
+		}));
+	}
 	transformFilter(filter) {
 		return new PGFilterTranslator().translate(filter);
 	}
@@ -912,8 +979,10 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			throw mastraError;
 		}
 		if (queryVector === void 0) {
-			const client = await this.pool.connect();
+			let client;
 			try {
+				await this.ensureNamespaceReady(indexName);
+				client = await this.pool.connect();
 				const { sql: filterQuery, values: filterValues } = buildDeleteFilterQuery(this.transformFilter(filter));
 				const { tableName } = this.getTableName(indexName);
 				const filterClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
@@ -939,6 +1008,10 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 					...includeVector && embedding && { vector: JSON.parse(embedding) }
 				}));
 			} catch (error) {
+				if (error instanceof _mastra_core_error.MastraError) {
+					this.logger?.trackException(error);
+					throw error;
+				}
 				const mastraError = new _mastra_core_error.MastraError({
 					id: (0, _mastra_core_storage.createVectorErrorId)("PG", "QUERY", "FAILED"),
 					domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
@@ -948,12 +1021,14 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				this.logger?.trackException(mastraError);
 				throw mastraError;
 			} finally {
-				client.release();
+				client?.release();
 			}
 		}
-		const indexInfo = await this.getIndexMetadata({ indexName });
-		const client = await this.pool.connect();
+		let client;
 		try {
+			await this.ensureNamespaceReady(indexName);
+			const indexInfo = await this.getIndexMetadata({ indexName });
+			client = await this.pool.connect();
 			await this.ensureSearchPath(client);
 			await client.query("BEGIN");
 			const { sql: filterQuery, values: filterValues } = buildFilterQuery(this.transformFilter(filter), minScore, topK);
@@ -1015,7 +1090,11 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				...includeVector && embedding && { vector: ops.parseEmbedding(embedding) }
 			}));
 		} catch (error) {
-			await client.query("ROLLBACK");
+			await client?.query("ROLLBACK");
+			if (error instanceof _mastra_core_error.MastraError) {
+				this.logger?.trackException(error);
+				throw error;
+			}
 			const mastraError = new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "QUERY", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
@@ -1025,15 +1104,17 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			this.logger?.trackException(mastraError);
 			throw mastraError;
 		} finally {
-			client.release();
+			client?.release();
 		}
 	}
 	async upsert({ indexName, vectors, metadata, ids, deleteFilter, namespace = DEFAULT_NAMESPACE }) {
 		(0, _mastra_core_vector.validateUpsertInput)("PG", vectors, metadata, ids);
 		const { tableName } = this.getTableName(indexName);
-		const indexInfo = await this.getIndexMetadata({ indexName });
-		const client = await this.pool.connect();
+		let client;
 		try {
+			const indexInfo = await this.getIndexMetadata({ indexName });
+			await this.ensureNamespaceReady(indexName);
+			client = await this.pool.connect();
 			await this.ensureSearchPath(client);
 			await client.query("BEGIN");
 			if (deleteFilter) {
@@ -1099,7 +1180,11 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			});
 			return vectorIds;
 		} catch (error) {
-			await client.query("ROLLBACK");
+			await client?.query("ROLLBACK");
+			if (error instanceof _mastra_core_error.MastraError) {
+				this.logger?.trackException(error);
+				throw error;
+			}
 			if (error instanceof Error && error.message?.includes("expected") && error.message?.includes("dimensions")) {
 				const match = error.message.match(/expected (\d+) dimensions, not (\d+)/);
 				if (match) {
@@ -1128,7 +1213,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			this.logger?.trackException(mastraError);
 			throw mastraError;
 		} finally {
-			client.release();
+			client?.release();
 		}
 	}
 	hasher = (0, xxhash_wasm.default)();
@@ -1256,9 +1341,8 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
             namespace VARCHAR(255) NOT NULL DEFAULT '${DEFAULT_NAMESPACE}'
           );
         `);
-				await this.ensureNamespaceSchema(indexName, client);
+				if (await this.reconcileNamespace(indexName, client)) this.namespaceReadyIndexes.add(indexName);
 				this.createdIndexes.set(indexName, indexCacheKey);
-				this.namespaceReadyIndexes.add(indexName);
 				this.indexVectorTypes.set(indexName, vectorType);
 				if (buildIndex) await this.setupIndex({
 					indexName,
@@ -1270,6 +1354,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			} catch (error) {
 				this.createdIndexes.delete(indexName);
 				this.namespaceReadyIndexes.delete(indexName);
+				this.namespaceReadyCache.delete(indexName);
 				this.indexVectorTypes.delete(indexName);
 				throw error;
 			} finally {
@@ -1644,27 +1729,30 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 		}
 	}
 	async deleteIndex({ indexName }) {
-		const client = await this.pool.connect();
-		try {
-			const { tableName } = this.getTableName(indexName);
-			await client.query(`DROP TABLE IF EXISTS ${tableName} CASCADE`);
-			this.createdIndexes.delete(indexName);
-			this.namespaceReadyIndexes.delete(indexName);
-			this.indexVectorTypes.delete(indexName);
-			this.invalidateIndexCaches(indexName);
-		} catch (error) {
-			await client.query("ROLLBACK");
-			const mastraError = new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_INDEX", "FAILED"),
-				domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
-				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
-				details: { indexName }
-			}, error);
-			this.logger?.trackException(mastraError);
-			throw mastraError;
-		} finally {
-			client.release();
-		}
+		await this.getMutexByName(`create-${indexName}`).runExclusive(async () => {
+			const client = await this.pool.connect();
+			try {
+				const { tableName } = this.getTableName(indexName);
+				await client.query(`DROP TABLE IF EXISTS ${tableName} CASCADE`);
+				this.createdIndexes.delete(indexName);
+				this.namespaceReadyIndexes.delete(indexName);
+				this.namespaceReadyCache.delete(indexName);
+				this.indexVectorTypes.delete(indexName);
+				this.invalidateIndexCaches(indexName);
+			} catch (error) {
+				await client.query("ROLLBACK");
+				const mastraError = new _mastra_core_error.MastraError({
+					id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_INDEX", "FAILED"),
+					domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
+					category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+					details: { indexName }
+				}, error);
+				this.logger?.trackException(mastraError);
+				throw mastraError;
+			} finally {
+				client.release();
+			}
+		});
 	}
 	async truncateIndex({ indexName }) {
 		const client = await this.pool.connect();
@@ -1720,6 +1808,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				details: { indexName }
 			});
 			const indexInfo = await this.getIndexMetadata({ indexName });
+			await this.ensureNamespaceReady(indexName);
 			client = await this.pool.connect();
 			await this.ensureSearchPath(client);
 			const { tableName } = this.getTableName(indexName);
@@ -1813,6 +1902,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	async deleteVector({ indexName, id, namespace = DEFAULT_NAMESPACE }) {
 		let client;
 		try {
+			await this.ensureNamespaceReady(indexName);
 			client = await this.pool.connect();
 			const { tableName } = this.getTableName(indexName);
 			const query = `
@@ -1821,6 +1911,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
       `;
 			await client.query(query, [id, namespace]);
 		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
 			const mastraError = new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_VECTOR", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
@@ -1847,6 +1938,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 		let client;
 		const effectiveNamespace = namespace ?? DEFAULT_NAMESPACE;
 		try {
+			await this.ensureNamespaceReady(indexName);
 			client = await this.pool.connect();
 			const { tableName } = this.getTableName(indexName);
 			if (!filter && !ids && namespace === void 0) throw new _mastra_core_error.MastraError({