@mastra/spanner 0.0.0-a-b-demo-20260526202724

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# @mastra/spanner
+
+## 0.0.0-a-b-demo-20260526202724
+
+### Major Changes
+
+- Added a Google Cloud Spanner storage adapter (`@mastra/spanner`) targeting the GoogleSQL dialect. The adapter implements the `memory`, `workflows`, `scores`, `backgroundTasks`, `agents`, `mcpClients`, `mcpServers`, `skills`, `blobs`, `promptBlocks`, `scorerDefinitions`, `schedules`, and `observability` storage domains and works with both managed Cloud Spanner instances and the local Spanner emulator. The `schedules` domain plugs into Mastra's built-in `WorkflowScheduler` for cron-driven workflow triggers, and the `observability` domain persists AI tracing spans in `mastra_ai_spans` to power the Studio traces UI (JSON containment filters compile to per-key `JSON_VALUE` equality and `EXISTS` over `JSON_QUERY_ARRAY` since Spanner has no `@>` operator). ([#15955](https://github.com/mastra-ai/mastra/pull/15955))
+
+  ```typescript
+  import { SpannerStore } from '@mastra/spanner';
+
+  const storage = new SpannerStore({
+    id: 'spanner-storage',
+    projectId: process.env.SPANNER_PROJECT_ID!,
+    instanceId: process.env.SPANNER_INSTANCE_ID!,
+    databaseId: process.env.SPANNER_DATABASE_ID!,
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cfa2e3a`](https://github.com/mastra-ai/mastra/commit/cfa2e3a5292322f48bb28b4d257d631da7f9d3cc), [`0cbece9`](https://github.com/mastra-ai/mastra/commit/0cbece9d832cb134a74cdbf3682d390a058215a4), [`2f5f58a`](https://github.com/mastra-ai/mastra/commit/2f5f58a9a8bb13bcdc6789db221eef7c9bf1ff02), [`7dfe1bc`](https://github.com/mastra-ai/mastra/commit/7dfe1bcfe71d261a6fd6bbf29b1dec49d78fb98f), [`ac442a4`](https://github.com/mastra-ai/mastra/commit/ac442a42fda0354ac2bcea772bf6691cb3e9dbb3), [`b7286f4`](https://github.com/mastra-ai/mastra/commit/b7286f4308267f5fd70e6bfee10dba9472640906), [`6096445`](https://github.com/mastra-ai/mastra/commit/60964459733f0ab384584d95e19c36607ffdf7b0), [`a481027`](https://github.com/mastra-ai/mastra/commit/a481027b549ba1018414990c8f045eaee7b9f413), [`1e5c067`](https://github.com/mastra-ai/mastra/commit/1e5c067d2e20a781af670578180d1ee249806d41), [`168fa09`](https://github.com/mastra-ai/mastra/commit/168fa09d6b39114cb8c13bd06f1dccb9bc81c6cd), [`df1947a`](https://github.com/mastra-ai/mastra/commit/df1947affa40f742067542251fac7ca759492ef4), [`ee59b74`](https://github.com/mastra-ai/mastra/commit/ee59b743ce73ad11784b4d9c6fbba8568edee1c8), [`a97b1a0`](https://github.com/mastra-ai/mastra/commit/a97b1a0abaed83946c3519d1e0f680d0815b8a67), [`008baaf`](https://github.com/mastra-ai/mastra/commit/008baafd8d851f831407045aebead5a2e3342eff), [`801baa0`](https://github.com/mastra-ai/mastra/commit/801baa07cccdbaec1d00942a92bdc831111744a2), [`8116436`](https://github.com/mastra-ai/mastra/commit/81164363eb225d774e41ff27da6a5ea611406688), [`c27c4b9`](https://github.com/mastra-ai/mastra/commit/c27c4b9f137df5414fca4e45896aceccff6b0ed5), [`08b3b59`](https://github.com/mastra-ai/mastra/commit/08b3b590dd960dee6c9a6e39272f8927d803db6e), [`9365eb3`](https://github.com/mastra-ai/mastra/commit/9365eb3773e9d44134ed097fa477b6430baf4245), [`b3c3b18`](https://github.com/mastra-ai/mastra/commit/b3c3b189121489a3a51a8fd8204b569be9a89fe5), [`b9d33b4`](https://github.com/mastra-ai/mastra/commit/b9d33b45c2f62bad0d3e1384ac2b11622c9fef58), [`70cb714`](https://github.com/mastra-ai/mastra/commit/70cb7149c8f16f478e15b58498254a53181750a4), [`91cf0e0`](https://github.com/mastra-ai/mastra/commit/91cf0e027e511b871481a8576b56b7af83b15afd), [`7f9da22`](https://github.com/mastra-ai/mastra/commit/7f9da22efd5aa595e138a31de55a5f0f2f28b33d), [`b9d33b4`](https://github.com/mastra-ai/mastra/commit/b9d33b45c2f62bad0d3e1384ac2b11622c9fef58)]:
+  - @mastra/core@0.0.0-a-b-demo-20260526202724
+
+## 2.0.0-alpha.0
+
+### Major Changes
+
+- Added a Google Cloud Spanner storage adapter (`@mastra/spanner`) targeting the GoogleSQL dialect. The adapter implements the `memory`, `workflows`, `scores`, `backgroundTasks`, `agents`, `mcpClients`, `mcpServers`, `skills`, `blobs`, `promptBlocks`, `scorerDefinitions`, `schedules`, and `observability` storage domains and works with both managed Cloud Spanner instances and the local Spanner emulator. The `schedules` domain plugs into Mastra's built-in `WorkflowScheduler` for cron-driven workflow triggers, and the `observability` domain persists AI tracing spans in `mastra_ai_spans` to power the Studio traces UI (JSON containment filters compile to per-key `JSON_VALUE` equality and `EXISTS` over `JSON_QUERY_ARRAY` since Spanner has no `@>` operator). ([#15955](https://github.com/mastra-ai/mastra/pull/15955))
+
+  ```typescript
+  import { SpannerStore } from '@mastra/spanner';
+
+  const storage = new SpannerStore({
+    id: 'spanner-storage',
+    projectId: process.env.SPANNER_PROJECT_ID!,
+    instanceId: process.env.SPANNER_INSTANCE_ID!,
+    databaseId: process.env.SPANNER_DATABASE_ID!,
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`0cbece9`](https://github.com/mastra-ai/mastra/commit/0cbece9d832cb134a74cdbf3682d390a058215a4), [`7dfe1bc`](https://github.com/mastra-ai/mastra/commit/7dfe1bcfe71d261a6fd6bbf29b1dec49d78fb98f), [`70cb714`](https://github.com/mastra-ai/mastra/commit/70cb7149c8f16f478e15b58498254a53181750a4), [`7f9da22`](https://github.com/mastra-ai/mastra/commit/7f9da22efd5aa595e138a31de55a5f0f2f28b33d)]:
+  - @mastra/core@1.37.0-alpha.6
+
+## 1.0.0
+
+### Major Changes
+
+- Initial stable release of the Google Cloud Spanner storage adapter for Mastra. Supports the GoogleSQL dialect with full storage-domain parity: `memory`, `workflows`, `scores`, `backgroundTasks`, `agents`, `mcpClients`, `mcpServers`, `skills`, `blobs`, `promptBlocks`, `scorerDefinitions`, `schedules` (cron-driven workflow triggers consumed by `WorkflowScheduler`), and `observability` (AI tracing spans persisted in `mastra_ai_spans` with the full trace read/write surface). Works against managed Spanner instances and the local Spanner emulator.

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,108 @@
+# @mastra/spanner
+
+Google Cloud Spanner storage adapter for Mastra. Implements the GoogleSQL dialect.
+
+## Installation
+
+```bash
+npm install @mastra/spanner
+```
+
+## Prerequisites
+
+- A Cloud Spanner instance and database created with the GoogleSQL dialect.
+- Application credentials available to the Node.js client (Application Default Credentials, service account JSON, or `GOOGLE_APPLICATION_CREDENTIALS`).
+- For local development, the [Spanner emulator](https://cloud.google.com/spanner/docs/emulator) running on `localhost:9010`.
+
+## Usage
+
+### Connecting to a managed Cloud Spanner database
+
+```typescript
+import { SpannerStore } from '@mastra/spanner';
+
+const store = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: 'my-gcp-project',
+  instanceId: 'my-instance',
+  databaseId: 'mastra',
+});
+```
+
+### Connecting to the Spanner emulator
+
+```typescript
+process.env.SPANNER_EMULATOR_HOST = 'localhost:9010';
+
+const store = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: 'test-project',
+  instanceId: 'test-instance',
+  databaseId: 'test-db',
+  // Skip auth checks when talking to the emulator
+  spannerOptions: { servicePath: 'localhost', port: 9010, sslCreds: undefined },
+});
+```
+
+The store automatically detects the `SPANNER_EMULATOR_HOST` env var and uses
+unauthenticated channels when set. You can also create the instance/database
+through the emulator using the standard `gcloud` CLI.
+
+### Pre-configured client or database
+
+If you already manage a Spanner client elsewhere, pass the database directly:
+
+```typescript
+import { Spanner } from '@google-cloud/spanner';
+import { SpannerStore } from '@mastra/spanner';
+
+const spanner = new Spanner({ projectId: 'my-project' });
+const database = spanner.instance('my-instance').database('mastra');
+
+const store = new SpannerStore({
+  id: 'spanner-storage',
+  database,
+});
+```
+
+## Notes on the GoogleSQL dialect
+
+- Tables are created with the GoogleSQL dialect using `STRING(MAX)` for text/JSON
+  payloads, `INT64`, `FLOAT64`, `BOOL` and `TIMESTAMP`.
+- DDL is applied through `database.updateSchema(...)` (long-running operation).
+- Upserts use `INSERT OR UPDATE`. Deletes use `DELETE WHERE TRUE` (Spanner has no
+  `TRUNCATE`).
+- Identifiers are quoted with backticks.
+- The adapter does not use named schemas. Use a dedicated database for isolation.
+
+## Storage domains
+
+The adapter implements the following storage domains:
+
+- `memory`: threads, messages, resources
+- `workflows`: workflow snapshots and run state
+- `scores`: evaluation scores
+- `backgroundTasks`: background tool execution state
+- `agents`: thin agent records and versioned config snapshots
+- `mcpClients`: MCP client configurations with version history
+- `mcpServers`: MCP server configurations with version history
+- `skills`: skill records and versioned skill snapshots
+- `blobs`: content-addressable blob store (used by the skills domain)
+- `promptBlocks`: prompt block records and versioned template/rules snapshots
+- `scorerDefinitions`: scorer definition records and versioned scoring-config snapshots
+- `schedules`: cron-driven workflow schedules and trigger history (consumed by `WorkflowScheduler`)
+- `observability`: AI tracing spans (per-trace and per-span records) used by the Studio traces UI
+
+## Testing locally with the emulator
+
+Start the emulator:
+
+```bash
+docker compose up -d
+```
+
+Then run the tests:
+
+```bash
+ENABLE_TESTS=true pnpm test
+```

package/dist/docs/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mastra-spanner
+description: Documentation for @mastra/spanner. Use when working with @mastra/spanner APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/spanner"
+  version: "0.0.0-a-b-demo-20260526202724"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/spanner to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Reference
+
+- [Reference: Google Cloud Spanner storage](references/reference-storage-spanner.md) - Documentation for the Google Cloud Spanner storage implementation in Mastra.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.0.0-a-b-demo-20260526202724",
+  "package": "@mastra/spanner",
+  "exports": {},
+  "modules": {}
+}

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

@@ -0,0 +1,213 @@
+# Google Cloud Spanner storage
+
+The Google Cloud Spanner storage implementation provides a horizontally scalable, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/spanner@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/spanner@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/spanner@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/spanner@latest
+```
+
+## Usage
+
+```typescript
+import { SpannerStore } from '@mastra/spanner'
+
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+```
+
+The instance and database must already exist. The adapter creates the required tables on first use, so the credentials provided to the Spanner client need permission to run schema changes (or run `storage.init()` once during a deploy step with elevated credentials).
+
+## Parameters
+
+**id** (`string`): Unique identifier for this storage instance.
+
+**projectId** (`string`): Google Cloud project ID. Required unless \`database\` is provided.
+
+**instanceId** (`string`): Cloud Spanner instance ID. Required unless \`database\` is provided.
+
+**databaseId** (`string`): Cloud Spanner database ID. Required unless \`database\` is provided.
+
+**database** (`@google-cloud/spanner Database`): Pre-configured Spanner Database handle. Use this when you manage the Spanner client elsewhere (for example, to share auth or connection options across services).
+
+**spannerOptions** (`object`): Options forwarded to the \`@google-cloud/spanner\` client constructor. Use this to set credentials, custom endpoints, or to point at the local emulator.
+
+**disableInit** (`boolean`): When true, skip automatic table creation on first use. You must call \`storage.init()\` explicitly during a separate deploy step. (Default: `false`)
+
+**skipDefaultIndexes** (`boolean`): When true, skip creation of default indexes during initialization. (Default: `false`)
+
+**indexes** (`CreateIndexOptions[]`): Custom secondary indexes to create. Each index must specify the table it belongs to. Indexes are routed to the appropriate domain based on the table name.
+
+**initMode** (`'sync' | 'validate'`): Controls schema-initialization behavior. \`'sync'\` creates missing tables, columns, and indexes during \`init()\` (the historical behavior). \`'validate'\` issues no DDL and instead verifies that every expected table, column, and default/custom index already exists, throwing a typed user error if anything is missing — useful when an external process (Terraform, Liquibase, a release pipeline, etc.) owns the schema and Mastra should only verify it. (Default: `'sync'`)
+
+## Constructor examples
+
+You can instantiate `SpannerStore` in several ways:
+
+```typescript
+import { Spanner } from '@google-cloud/spanner'
+import { SpannerStore } from '@mastra/spanner'
+
+// Using projectId / instanceId / databaseId
+const store1 = new SpannerStore({
+  id: 'spanner-storage-1',
+  projectId: 'my-gcp-project',
+  instanceId: 'my-instance',
+  databaseId: 'mastra',
+})
+
+// Reusing an existing Spanner Database handle
+const spanner = new Spanner({ projectId: 'my-gcp-project' })
+const database = spanner.instance('my-instance').database('mastra')
+
+const store2 = new SpannerStore({
+  id: 'spanner-storage-2',
+  database,
+})
+
+// Using the local Spanner emulator (set the SPANNER_EMULATOR_HOST env var)
+process.env.SPANNER_EMULATOR_HOST = 'localhost:9010'
+const store3 = new SpannerStore({
+  id: 'spanner-storage-emulator',
+  projectId: 'test-project',
+  instanceId: 'test-instance',
+  databaseId: 'test-db',
+  spannerOptions: { servicePath: 'localhost', port: 9010, sslCreds: undefined },
+})
+```
+
+## Additional notes
+
+### Schema management
+
+The storage adapter creates the following tables, all using the GoogleSQL dialect:
+
+- `mastra_workflow_snapshot`: workflow state and execution data
+- `mastra_threads`: conversation threads
+- `mastra_messages`: individual messages
+- `mastra_resources`: resource working memory
+- `mastra_scorers`: evaluation scores
+- `mastra_background_tasks`: background tool execution state
+- `mastra_agents`: thin agent records (id, status, active version)
+- `mastra_agent_versions`: versioned agent configuration snapshots
+- `mastra_mcp_clients` / `mastra_mcp_client_versions`: MCP client configurations and their version history
+- `mastra_mcp_servers` / `mastra_mcp_server_versions`: MCP server configurations and their version history
+- `mastra_skills` / `mastra_skill_versions`: skill records and versioned skill snapshots (instructions, references, scripts, assets, content tree)
+- `mastra_skill_blobs`: content-addressable blob store keyed by SHA-256 hash, used for skill version contents
+- `mastra_prompt_blocks` / `mastra_prompt_block_versions`: prompt block records and versioned content snapshots (template content, rules, request-context schema)
+- `mastra_scorer_definitions` / `mastra_scorer_definition_versions`: scorer definition records and versioned config snapshots (judge instructions, model, score range, preset config, default sampling)
+- `mastra_schedules` / `mastra_schedule_triggers`: cron-driven workflow schedules and trigger history, consumed by Mastra's built-in `WorkflowScheduler`
+- `mastra_ai_spans`: AI tracing spans for observability (per-trace and per-span records, used to power the Studio traces UI)
+
+Tables are created with `STRING(MAX)` for text and JSON payloads, `INT64`, `FLOAT64`, `BOOL`, and `TIMESTAMP`.
+
+Two tables also carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
+
+- `mastra_workflow_snapshot.snapshotStatus` — extracts `$.status` from `snapshot`; backs `listWorkflowRuns({ status })`.
+- `mastra_schedules.target_workflow_id` — extracts `$.workflowId` from `target`; backs `listSchedules({ workflowId })`.
+
+Both are added via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` during `init()` and skipped under `initMode: 'validate'` (where the schema is owned externally). When the column is absent, the adapter falls back to a `JSON_VALUE` filter at runtime.
+
+The adapter does not create or use named schemas; use a dedicated database for isolation.
+
+### Initialization
+
+When you pass storage to the `Mastra` class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SpannerStore } from '@mastra/spanner'
+
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+})
+```
+
+If you use storage directly, call `init()` once before the first operation. Spanner does not allow concurrent schema changes, so `SpannerStore.init()` runs each domain's setup sequentially.
+
+```typescript
+const storage = new SpannerStore({
+  id: 'spanner-storage',
+  projectId: process.env.SPANNER_PROJECT_ID!,
+  instanceId: process.env.SPANNER_INSTANCE_ID!,
+  databaseId: process.env.SPANNER_DATABASE_ID!,
+})
+
+await storage.init()
+const memory = await storage.getStore('memory')
+const thread = await memory?.getThreadById({ threadId: '...' })
+```
+
+> **Warning:** If `init()` is not called and `disableInit` is true, the required tables will not exist and storage operations will fail.
+
+### GoogleSQL specifics
+
+A few behaviors differ from other relational adapters:
+
+- Upserts use `INSERT OR UPDATE`. Spanner does not provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
+- There is no `TRUNCATE`; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
+- Identifiers are quoted with backticks.
+- DDL is applied through `database.updateSchema(...)`, which is asynchronous (long-running operation).
+- `NULLS FIRST/LAST` is not supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
+- JSON containment is not supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches are not expressible.
+
+### Direct database access
+
+`SpannerStore` exposes the underlying Spanner client objects:
+
+```typescript
+store.database // @google-cloud/spanner Database
+store.instance // @google-cloud/spanner Instance (when created internally)
+store.spanner // @google-cloud/spanner Spanner client (when created internally)
+```
+
+These are intended for advanced scenarios such as bespoke transactions or schema introspection. When you reuse the database directly, you bypass the adapter's validation and JSON conversion logic.
+
+### Local development with the emulator
+
+Run the Cloud Spanner emulator locally with Docker:
+
+```bash
+docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator
+```
+
+Set `SPANNER_EMULATOR_HOST=localhost:9010` and create the instance and database before running your app:
+
+```bash
+gcloud spanner instances create test-instance --config=emulator-config --nodes=1
+gcloud spanner databases create test-db --instance=test-instance
+```
+
+Then connect with the same env var set in your Node.js process; the `@google-cloud/spanner` client detects the emulator automatically.