@mastra/spanner 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @mastra/spanner
+
+## 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/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mastra/spanner",
+  "version": "0.0.0",
+  "description": "Google Cloud Spanner provider for Mastra - db storage capabilities (GoogleSQL dialect)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@google-cloud/spanner": "^8.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.15",
+    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/ui": "4.1.5",
+    "eslint": "^10.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.5",
+    "@internal/lint": "0.0.97",
+    "@mastra/core": "1.37.0-alpha.7",
+    "@internal/storage-test-utils": "0.0.93",
+    "@internal/types-builder": "0.0.72"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=1.0.0-0 <2.0.0-0"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "homepage": "https://mastra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastra-ai/mastra.git",
+    "directory": "stores/spanner"
+  },
+  "bugs": {
+    "url": "https://github.com/mastra-ai/mastra/issues"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build:lib": "tsup --silent --config tsup.config.ts",
+    "build:watch": "tsup --watch --silent --config tsup.config.ts",
+    "pretest": "docker compose up -d && (for i in $(seq 1 30); do nc -z localhost 9010 && exit 0; sleep 1; done; echo 'Spanner emulator did not become ready on localhost:9010 within 30s' >&2; exit 1)",
+    "test": "vitest run",
+    "posttest": "docker compose down -v",
+    "pretest:watch": "docker compose up -d",
+    "test:watch": "vitest watch",
+    "posttest:watch": "docker compose down -v",
+    "lint": "eslint ."
+  }
+}