Skip to content
Google Cloud Spanner Basics

Google Cloud Spanner BasicsSkill

by Google Cloud
Released
Apache-2.0
Repository Docs
markdown Development

Summary

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.

Features

  • 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

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
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.

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Copy skills/cloud/spanner-basics from github.com/google/skills into your agent's skills directory. Works against a real Spanner instance via gcloud/client libraries, or against the Spanner emulator for unattended changes.

Example Usage

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

Description

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.

Related Skills

Skill: gcloud CLI Guardrails

by Google Cloud

New

Google's official skill for driving the gcloud CLI safely from an agent: validate every command against its own help text, cap the output, and refuse the operations that should never run unattended.

Development

Skill: Convex

by Convex

New

Convex's official top-level agent skill — routes an agent to the right convex-* skill for the task and to a served capability catalogue that stays current without a reinstall.

Development

Skill: Shopify Liquid & Themes

by Shopify

New

Official Shopify skill for theme development in Liquid — teaches an agent the modern theme architecture of sections, blocks and snippets, and validates generated templates and schemas.

Development
1 views

Skill: Shopify Admin GraphQL

by Shopify

New

Shopify's official skill for writing Admin GraphQL queries and mutations — it searches the live API docs and validates every operation against the schema before handing you code.

Development
1 views
Browse all skills →