@mastra/pg 1.25.1-alpha.0 → 1.26.0-alpha.2

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.25.1-alpha.0"
+  version: "1.26.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/reference-storage-retention.md

@@ -6,11 +6,37 @@
 
 Because storage grows without bound by default, Mastra provides an opt-in, age-based retention system. Declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Unconfigured data is kept forever, so behavior doesn't change until you opt in.
 
-`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+`prune()` deletes rows in bounded batches. Runs are resumable and cancellable, so you can limit how much work each maintenance window performs. Pruning doesn't reclaim disk space by itself. Use the database-specific maintenance guidance below when you need to return freed space to the operating system.
 
 Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
-The reference implementations are [libSQL](https://mastra.ai/integrations/databases/libsql), [PostgreSQL](https://mastra.ai/integrations/databases/postgresql), and [MongoDB](https://mastra.ai/integrations/databases/mongodb). Other adapters keep rows forever until they implement retention.
+Storage adapters use the shared core retention contract for `prune()`, or a database-native mechanism when that better matches the backend.
+
+| Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
+| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
+| PostgreSQL           | `prune()`               | All supported growth domains. V-next observability drops expired partitions or chunks                                                                                                  |
+| MongoDB              | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
+| DuckDB               | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
+| MySQL                | `prune()`               | Observability spans                                                                                                                                                                    |
+| Microsoft SQL Server | `prune()`               | Observability spans                                                                                                                                                                    |
+| Oracle Database      | `prune()`               | Observability spans and logs                                                                                                                                                           |
+| Amazon Aurora DSQL   | `prune()`               | Observability spans                                                                                                                                                                    |
+| Google Cloud Spanner | `prune()`               | Observability spans, plus metrics when metrics storage is enabled                                                                                                                      |
+| ClickHouse           | Native TTL              | Observability spans, metrics, logs, scores, and feedback. When all five signals have finite retention, deletion-request records expire after the longest signal retention plus 30 days |
+
+## Storage-specific maintenance
+
+| Adapter           | Maintenance guidance                                                                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite and libSQL | Freed pages are reused by future writes, which stops the database file from growing. Reclaiming disk space requires database-level maintenance. |
+| DuckDB            | For file-backed stores, run `CHECKPOINT` after pruning to reclaim deleted rows in storage. DuckDB's `VACUUM` doesn't reclaim deleted rows.      |
+
+## Schedule pruning
+
+Run `prune()` from a scheduler or maintenance worker, not from application startup or shutdown hooks. For deployments that share a database, prefer a single active scheduler or worker for pruning.
+
+Prefer lower-traffic periods when pruning large tables. Use `maxBatches`, `maxRows`, and `pauseMs` to bound each run, and pass an `AbortSignal` when the maintenance process needs to stop promptly. These recommendations apply to adapters that expose `prune()`. ClickHouse applies its native time to live (TTL) policy within the database.
 
 ## Usage example
 
@@ -94,7 +120,8 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
-> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`.
+> - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.
+> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`. DuckDB, MySQL, Microsoft SQL Server, Oracle Database, Amazon Aurora DSQL, and Google Cloud Spanner currently support retention only in their `observability` domains, with the signal coverage shown in the support matrix.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
@@ -109,7 +136,7 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 Pass `options.retention` to replace the configured policies for that call only: for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
 
-Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index.
+Adapters that use anchor-column indexes create them lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index. DuckDB uses its built-in zone maps instead of creating retention indexes.
 
 ```typescript
 const results = await storage.prune({
@@ -177,6 +204,31 @@ async function retentionTick() {
 
 You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
+## ClickHouse native TTL
+
+ClickHouse observability storage uses native table TTLs instead of `prune()`. Configure retention as days per signal. `init()` applies the TTLs to new and existing tables and skips `ALTER TABLE` statements when the configured TTL is already present.
+
+For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the v-next observability store:
+
+```typescript
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const observability = new ObservabilityStorageClickhouseVNext({
+  client,
+  retention: {
+    tracing: 30,
+    logs: 7,
+    metrics: 14,
+    scores: 90,
+    feedback: 60,
+  },
+})
+
+await observability.applyRetention()
+```
+
+Deletion requests are retained long enough to keep enforcing erasure after signal rows expire. Mastra applies a TTL to `mastra_deletion_requests` only when tracing, logs, metrics, scores, and feedback all have finite retention. The deletion-request TTL is the longest of those periods plus 30 days. For example, if score retention is the longest period at 90 days, deletion requests expire after 120 days. When any signal is unbounded, deletion requests remain unbounded because trace deletion requests cover rows across all five signals.
+
 ## MongoDB TTL indexes (alternative to prune)
 
 MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) that automatically delete expired documents without requiring manual `prune()` calls. This is a database-level feature that runs as a background thread.

package/dist/index.cjs

@@ -4927,137 +4927,31 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 };
 //#endregion
 //#region src/storage/retention.ts
-const DEFAULT_BATCH_SIZE = 1e3;
-async function sleep(ms, signal) {
-	if (ms <= 0 || signal?.aborted) return;
-	await new Promise((resolve) => {
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			resolve();
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Convert a policy's `maxAge` into a cutoff bound matching the anchor's storage
-* type: a `Date` for `timestamptz` columns (pg compares timezone-aware), or a
-* raw millisecond number for `bigint` epoch-ms columns.
-*/
 function cutoffFor(policy, anchorType, now = Date.now()) {
-	const cutoffMs = now - (0, _mastra_core_storage.parseDuration)(policy.maxAge);
+	const cutoffMs = (0, _mastra_core_storage.retentionCutoffMs)(policy, now);
 	return anchorType === "epoch-ms" ? cutoffMs : new Date(cutoffMs);
 }
-/**
-* Run the bounded/cancellable batched-delete loop for a single logical target,
-* delegating the actual delete of up to `limit` rows to `deleteBatch`. Returns
-* `{ deleted, done }`; `done: false` means the loop stopped on a bound or the
-* abort signal and eligible rows may remain.
-*/
-async function runBatchedDelete({ deleteBatch, batchSize, options }) {
-	if (!Number.isSafeInteger(batchSize) || batchSize <= 0) throw new Error(`retention batchSize must be a positive integer; received ${batchSize}`);
-	let deleted = 0;
-	let batches = 0;
-	while (true) {
-		if (options?.signal?.aborted) return {
-			deleted,
-			done: false
-		};
-		if (options?.maxBatches !== void 0 && batches >= options.maxBatches) return {
-			deleted,
-			done: false
-		};
-		let limit = batchSize;
-		if (options?.maxRows !== void 0) {
-			const remaining = options.maxRows - deleted;
-			if (remaining <= 0) return {
-				deleted,
-				done: false
-			};
-			limit = Math.min(limit, remaining);
-		}
-		const affected = await deleteBatch(limit);
-		deleted += affected;
-		batches += 1;
-		if (affected < limit) return {
-			deleted,
-			done: true
-		};
-		if (options?.pauseMs) await sleep(options.pauseMs, options.signal);
-	}
-}
-/**
-* Runs the bounded, batched, cancellable delete loop for a set of tables in the
-* given order (callers pass children before parents for cascade-safe pruning),
-* and returns one {@link PruneResult} per table.
-*
-* The loop:
-* - deletes in chunks of `batchSize` (default 1000), each its own statement;
-* - stops a table's loop when a batch deletes fewer rows than requested (drained),
-*   or when `maxBatches`/`maxRows` is hit, or the `signal` aborts — the latter
-*   three leave `done: false` so the caller can resume;
-* - pauses `pauseMs` between batches when set, to avoid starving live traffic.
-*
-* `prune()` only deletes rows; it never reclaims disk. PostgreSQL reuses freed
-* space (dead tuples) via autovacuum on subsequent writes, so tables stop
-* growing. Returning disk to the OS (e.g. `VACUUM FULL`) is left to the operator.
-*/
-async function runPrune({ db, domain, targets, options }) {
-	const results = [];
-	const now = Date.now();
-	for (const target of targets) {
-		if (options?.signal?.aborted) {
-			results.push({
-				domain,
-				table: target.table,
-				deleted: 0,
-				done: false
-			});
-			continue;
-		}
-		const cutoff = cutoffFor(target.policy, target.anchorType, now);
-		const { deleted, done } = await runBatchedDelete({
-			deleteBatch: (limit) => db.pruneBatch({
-				tableName: target.table,
-				column: target.column,
-				cutoff,
-				limit
-			}),
-			batchSize: target.policy.batchSize ?? DEFAULT_BATCH_SIZE,
-			options
-		});
-		results.push({
-			domain,
-			table: target.table,
-			deleted,
-			done
-		});
-	}
-	return results;
+const runBatchedDelete = _mastra_core_storage.runRetentionBatches;
+function runPrune({ db, domain, targets, options }) {
+	return (0, _mastra_core_storage.executeRetentionPrune)({
+		domain,
+		targets,
+		options,
+		cutoffFor: (target, now) => cutoffFor(target.policy, target.anchorType ?? "timestamp", now),
+		deleteBatch: (target, cutoff, limit) => db.pruneBatch({
+			tableName: target.table,
+			column: target.column,
+			cutoff,
+			limit
+		})
+	});
 }
-/**
-* Resolve a domain's `{ tableKey: policy }` map plus its descriptor into an
-* ordered list of {@link PruneTarget}s. `order` lists table keys children-first
-* so cascade-dependent rows are removed before their parents. Table keys not in
-* `policies` are skipped (unset = keep forever).
-*/
 function resolveTargets({ policies, descriptor, order }) {
-	const targets = [];
-	for (const key of order) {
-		const policy = policies[key];
-		const entry = descriptor[key];
-		if (!policy || !entry) continue;
-		targets.push({
-			table: entry.table,
-			column: entry.column,
-			anchorType: entry.anchorType ?? "timestamp",
-			policy
-		});
-	}
-	return targets;
+	return (0, _mastra_core_storage.resolveRetentionTargets)({
+		policies,
+		descriptor,
+		order
+	});
 }
 //#endregion
 //#region src/storage/domains/background-tasks/index.ts
@@ -17315,6 +17209,11 @@ const FEEDBACK_FIELDS = {
 const TRACE_SELECT = `
   r."traceId" AS "traceId",
   r."spanId" AS "rootSpanId",
+  r."name" AS "name",
+  r."entityId" AS "entityId",
+  r."parentSpanId" AS "parentSpanId",
+  r."metadata" AS "metadata",
+  r."input" AS "input",
   r."threadId" AS "threadId",
   r."resourceId" AS "resourceId",
   r."startedAt" AS "startedAt",
@@ -17716,6 +17615,75 @@ LIMIT $${values.length}`,
 		values
 	};
 }
+function discoveryRegistry(scope) {
+	if (scope === "trace") return TRACE_FIELDS;
+	if (scope === "spans") return SPAN_FIELDS;
+	if (scope === "scores") return SCORE_FIELDS;
+	return FEEDBACK_FIELDS;
+}
+function discoverySource(scope) {
+	if (scope === "trace") return "root_scope r";
+	if (scope === "spans") return "current_spans s";
+	if (scope === "scores") return "current_scores s";
+	return "current_feedback s";
+}
+function discoveryCollections(scope) {
+	return scope === "trace" ? /* @__PURE__ */ new Set() : /* @__PURE__ */ new Set([scope]);
+}
+function compilePostgresTraceQueryObservedFields(schema, plan) {
+	const { ctes, values } = compilePostgresTraceScope(schema, plan, /* @__PURE__ */ new Set());
+	const searchParameter = values.length + 1;
+	const search = plan.search ? `AND strpos(lower('metadata.' || entry.key), lower($${searchParameter})) > 0` : "";
+	if (plan.search) values.push(plan.search);
+	values.push(plan.limit + 1);
+	return {
+		text: `WITH ${ctes.join(",\n")}
+SELECT 'metadata.' || entry.key AS path, count(*)::bigint AS occurrences
+FROM root_scope r
+CROSS JOIN LATERAL jsonb_each(CASE WHEN jsonb_typeof(r."metadataRaw") = 'object' THEN r."metadataRaw" ELSE '{}'::jsonb END) entry
+WHERE jsonb_typeof(entry.value) = 'string'
+  AND btrim(entry.value #>> '{}') <> ''
+  AND entry.key <> ''
+  AND strpos(entry.key, '.') = 0
+  AND octet_length('metadata.' || entry.key) <= ${_mastra_core_storage.TRACE_QUERY_MAX_PATH_BYTES}
+  AND octet_length(entry.value #>> '{}') <= ${_mastra_core_storage.TRACE_QUERY_MAX_STRING_BYTES}
+  ${search}
+GROUP BY entry.key
+ORDER BY occurrences DESC, ('metadata.' || entry.key) COLLATE "C" ASC
+LIMIT $${values.length}`,
+		values
+	};
+}
+function compilePostgresTraceQueryValues(schema, plan) {
+	const { ctes, values } = compilePostgresTraceScope(schema, plan, discoveryCollections(plan.predicateScope));
+	let field;
+	if (plan.predicateScope === "trace" && plan.path.startsWith("metadata.")) {
+		const keyParameter = `$${values.length + 1}`;
+		field = `COALESCE(
+      CASE WHEN jsonb_typeof(r."metadataSearch" -> ${keyParameter}) = 'string' THEN r."metadataSearch" ->> ${keyParameter} END,
+      CASE WHEN jsonb_typeof(r."metadataRaw" -> ${keyParameter}) = 'string' THEN NULLIF(btrim(r."metadataRaw" ->> ${keyParameter}), '') END
+    )`;
+		values.push(plan.path.slice(9));
+	} else field = fieldSql(discoveryRegistry(plan.predicateScope), plan.path);
+	const searchParameter = values.length + 1;
+	const search = plan.search ? `AND strpos(lower(value), lower($${searchParameter})) > 0` : "";
+	if (plan.search) values.push(plan.search);
+	values.push(plan.limit + 1);
+	return {
+		text: `WITH ${ctes.join(",\n")}, extracted AS (
+  SELECT ${field}::text AS value FROM ${discoverySource(plan.predicateScope)}
+)
+SELECT value, count(*)::bigint AS count
+FROM extracted
+WHERE value IS NOT NULL
+  AND octet_length(value) <= ${_mastra_core_storage.TRACE_QUERY_MAX_STRING_BYTES}
+  ${search}
+GROUP BY value
+ORDER BY count DESC, value COLLATE "C" ASC
+LIMIT $${values.length}`,
+		values
+	};
+}
 function asIsoTimestamp$1(value) {
 	if (value === null || value === void 0) throw new Error("Trace query returned a null timestamp");
 	return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
@@ -17725,6 +17693,11 @@ function isPostgresStatementTimeout(error) {
 	const candidate = error;
 	return candidate.code === "57014" && String(candidate.message ?? "").includes("statement timeout");
 }
+function isPostgresResourceLimit(error) {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate.code === "53200" || candidate.code === "53400";
+}
 async function runWithPostgresTraceQueryTimeout(client, timeoutMs, execute) {
 	const resolvedTimeoutMs = _mastra_core_storage.resolveTraceQueryTimeoutMs(timeoutMs);
 	try {
@@ -17734,9 +17707,33 @@ async function runWithPostgresTraceQueryTimeout(client, timeoutMs, execute) {
 		});
 	} catch (error) {
 		if (isPostgresStatementTimeout(error)) throw new _mastra_core_storage.TraceQueryExecutionError();
+		if (isPostgresResourceLimit(error)) throw new _mastra_core_storage.TraceQueryResourceLimitError();
 		throw error;
 	}
 }
+async function getTraceQueryObservedFields(client, schema, plan, timeoutMs) {
+	if (plan.predicateScope !== "trace") return {
+		observedFields: [],
+		observedFieldsTruncated: false
+	};
+	const query = compilePostgresTraceQueryObservedFields(schema, plan);
+	const rows = await runWithPostgresTraceQueryTimeout(client, timeoutMs, (transaction) => transaction.any(query.text, query.values));
+	return {
+		observedFields: rows.slice(0, plan.limit).map((row) => _mastra_core_storage.createTraceQueryObservedFieldDescriptor(String(row.path), Number(row.occurrences))),
+		observedFieldsTruncated: rows.length > plan.limit
+	};
+}
+async function getTraceQueryValues(client, schema, plan, timeoutMs) {
+	const query = compilePostgresTraceQueryValues(schema, plan);
+	const rows = await runWithPostgresTraceQueryTimeout(client, timeoutMs, (transaction) => transaction.any(query.text, query.values));
+	return _mastra_core_storage.getTraceQueryValuesResponseSchema.parse({
+		values: rows.slice(0, plan.limit).map((row) => ({
+			value: String(row.value),
+			count: Number(row.count)
+		})),
+		valuesTruncated: rows.length > plan.limit
+	});
+}
 async function queryTraces(client, schema, plan, timeoutMs) {
 	const query = compilePostgresTraceQuery(schema, plan);
 	const rows = await runWithPostgresTraceQueryTimeout(client, timeoutMs, (transaction) => transaction.any(query.text, query.values));
@@ -17755,6 +17752,12 @@ async function queryTraces(client, schema, plan, timeoutMs) {
 	const traces = visibleRows.map((row) => ({
 		traceId: String(row.traceId),
 		rootSpanId: String(row.rootSpanId),
+		name: row.name,
+		entityId: row.entityId ?? null,
+		parentSpanId: row.parentSpanId ?? null,
+		createdAt: asIsoTimestamp$1(row.startedAt),
+		metadata: row.metadata ?? null,
+		inputPreview: _mastra_core_storage.buildInputPreview(row.input) ?? null,
 		threadId: row.threadId == null ? null : String(row.threadId),
 		resourceId: row.resourceId == null ? null : String(row.resourceId),
 		startedAt: asIsoTimestamp$1(row.startedAt),
@@ -18502,7 +18505,7 @@ async function dangerouslyClearTracing(client, schema) {
 * Use it through `MastraCompositeStore` with a dedicated Postgres connection.
 */
 function wrapError(op, error, details) {
-	if (error instanceof _mastra_core_error.MastraError || error instanceof _mastra_core_storage.TraceQueryExecutionError) throw error;
+	if (error instanceof _mastra_core_error.MastraError || error instanceof _mastra_core_storage.TraceQueryExecutionError || error instanceof _mastra_core_storage.TraceQueryResourceLimitError) throw error;
 	throw new _mastra_core_error.MastraError({
 		id: (0, _mastra_core_storage.createStorageErrorId)("PG", op, "FAILED"),
 		domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -18683,6 +18686,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"metrics",
 			"logs",
 			"trace-query",
+			"trace-query-discovery",
 			"thread-query"
 		];
 		return [
@@ -18690,6 +18694,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"logs",
 			"delta-polling",
 			"trace-query",
+			"trace-query-discovery",
 			"thread-query"
 		];
 	}
@@ -18736,6 +18741,12 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 	async queryTraces(plan) {
 		return this.#run("QUERY_TRACES", () => queryTraces(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
 	}
+	async getTraceQueryObservedFields(plan) {
+		return this.#run("GET_TRACE_QUERY_OBSERVED_FIELDS", () => getTraceQueryObservedFields(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
+	}
+	async getTraceQueryValues(plan) {
+		return this.#run("GET_TRACE_QUERY_VALUES", () => getTraceQueryValues(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
+	}
 	async queryThreads(plan) {
 		return this.#run("QUERY_THREADS", () => queryThreads(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
 	}