@mastra/pg 1.19.0-alpha.0 → 1.19.0-alpha.2

package/dist/index.js

@@ -1,5 +1,5 @@
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowsStorage, WorkspacesStorage, calculatePagination, createStorageErrorId, createVectorErrorId, ensureDate, getDefaultValue, getSqlType, hasErrorCode, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, createStorageErrorId, createVectorErrorId, ensureDate, getDefaultValue, getSqlType, hasErrorCode, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { parseFieldKey, parseSqlIdentifier } from "@mastra/core/utils";
 import { MastraVector, validateTopK, validateUpsertInput } from "@mastra/core/vector";
 import { Mutex } from "async-mutex";
@@ -1947,9 +1947,25 @@ var PinnedClientAdapter = class {
 var RoutingDbClient = class {
 	#base;
 	#pinned = null;
+	#schemaSnapshot = null;
 	constructor(base) {
 		this.#base = base;
 	}
+	/**
+	* Catalog snapshot for the current init window, or `null` outside it.
+	*
+	* It lives here rather than on `PgDB` because every storage domain builds its
+	* own `PgDB` over this one shared client — hanging the snapshot off the
+	* client means one load serves all of them, and its lifetime lines up exactly
+	* with the pinned-init window that `pin()`/`unpin()` already delimit.
+	*/
+	get schemaSnapshot() {
+		return this.#schemaSnapshot;
+	}
+	/** Install (or clear, with `null`) the init-window catalog snapshot. */
+	setSchemaSnapshot(snapshot) {
+		this.#schemaSnapshot = snapshot;
+	}
 	/** Returns the currently active client (pinned if set, otherwise base). */
 	get active() {
 		return this.#pinned ?? this.#base;
@@ -2050,6 +2066,67 @@ function isDuplicateSchemaError(error) {
 	return /schema .* already exists/i.test(message);
 }
 //#endregion
+//#region src/storage/db/schema-snapshot.ts
+/**
+* Returns the snapshot currently installed on `client`, but only when it was
+* taken from the schema the caller operates on. A store configured for another
+* schema (or a client with no snapshot at all) gets `null` and falls back to
+* probing the live catalog.
+*/
+function getSchemaSnapshot(client, schemaName) {
+	const snapshot = client?.schemaSnapshot;
+	if (!snapshot) return null;
+	return snapshot.schemaName === (schemaName || "public") ? snapshot : null;
+}
+/**
+* Reads the catalog for `schemaName` in three queries. Must be called on the
+* pinned init client so the snapshot reflects what that connection will see.
+*/
+async function loadSchemaSnapshot(client, schemaName) {
+	const schema = schemaName || "public";
+	const [tableRows, columnRows, indexRows] = await Promise.all([
+		client.manyOrNone(`SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname = $1`, [schema]),
+		client.manyOrNone(`SELECT c.relname AS table_name, a.attname AS column_name
+         FROM pg_catalog.pg_class c
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+         JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
+        WHERE n.nspname = $1
+          AND c.relkind IN ('r', 'p')
+          AND a.attnum > 0
+          AND NOT a.attisdropped`, [schema]),
+		client.manyOrNone(`SELECT c.relname AS indexname, i.indisreplident AS is_replica_identity, i.indisprimary AS is_primary
+         FROM pg_catalog.pg_index i
+         JOIN pg_catalog.pg_class c ON c.oid = i.indexrelid
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1`, [schema])
+	]);
+	const columns = /* @__PURE__ */ new Map();
+	for (const row of columnRows) {
+		let set = columns.get(row.table_name);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			columns.set(row.table_name, set);
+		}
+		set.add(row.column_name);
+	}
+	const indexes = /* @__PURE__ */ new Set();
+	const replicaIdentityIndexes = /* @__PURE__ */ new Set();
+	const primaryKeyIndexes = /* @__PURE__ */ new Set();
+	for (const row of indexRows) {
+		indexes.add(row.indexname);
+		if (row.is_replica_identity) replicaIdentityIndexes.add(row.indexname);
+		if (row.is_primary) primaryKeyIndexes.add(row.indexname.toLowerCase());
+	}
+	return {
+		schemaName: schema,
+		tables: new Set(tableRows.map((r) => r.tablename)),
+		columns,
+		indexes,
+		replicaIdentityIndexes,
+		primaryKeyIndexes
+	};
+}
+//#endregion
 //#region src/storage/db/index.ts
 /**
 * Resolves PgDomainConfig to a database client and schema.
@@ -2229,7 +2306,8 @@ function generateTimestampTriggerSQL(tableName, schemaName) {
 		schemaName: quotedSchemaName
 	});
 	const functionName = `${quotedSchemaName}.trigger_set_timestamps`;
-	const triggerName = `"${parseSqlIdentifier(`${tableName}_timestamps`, "trigger name")}"`;
+	const parsedTriggerName = parseSqlIdentifier(`${tableName}_timestamps`, "trigger name");
+	const triggerName = `"${parsedTriggerName}"`;
 	return `CREATE OR REPLACE FUNCTION ${functionName}()
 RETURNS TRIGGER AS $$
 BEGIN
@@ -2248,12 +2326,38 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql;
 
-DROP TRIGGER IF EXISTS ${triggerName} ON ${fullTableName};
+DO $mastra_timestamps_trigger$
+BEGIN
+    -- Recreating the trigger unconditionally would take an ACCESS EXCLUSIVE
+    -- lock on the table (DROP TRIGGER does, even when nothing changes), and
+    -- init runs on every process start. Skip when the trigger is already
+    -- exactly what the CREATE below would produce.
+    --
+    -- tgtype 23 = ROW (1) | BEFORE (2) | INSERT (4) | UPDATE (16), so a trigger
+    -- whose timing or events differ still falls through and gets rebuilt. The
+    -- behaviour itself lives in the function, which is replaced above on every
+    -- init, so an upgraded function body lands without touching the trigger.
+    IF NOT EXISTS (
+        SELECT 1
+        FROM pg_catalog.pg_trigger tg
+        JOIN pg_catalog.pg_class c ON c.oid = tg.tgrelid
+        JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+        WHERE tg.tgname = ${`'${parsedTriggerName}'`}
+          AND c.relname = ${`'${parseSqlIdentifier(tableName, "table name")}'`}
+          AND n.nspname = ${schemaName ? `'${parseSqlIdentifier(schemaName, "schema name")}'` : `'public'`}
+          AND NOT tg.tgisinternal
+          AND tg.tgtype = 23
+          AND tg.tgfoid = '${functionName}()'::regprocedure
+    ) THEN
+        DROP TRIGGER IF EXISTS ${triggerName} ON ${fullTableName};
 
-CREATE TRIGGER ${triggerName}
-    BEFORE INSERT OR UPDATE ON ${fullTableName}
-    FOR EACH ROW
-    EXECUTE FUNCTION ${functionName}();`;
+        CREATE TRIGGER ${triggerName}
+            BEFORE INSERT OR UPDATE ON ${fullTableName}
+            FOR EACH ROW
+            EXECUTE FUNCTION ${functionName}();
+    END IF;
+END
+$mastra_timestamps_trigger$;`;
 }
 const schemaSetupRegistry = /* @__PURE__ */ new Map();
 /**
@@ -2280,6 +2384,99 @@ var PgDB = class extends MastraBase {
 		this.skipDefaultIndexes = config.skipDefaultIndexes;
 	}
 	/**
+	* Catalog snapshot for the current init window, or `null` outside it.
+	*
+	* When non-null, the init-path methods below answer existence questions from
+	* it instead of round-tripping to the server, and record the objects they
+	* create so later callers in the same init see them. See
+	* {@link SchemaSnapshot} for why it is scoped to init only.
+	*/
+	get schemaSnapshot() {
+		return getSchemaSnapshot(this.client, this.schemaName);
+	}
+	/**
+	* Whether the snapshot proves `generateTableSQL` would be a no-op for this
+	* table — i.e. the CREATE statement can be skipped.
+	*
+	* For most tables that is just "the table exists". `workflow_snapshot` is the
+	* exception: its generated SQL also carries a DO block that back-fills the
+	* `(workflow_name, run_id)` unique constraint and promotes it to the table's
+	* replica identity, so a table created by an older version still needs the
+	* statement to run.
+	*/
+	snapshotShowsTableConverged(snapshot, tableName) {
+		if (!snapshot.tables.has(tableName)) return false;
+		if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
+			const constraintName = buildConstraintName({
+				baseName: "mastra_workflow_snapshot_workflow_name_run_id_key",
+				schemaName: this.schemaName ? parseSqlIdentifier(this.schemaName, "schema name") : void 0
+			}).toLowerCase();
+			return snapshot.indexes.has(constraintName) && snapshot.replicaIdentityIndexes.has(constraintName);
+		}
+		return true;
+	}
+	/** Column set for `tableName` in the snapshot, created empty if absent. */
+	snapshotColumns(snapshot, tableName) {
+		let columns = snapshot.columns.get(tableName);
+		if (!columns) {
+			columns = /* @__PURE__ */ new Set();
+			snapshot.columns.set(tableName, columns);
+		}
+		return columns;
+	}
+	/**
+	* Records an out-of-band `ALTER TABLE … RENAME TO` in the init snapshot.
+	*
+	* Init-time migrations that issue raw DDL on `this.client` (instead of going
+	* through createTable/alterTable/createIndex, which maintain the snapshot
+	* themselves) MUST report it through these `note*` methods. A snapshot that
+	* still lists a renamed-away table makes a later createTable() in the same
+	* init skip the rebuild the migration depends on — stranding data. No-op
+	* outside the init window.
+	*
+	* Indexes riding along with a rename keep their names, so the snapshot's
+	* index set stays accurate without changes here.
+	*/
+	noteTableRenamed(oldName, newName) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) {
+			if (snapshot.tables.delete(oldName)) snapshot.tables.add(newName);
+			const columns = snapshot.columns.get(oldName);
+			if (columns) {
+				snapshot.columns.delete(oldName);
+				snapshot.columns.set(newName, columns);
+			}
+		}
+		this.tableColumnsCache.delete(oldName);
+		this.tableColumnsCache.delete(newName);
+	}
+	/**
+	* Records an out-of-band `DROP TABLE` in the init snapshot. See
+	* {@link noteTableRenamed} for why raw-DDL migrations must call this.
+	*
+	* The dropped table's indexes vanish with it, but the snapshot's flat index
+	* set cannot map names back to tables. Stale entries only make a later
+	* createIndex() skip a recreate until the next init re-reads the catalog —
+	* the same self-healing bound the rest of the snapshot design accepts.
+	*/
+	noteTableDropped(tableName) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) {
+			snapshot.tables.delete(tableName);
+			snapshot.columns.delete(tableName);
+		}
+		this.tableColumnsCache.delete(tableName);
+	}
+	/**
+	* Records an out-of-band `ALTER TABLE … ADD COLUMN` in the init snapshot.
+	* See {@link noteTableRenamed} for why raw-DDL migrations must call this.
+	*/
+	noteColumnAdded(tableName, column) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) this.snapshotColumns(snapshot, tableName).add(column);
+		this.tableColumnsCache.delete(tableName);
+	}
+	/**
 	* Gets the set of column names that actually exist in the database table.
 	* Results are cached; the cache is invalidated when alterTable() adds new columns.
 	*/
