Skip to content
Google Cloud Spanner Basics

Google Cloud Spanner Basics Skill

Google's official Spanner skill: provision instances, design primary keys that do not hotspot, write SQL and client-library code, and diagnose slow queries — with DDL and DML gated behind your approval.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from google/skills.

$ npx skills add google/skills --skill spanner-basics

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/spanner-basics/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/google/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/cloud/spanner-basics ~/.claude/skills/spanner-basics

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/spanner-basics/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Warns against monotonic primary keys that create write hotspots
  • Prefers interleaved tables for parent-child data accessed together
  • Requires explicit user confirmation before any non-emulator DDL, DML or destructive operation
  • Covers instance and database provisioning, schema evolution, queries and client-library code
  • Performance diagnosis workflow for slow queries and index problems
  • Generates DDL without blocking when database access or auth is unavailable

Cloud Spanner gives you global transactional consistency and synchronous replication, and charges for it in a currency most developers are not used to paying: schema design. Get the primary key wrong and the database scales horizontally into a single hot split. Google's official skill exists mostly to stop an agent from making that mistake on your behalf.

What it insists on
  • Primary keys first. The skill actively warns against monotonically increasing or decreasing values — sequential timestamps, auto-increment IDs — as the leading component of a primary key, because in Spanner that concentrates every write on one server rather than spreading it.
  • Interleaving where it earns its keep. For strongly related parent-child data that is read together, it prefers interleaved tables, which co-locate the rows.
  • Confirmation before change. DDL and DML against any non-emulator database, and every destructive operation such as dropping a table or index, must be approved by you explicitly. The agent outputs the command — gcloud spanner databases ddl update and friends — and waits rather than running it.
What it covers

Provisioning instances and databases; schema evolution and DDL; writing queries and client-library code; and diagnosing performance problems, which in Spanner usually means tracing a slow query back to a key design or a missing index rather than to the query text.

There is a pragmatic touch worth noting: when database access is unavailable or authentication fails, the skill does not stall trying to confirm that an instance or table exists. It assumes the resources you named are real and generates the DDL, which is the right call for an agent that would otherwise spend its turn failing to authenticate.

Getting it

Part of Google's official agent-skills catalogue at github.com/google/skills, under Apache-2.0. Pairs naturally with the gcloud CLI skill from the same repository.

Try it

Once installed, ask your agent something like:

Design a Spanner schema for orders and order line items, and explain why you chose that primary key.

SKILL.md

The instructions your agent loads, as published by Google Cloud.

SKILL.md
name
spanner-basics
metadata
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.

  • 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
  1. Use gcloud spanner databases ddl update to apply schema updates (such as CREATE, ALTER, or DROP tables and indexes).
  2. Reference [schema-design.md](references/schema-design.md) for guidelines on primary key selection and interleaved tables.
Diagnosing Performance Issues
  1. Use SPANNER_SYS tables to identify slow or resource-intensive queries.
  2. For example, query SPANNER_SYS.QUERY_STATS_TOP_HOUR to find queries with the highest CPU usage.
Reference Directory
  • [Core Concepts](references/core-concepts.md): Explanation of Spanner internals, architecture, and design.
  • [CLI Usage](references/cli-usage.md): Essential gcloud spanner command-line operations for managing instances and databases.
  • [IAM Security](references/iam-security.md): Roles, permissions, and data governance best practices for Spanner.
  • [Client Library Usage](references/client-library-usage.md): Using Google Cloud client libraries for Spanner (Java, Go, Python, Node.js).
  • [Terraform Usage](references/terraform-usage.md): Infrastructure as Code examples for provisioning Spanner instances and databases.
  • [MCP Usage](references/mcp-usage.md): Using the Spanner remote MCP server.
  • [PostgreSQL Dialect](references/postgresql-dialect.md): Best practices and examples for using the PostgreSQL interface in Spanner.
  • [Schema Design](references/schema-design.md): 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.

Install
Browse all skills →