Cloud Spanner Assistant

Spanner basics

by google · Apache-2.0 license · ★ 20,901 on GitHub

Assists in provisioning instances and databases, designing performant schemas, and querying data in Spanner. Use when designing primary keys, writing SQL queries or client library code, or diagnosing performance issues.

---
name: spanner-basics
metadata:
  version: "1.1.0"
  category: Databases
description: >-
  Assists in provisioning instances and databases, designing performant schemas, and querying data in Spanner. Use when designing primary keys, writing SQL queries or client library code, or diagnosing performance issues.
---

# Spanner Basics

This skill provides core workflows and guidance for administering and developing with Google Cloud Spanner, a fully managed, mission-critical database service offering global transactional consistency and automatic, synchronous replication for high availability.

## Core Principles

-   **Performance First:** Spanner scales horizontally. Efficiency is tied to
    Primary Key design. Always warn against using monotonically increasing/decreasing
    values (like sequential timestamps) as the first part of a primary key to avoid hotspots.

Overview

This skill provides core workflows and guidance for administering and developing with Google Cloud Spanner, a fully managed, mission-critical database service offering global transactional consistency and automatic, synchronous replication for high availability.

Manual install (npx, ZIP)

Claude Codenpx skills add google/skills --skill spanner-basics -g -a claude-code

Claude Code (degit)npx degit google/skills/skills/cloud/spanner-basics#main ~/.claude/skills/spanner-basics

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.3 KB

Read SKILL.md here

google/main1 file shown

SKILL.md3.3 KB

Browse every file on GitHub↗

SKILL.md

Show the full text53 lines

spanner-basics/SKILL.md53 lines · 3.3 KB

PreviewCode

Outline

RawView on GitHub

Spanner Basics

Core Principles

Performance First: Spanner scales horizontally. Efficiency is tied to Primary Key design. Always warn against using monotonically increasing/decreasing values (like sequential timestamps) as the first part of a primary key to avoid hotspots.
Schema Design: Prefer interleaved tables for strongly related parent-child data that is frequently accessed together.

Safety

[!CAUTION] CRITICAL INSTRUCTION: You MUST obtain explicit user confirmation before making any non-emulator database changes (DML or DDL) or destructive operations (such as dropping tables, indexes, or any other Spanner resources). Do not execute them automatically; instead, output the command (e.g., gcloud spanner databases ddl update) and ask for explicit user approval. When database access is unavailable or authentication fails, do not block on trying to verify the existence of the instance, database, or table. Assume the provided resources exist and directly generate the DDL commands.

Common Workflows

Schema Evolution & DDL

Use gcloud spanner databases ddl update to apply schema updates (such as CREATE, ALTER, or DROP tables and indexes).
Reference schema-design.md for guidelines on primary key selection and interleaved tables.

Diagnosing Performance Issues

Use SPANNER_SYS tables to identify slow or resource-intensive queries.
For example, query SPANNER_SYS.QUERY_STATS_TOP_HOUR to find queries with the highest CPU usage.

Reference Directory

Core Concepts: Explanation of Spanner internals, architecture, and design.
CLI Usage: Essential gcloud spanner command-line operations for managing instances and databases.
IAM Security: Roles, permissions, and data governance best practices for Spanner.
Client Library Usage: Using Google Cloud client libraries for Spanner (Java, Go, Python, Node.js).
Terraform Usage: Infrastructure as Code examples for provisioning Spanner instances and databases.
MCP Usage: Using the Spanner remote MCP server.
PostgreSQL Dialect: Best practices and examples for using the PostgreSQL interface in Spanner.
Queues Usage: Cloud Spanner Queues: mental model, design constraints, and links related to transactional message queues.
Schema Design: Guidelines on primary key selection and interleaved tables for performance.

If you need product information that's not found in these references, use the search_documents tool of the Developer Knowledge MCP server.

1	---
2	name: spanner-basics
3	metadata:
4	version: "1.1.0"
5	category: Databases
6	description: >-
7	Assists in provisioning instances and databases, designing performant schemas, and querying data in Spanner. Use when designing primary keys, writing SQL queries or client library code, or diagnosing performance issues.
8	---
9
10	# Spanner Basics
11
12	This skill provides core workflows and guidance for administering and developing with Google Cloud Spanner, a fully managed, mission-critical database service offering global transactional consistency and automatic, synchronous replication for high availability.
13
14	## Core Principles
15
16	- Performance First: Spanner scales horizontally. Efficiency is tied to
17	Primary Key design. Always warn against using monotonically increasing/decreasing
18	values (like sequential timestamps) as the first part of a primary key to avoid hotspots.
19	- Schema Design: Prefer interleaved tables for strongly related parent-child data
20	that is frequently accessed together.
21
22	## Safety
23
24	> [!CAUTION] CRITICAL INSTRUCTION: You MUST obtain explicit user confirmation before making any non-emulator database changes (DML or DDL) or destructive operations (such as dropping tables, indexes, or any other Spanner resources). Do not execute them automatically; instead, output the command (e.g., `gcloud spanner databases ddl update`) and ask for explicit user approval.
25	> When database access is unavailable or authentication fails, do not block on trying to verify the existence of the instance, database, or table. Assume the provided resources exist and directly generate the DDL commands.
26
27	## Common Workflows
28
29	### Schema Evolution & DDL
30
31	1. Use `gcloud spanner databases ddl update` to apply schema updates (such as CREATE, ALTER, or DROP tables and indexes).
32	2. Reference [schema-design.md](references/schema-design.md) for guidelines on primary key selection and interleaved tables.
33
34	### Diagnosing Performance Issues
35
36	1. Use `SPANNER_SYS` tables to identify slow or resource-intensive queries.
37	2. For example, query `SPANNER_SYS.QUERY_STATS_TOP_HOUR` to find queries with the highest CPU usage.
38
39	## Reference Directory
40
41	- [Core Concepts](references/core-concepts.md): Explanation of Spanner internals, architecture, and design.
42	- [CLI Usage](references/cli-usage.md): Essential `gcloud spanner` command-line operations for managing instances and databases.
43	- [IAM Security](references/iam-security.md): Roles, permissions, and data governance best practices for Spanner.
44	- [Client Library Usage](references/client-library-usage.md): Using Google Cloud client libraries for Spanner (Java, Go, Python, Node.js).
45	- [Terraform Usage](references/terraform-usage.md): Infrastructure as Code examples for provisioning Spanner instances and databases.
46	- [MCP Usage](references/mcp-usage.md): Using the Spanner remote MCP server.
47	- [PostgreSQL Dialect](references/postgresql-dialect.md): Best practices and examples for using the PostgreSQL interface in Spanner.
48	- [Queues Usage](references/queues-usage.md): Cloud Spanner Queues: mental model, design constraints, and links related to transactional message queues.
49	- [Schema Design](references/schema-design.md): Guidelines on primary key selection and interleaved tables for performance.
50
51	If you need product information that's not found in these references, use the
52	`search_documents` tool of the Developer Knowledge MCP server.
53