@@ -2306,6 +2503,12 @@ var PgDB = class extends MastraBase {
 	}
 	async hasColumn(table, column) {
 		const schema = this.schemaName || "public";
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) {
+			const columns = snapshot.columns.get(table);
+			if (!columns) return false;
+			return columns.has(column) || columns.has(column.toLowerCase());
+		}
 		return !!await this.client.oneOrNone(`SELECT 1 FROM information_schema.columns WHERE table_schema = $1 AND table_name = $2 AND (column_name = $3 OR column_name = $4)`, [
 			schema,
 			table,
@@ -2344,6 +2547,14 @@ var PgDB = class extends MastraBase {
 		if (!this.schemaName) return;
 		let registryEntry = schemaSetupRegistry.get(this.schemaName);
 		if (registryEntry?.complete) return;
+		const snapshot = this.schemaSnapshot;
+		if (snapshot && snapshot.tables.size > 0) {
+			schemaSetupRegistry.set(this.schemaName, {
+				promise: null,
+				complete: true
+			});
+			return;
+		}
 		const quotedSchemaName = getSchemaName$6(this.schemaName);
 		if (!registryEntry?.promise) {
 			const schemaNameCapture = this.schemaName;
@@ -2448,16 +2659,28 @@ var PgDB = class extends MastraBase {
 		try {
 			const timeZColumnNames = Object.entries(schema).filter(([_, def]) => def.type === "timestamp").map(([name]) => name);
 			if (this.schemaName) await this.setupSchema();
-			const sql = generateTableSQL({
-				tableName,
-				schema,
-				schemaName: this.schemaName,
-				compositePrimaryKey
-			});
-			try {
-				await this.client.none(sql);
-			} catch (error) {
-				if (!isDuplicateRelationError(error)) throw error;
+			const snapshot = this.schemaSnapshot;
+			if (!snapshot || !this.snapshotShowsTableConverged(snapshot, tableName)) {
+				const sql = generateTableSQL({
+					tableName,
+					schema,
+					schemaName: this.schemaName,
+					compositePrimaryKey
+				});
+				try {
+					await this.client.none(sql);
+				} catch (error) {
+					if (!isDuplicateRelationError(error)) throw error;
+				}
+				if (snapshot) {
+					snapshot.tables.add(tableName);
+					const created = this.snapshotColumns(snapshot, tableName);
+					for (const [name, def] of Object.entries(schema)) {
+						const parsedName = parseSqlIdentifier(name, "column name");
+						created.add(parsedName);
+						if (def.type === "timestamp") created.add(`${parsedName}Z`);
+					}
+				}
 			}
 			await this.alterTable({
 				tableName,
@@ -2523,10 +2746,12 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 				const sqlType = mapToSqlType(columnDef.type);
 				const alterSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}" ${sqlType} ${columnDef.nullable ? "" : "NOT NULL"} ${!columnDef.nullable ? this.getDefaultValue(columnDef.type) : ""}`.trim();
 				await this.client.none(alterSql);
+				this.noteColumnAdded(TABLE_SPANS, columnName);
 				this.logger?.debug?.(`Added column '${columnName}' to ${fullTableName}`);
 				if (sqlType === "TIMESTAMP") {
 					const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}Z" TIMESTAMPTZ DEFAULT NOW()`.trim();
 					await this.client.none(timestampZSql);
+					this.noteColumnAdded(TABLE_SPANS, `${columnName}Z`);
 					this.logger?.debug?.(`Added timezone column '${columnName}Z' to ${fullTableName}`);
 				}
 			}
@@ -2535,6 +2760,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 				if (!await this.hasColumn(TABLE_SPANS, tzColumnName)) {
 					const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parseSqlIdentifier(tzColumnName, "column name")}" TIMESTAMPTZ DEFAULT NOW()`.trim();
 					await this.client.none(timestampZSql);
+					this.noteColumnAdded(TABLE_SPANS, tzColumnName);
 					this.logger?.debug?.(`Added timezone column '${tzColumnName}' to ${fullTableName}`);
 				}
 			}
@@ -2657,6 +2883,12 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			schemaName: (this.schemaName ? parseSqlIdentifier(this.schemaName, "schema name") : "") || void 0
 		});
 		const schemaFilter = this.schemaName || "public";
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) return snapshot.primaryKeyIndexes.has(constraintName.toLowerCase());
+		return this.spansPrimaryKeyExistsLive(constraintName, schemaFilter);
+	}
+	/** Live-catalog variant of {@link spansPrimaryKeyExists}, bypassing the snapshot. */
+	async spansPrimaryKeyExistsLive(constraintName, schemaFilter) {
 		return (await this.client.oneOrNone(`SELECT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = lower($1) AND connamespace = (SELECT oid FROM pg_namespace WHERE nspname = $2)) as exists`, [constraintName, schemaFilter]))?.exists ?? false;
 	}
 	/**
@@ -2687,10 +2919,12 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
         ADD CONSTRAINT ${constraintName}
         PRIMARY KEY ("traceId", "spanId")
       `);
+			this.schemaSnapshot?.primaryKeyIndexes.add(constraintName.toLowerCase());
 			this.logger?.info?.(`Added PRIMARY KEY constraint ${constraintName} to ${fullTableName}`);
 		} catch (error) {
 			if (isDuplicateRelationError(error)) {
-				if (await this.spansPrimaryKeyExists()) {
+				if (await this.spansPrimaryKeyExistsLive(constraintName, schemaFilter)) {
+					this.schemaSnapshot?.primaryKeyIndexes.add(constraintName.toLowerCase());
 					this.logger?.debug?.(`PRIMARY KEY constraint ${constraintName} was created by another process`);
 					return;
 				}
@@ -2772,16 +3006,25 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			indexName: tableName,
 			schemaName: getSchemaName$6(this.schemaName)
 		});
+		const snapshot = this.schemaSnapshot;
+		const knownColumns = snapshot ? this.snapshotColumns(snapshot, tableName) : null;
 		try {
 			for (const columnName of ifNotExists) if (schema[columnName]) {
 				const columnDef = schema[columnName];
 				const parsedColumnName = parseSqlIdentifier(columnName, "column name");
 				const sqlType = mapToSqlType(columnDef.type);
 				const alterSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}" ${sqlType} ${columnDef.nullable ? "" : "NOT NULL"} ${!columnDef.nullable ? this.getDefaultValue(columnDef.type) : ""}`.trim();
-				await this.client.none(alterSql);
+				if (!knownColumns?.has(parsedColumnName)) {
+					await this.client.none(alterSql);
+					knownColumns?.add(parsedColumnName);
+				}
 				if (sqlType === "TIMESTAMP") {
-					const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}Z" TIMESTAMPTZ DEFAULT NOW()`.trim();
-					await this.client.none(timestampZSql);
+					const tzColumnName = `${parsedColumnName}Z`;
+					if (!knownColumns?.has(tzColumnName)) {
+						const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${tzColumnName}" TIMESTAMPTZ DEFAULT NOW()`.trim();
+						await this.client.none(timestampZSql);
+						knownColumns?.add(tzColumnName);
+					}
 				}
 				this.logger?.debug?.(`Ensured column ${parsedColumnName} exists in table ${fullTableName}`);
 			}
@@ -2867,7 +3110,10 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 				indexName: table,
 				schemaName: getSchemaName$6(this.schemaName)
 			});
-			if (await this.client.oneOrNone(`SELECT 1 FROM pg_indexes
+			const snapshot = this.schemaSnapshot;
+			if (snapshot) {
+				if (snapshot.indexes.has(name)) return;
+			} else if (await this.client.oneOrNone(`SELECT 1 FROM pg_indexes
          WHERE indexname = $1
          AND schemaname = $2`, [name, schemaName])) return;
 			const uniqueStr = unique ? "UNIQUE " : "";
@@ -2889,6 +3135,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			if (storage && Object.keys(storage).length > 0) withStr = ` WITH (${Object.entries(storage).map(([key, value]) => `${key} = ${value}`).join(", ")})`;
 			const sql = `CREATE ${uniqueStr}INDEX ${concurrentStr}${`"${parseSqlIdentifier(name, "index name")}"`} ON ${fullTableName} ${methodStr}(${columnsStr})${withStr}${tablespaceStr}${whereStr}`;
 			await this.client.none(sql);
+			snapshot?.indexes.add(name);
 		} catch (error) {
 			if (error instanceof Error && error.message.includes("CONCURRENTLY")) {
 				const retryOptions = {
@@ -2908,15 +3155,34 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			}, error);
 		}
 	}
+	/**
+	* Runs a caller-built `CREATE INDEX IF NOT EXISTS` statement, unless the init
+	* snapshot already proves `indexName` exists.
+	*
+	* `createIndex` covers the indexes described by {@link CreateIndexOptions};
+	* this is for the two init paths that hand-write their statement (a partial
+	* or otherwise non-standard index) and would otherwise send a no-op DDL on
+	* every warm init.
+	*/
+	async createIndexFromStatement(indexName, sql) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot?.indexes.has(indexName)) return;
+		await this.client.none(sql);
+		snapshot?.indexes.add(indexName);
+	}
 	async dropIndex(indexName) {
 		try {
 			const schemaName = this.schemaName || "public";
-			if (!await this.client.oneOrNone(`SELECT 1 FROM pg_indexes
+			const snapshot = this.schemaSnapshot;
+			if (snapshot) {
+				if (!snapshot.indexes.has(indexName)) return;
+			} else if (!await this.client.oneOrNone(`SELECT 1 FROM pg_indexes
          WHERE indexname = $1
          AND schemaname = $2`, [indexName, schemaName])) return;
 			const quotedIndexName = `"${parseSqlIdentifier(indexName, "index name")}"`;
 			const sql = `DROP INDEX IF EXISTS ${getSchemaName$6(this.schemaName)}.${quotedIndexName}`;
 			await this.client.none(sql);
+			snapshot?.indexes.delete(indexName);
 		} catch (error) {
 			throw new MastraError({
 				id: createStorageErrorId("PG", "INDEX_DROP", "FAILED"),
@@ -3413,7 +3679,9 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 		});
 		if (await this.#db.hasColumn(TABLE_AGENTS, "name")) {
 			await this.#db.client.none(`ALTER TABLE ${fullTableName} RENAME TO "${TABLE_AGENTS}_legacy"`);
+			this.#db.noteTableRenamed(TABLE_AGENTS, `${TABLE_AGENTS}_legacy`);
 			await this.#db.client.none(`DROP TABLE IF EXISTS ${fullVersionsTableName}`);
+			this.#db.noteTableDropped(TABLE_AGENT_VERSIONS);
 		}
 		if (!await this.#db.hasColumn(`${TABLE_AGENTS}_legacy`, "name")) return;
 		const oldAgents = await this.#db.client.manyOrNone(`SELECT * FROM ${legacyTableName}`);
@@ -3470,6 +3738,7 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 			]);
 		}
 		await this.#db.client.none(`DROP TABLE IF EXISTS ${legacyTableName}`);
+		this.#db.noteTableDropped(`${TABLE_AGENTS}_legacy`);
 	}
 	/**
 	* Migrates the agent_versions table from the old snapshot-based schema (single `snapshot` JSON column)
@@ -3487,7 +3756,9 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 			schemaName: getSchemaName$5(this.#schema)
 		});
 		await this.#db.client.none(`DROP TABLE IF EXISTS ${fullVersionsTableName}`);
+		this.#db.noteTableDropped(TABLE_AGENT_VERSIONS);
 		await this.#db.client.none(`DROP TABLE IF EXISTS ${legacyTableName}`);
+		this.#db.noteTableDropped(`${TABLE_AGENTS}_legacy`);
 	}
 	/**
 	* Migrates the tools field from string[] format to JSONB format { "tool-key": { "description": "..." } }.
@@ -5015,6 +5286,7 @@ var DatasetsPG = class DatasetsPG extends DatasetsStorage {
 				schemaName: getSchemaName$5(this.#schema)
 			});
 			await this.#db.client.none(`ALTER TABLE ${fullTableName} ADD COLUMN "${column}" ${sqlType}`);
+			this.#db.noteColumnAdded(table, column);
 		}
 	}
 	getDefaultIndexDefinitions() {
@@ -6884,7 +7156,7 @@ var FavoritesPG = class FavoritesPG extends FavoritesStorage {
 			indexName: TABLE_FAVORITES,
 			schemaName: getSchemaName$5(this.#schema)
 		});
-		await this.#db.client.none(`CREATE INDEX IF NOT EXISTS idx_favorites_entity ON ${fullTableName} ("entityType", "entityId")`);
+		await this.#db.createIndexFromStatement("idx_favorites_entity", `CREATE INDEX IF NOT EXISTS idx_favorites_entity ON ${fullTableName} ("entityType", "entityId")`);
 	}
 	async dangerouslyClearAll() {
 		const fullTableName = getTableName$5({
@@ -8380,7 +8652,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				indexName: OM_TABLE,
 				schemaName: getSchemaName$3(this.#schema)
 			});
-			await this.#db.client.none(`CREATE INDEX IF NOT EXISTS idx_om_lookup_key ON ${omTableName} ("lookupKey")`);
+			await this.#db.createIndexFromStatement("idx_om_lookup_key", `CREATE INDEX IF NOT EXISTS idx_om_lookup_key ON ${omTableName} ("lookupKey")`);
 		}
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
@@ -18476,6 +18748,187 @@ var ToolProviderConnectionsPG = class ToolProviderConnectionsPG extends ToolProv
 	}
 };
 //#endregion
+//#region src/storage/domains/workflow-definitions/index.ts
+function rowToDefinition(row) {
+	const inputSchema = parseJsonResilient(row.inputSchema);
+	const outputSchema = parseJsonResilient(row.outputSchema);
+	const graph = parseJsonResilient(row.graph);
+	if (inputSchema === void 0 || outputSchema === void 0 || graph === void 0) throw new Error(`Workflow definition row "${String(row.id)}" is missing required JSON columns.`);
+	const def = {
+		id: String(row.id),
+		inputSchema,
+		outputSchema,
+		graph,
+		status: String(row.status),
+		source: String(row.source),
+		createdAt: new Date(row.createdAtZ ?? row.createdAt),
+		updatedAt: new Date(row.updatedAtZ ?? row.updatedAt)
+	};
+	if (row.description != null) def.description = String(row.description);
+	const metadata = parseJsonResilient(row.metadata);
+	if (metadata !== void 0 && metadata !== null) def.metadata = metadata;
+	const stateSchema = parseJsonResilient(row.stateSchema);
+	if (stateSchema !== void 0 && stateSchema !== null) def.stateSchema = stateSchema;
+	const requestContextSchema = parseJsonResilient(row.requestContextSchema);
+	if (requestContextSchema !== void 0 && requestContextSchema !== null) def.requestContextSchema = requestContextSchema;
+	if (row.authorId != null) def.authorId = String(row.authorId);
+	return def;
+}
+var WorkflowDefinitionsPG = class WorkflowDefinitionsPG extends WorkflowDefinitionsStorage {
+	#db;
+	#schema;
+	#skipDefaultIndexes;
+	#indexes;
+	static MANAGED_TABLES = [TABLE_WORKFLOW_DEFINITIONS];
+	constructor(config) {
+		super();
+		const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
+		this.#db = new PgDB({
+			client,
+			schemaName,
+			skipDefaultIndexes
+		});
+		this.#schema = schemaName || "public";
+		this.#skipDefaultIndexes = skipDefaultIndexes;
+		this.#indexes = indexes?.filter((idx) => WorkflowDefinitionsPG.MANAGED_TABLES.includes(idx.table));
+	}
+	static getExportDDL(schemaName) {
+		return [generateTableSQL({
+			tableName: TABLE_WORKFLOW_DEFINITIONS,
+			schema: TABLE_SCHEMAS[TABLE_WORKFLOW_DEFINITIONS],
+			schemaName,
+			includeAllConstraints: true
+		})];
+	}
+	getDefaultIndexDefinitions() {
+		return [{
+			name: `${this.#schema !== "public" ? `${this.#schema}_` : ""}idx_workflow_definitions_status`,
+			table: TABLE_WORKFLOW_DEFINITIONS,
+			columns: ["status"]
+		}];
+	}
+	async createDefaultIndexes() {
+		if (this.#skipDefaultIndexes) return;
+		for (const indexDef of this.getDefaultIndexDefinitions()) try {
+			await this.#db.createIndex(indexDef);
+		} catch (error) {
+			this.logger?.warn?.(`Failed to create index ${indexDef.name}:`, error);
+		}
+	}
+	async createCustomIndexes() {
+		if (!this.#indexes || this.#indexes.length === 0) return;
+		for (const indexDef of this.#indexes) try {
+			await this.#db.createIndex(indexDef);
+		} catch (error) {
+			this.logger?.warn?.(`Failed to create custom index ${indexDef.name}:`, error);
+		}
+	}
+	async init() {
+		await this.#db.createTable({
+			tableName: TABLE_WORKFLOW_DEFINITIONS,
+			schema: TABLE_SCHEMAS[TABLE_WORKFLOW_DEFINITIONS]
+		});
+		await this.createDefaultIndexes();
+		await this.createCustomIndexes();
+	}
+	async dangerouslyClearAll() {
+		await this.#db.clearTable({ tableName: TABLE_WORKFLOW_DEFINITIONS });
+	}
+	async upsert(input) {
+		const now = /* @__PURE__ */ new Date();
+		if (!await this.get(input.id)) {
+			if (!("inputSchema" in input) || !input.inputSchema) throw new Error(`Cannot create workflow definition "${input.id}": inputSchema is required.`);
+			if (!("outputSchema" in input) || !input.outputSchema) throw new Error(`Cannot create workflow definition "${input.id}": outputSchema is required.`);
+			if (!("graph" in input) || !input.graph) throw new Error(`Cannot create workflow definition "${input.id}": graph is required.`);
+			const record = {
+				id: input.id,
+				description: input.description ?? null,
+				metadata: input.metadata ?? null,
+				inputSchema: input.inputSchema,
+				outputSchema: input.outputSchema,
+				stateSchema: input.stateSchema ?? null,
+				requestContextSchema: input.requestContextSchema ?? null,
+				graph: input.graph,
+				status: "active",
+				source: "storage",
+				authorId: "authorId" in input ? input.authorId ?? null : null,
+				createdAt: now,
+				updatedAt: now
+			};
+			try {
+				await this.#db.insert({
+					tableName: TABLE_WORKFLOW_DEFINITIONS,
+					record
+				});
+			} catch (error) {
+				if (!await this.get(input.id)) throw error;
+				return this.applyUpdate(input, now);
+			}
+			const created = await this.get(input.id);
+			if (!created) throw new Error(`Failed to persist workflow definition "${input.id}".`);
+			return created;
+		}
+		return this.applyUpdate(input, now);
+	}
+	async applyUpdate(input, now) {
+		const data = { updatedAt: now };
+		if ("description" in input && input.description !== void 0) data.description = input.description;
+		if ("metadata" in input && input.metadata !== void 0) data.metadata = input.metadata;
+		if ("inputSchema" in input && input.inputSchema !== void 0) data.inputSchema = input.inputSchema;
+		if ("outputSchema" in input && input.outputSchema !== void 0) data.outputSchema = input.outputSchema;
+		if ("stateSchema" in input && input.stateSchema !== void 0) data.stateSchema = input.stateSchema;
+		if ("requestContextSchema" in input && input.requestContextSchema !== void 0) data.requestContextSchema = input.requestContextSchema;
+		if ("graph" in input && input.graph !== void 0) data.graph = input.graph;
+		if ("status" in input && input.status !== void 0) data.status = input.status;
+		if ("authorId" in input && input.authorId !== void 0) data.authorId = input.authorId;
+		await this.#db.update({
+			tableName: TABLE_WORKFLOW_DEFINITIONS,
+			keys: { id: input.id },
+			data
+		});
+		const updated = await this.get(input.id);
+		if (!updated) throw new Error(`Failed to update workflow definition "${input.id}".`);
+		return updated;
+	}
+	async get(id) {
+		const tableName = getTableName$5({
+			indexName: TABLE_WORKFLOW_DEFINITIONS,
+			schemaName: getSchemaName$5(this.#schema)
+		});
+		const row = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1`, [id]);
+		return row ? rowToDefinition(row) : null;
+	}
+	async list(args) {
+		const tableName = getTableName$5({
+			indexName: TABLE_WORKFLOW_DEFINITIONS,
+			schemaName: getSchemaName$5(this.#schema)
+		});
+		const conditions = [];
+		const params = [];
+		if (args?.status) {
+			params.push(args.status);
+			conditions.push(`"status" = $${params.length}`);
+		}
+		if (args?.authorId !== void 0) {
+			params.push(args.authorId);
+			conditions.push(`"authorId" = $${params.length}`);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		const definitions = (await this.#db.client.manyOrNone(`SELECT * FROM ${tableName} ${where} ORDER BY "updatedAt" DESC`, params)).map((row) => rowToDefinition(row));
+		return {
+			definitions,
+			total: definitions.length
+		};
+	}
+	async delete(id) {
+		const tableName = getTableName$5({
+			indexName: TABLE_WORKFLOW_DEFINITIONS,
+			schemaName: getSchemaName$5(this.#schema)
+		});
+		await this.#db.client.none(`DELETE FROM ${tableName} WHERE "id" = $1`, [id]);
+	}
+};
+//#endregion
 //#region src/storage/domains/workflows/index.ts
 function getSchemaName(schema) {
 	return schema ? `"${schema}"` : "\"public\"";
@@ -19968,6 +20421,7 @@ const ALL_DOMAINS = [
 	BlobsPG,
 	ToolProviderConnectionsPG,
 	WorkflowsPG,
+	WorkflowDefinitionsPG,
 	DatasetsPG,
 	ExperimentsPG,
 	BackgroundTasksPG,
@@ -20049,6 +20503,7 @@ var PostgresStore = class extends MastraCompositeStore {
 			this.stores = {
 				scores: new ScoresPG(domainConfig),
 				workflows: new WorkflowsPG(domainConfig),
+				workflowDefinitions: new WorkflowDefinitionsPG(domainConfig),
 				memory: new MemoryPG(domainConfig),
 				notifications: new NotificationsPG(domainConfig),
 				observability: new ObservabilityPG(domainConfig),
@@ -20101,6 +20556,7 @@ var PostgresStore = class extends MastraCompositeStore {
 			pinnedClient = await this.#pool.connect();
 			const pinned = new PinnedClientAdapter(this.#pool, pinnedClient);
 			this.#db.pin(pinned);
+			this.#db.setSchemaSnapshot(await loadSchemaSnapshot(pinned, this.schema));
 			await super.init();
 			this.isInitialized = true;
 		} catch (error) {
@@ -20112,6 +20568,7 @@ var PostgresStore = class extends MastraCompositeStore {
 				category: ErrorCategory.THIRD_PARTY
 			}, error);
 		} finally {
+			this.#db.setSchemaSnapshot(null);
 			if (pinnedClient) {
 				this.#db.unpin();
 				pinnedClient.release();
@@ -20371,6 +20828,6 @@ Example Complex Query:
   ]
 }`;
 //#endregion
-export { AgentsPG, BackgroundTasksPG, BlobsPG, ChannelsPG, DatasetsPG, ExperimentsPG, FavoritesPG, MCPClientsPG, MCPServersPG, MemoryPG, NotificationsPG, ObservabilityPG, ObservabilityStoragePostgresVNext, PGVECTOR_PROMPT, PgFactoryStorage, PgVector, PoolAdapter, PostgresStore, PostgresStoreVNext, PromptBlocksPG, SchedulesPG, ScorerDefinitionsPG, ScoresPG, SkillsPG, ToolProviderConnectionsPG, WorkflowsPG, WorkspacesPG, exportSchemas };
+export { AgentsPG, BackgroundTasksPG, BlobsPG, ChannelsPG, DatasetsPG, ExperimentsPG, FavoritesPG, MCPClientsPG, MCPServersPG, MemoryPG, NotificationsPG, ObservabilityPG, ObservabilityStoragePostgresVNext, PGVECTOR_PROMPT, PgFactoryStorage, PgVector, PoolAdapter, PostgresStore, PostgresStoreVNext, PromptBlocksPG, SchedulesPG, ScorerDefinitionsPG, ScoresPG, SkillsPG, ToolProviderConnectionsPG, WorkflowDefinitionsPG, WorkflowsPG, WorkspacesPG, exportSchemas };
 
 //# sourceMappingURL=index.js.map