Assists in provisioning instances and databases, designing performant schemas, and querying data in Cloud Spanner on Google Cloud. Use when designing primary keys, writing SQL queries or client library code, or diagnosing performance issues.
Use the spanner-basics skill to review my proposed table schema and primary key for hotspot risks. Consider whether frequently accessed parent-child data would benefit from interleaved tables, and explain a small set of recommended schema changes without applying them.
Required inputs
The proposed Spanner table schema and primary key.
Expected insert patterns and common queries.
Relevant parent-child relationships and whether those records are frequently accessed together.
Previously published starter task based on a pinned source version; check the source and required inputs before running. Task evidence ↗
SKILL.md
name: spanner-basicsmetadata: version: "1.1.2" category: Databasesdescription: >- Assists in provisioning instances and databases, designing performant schemas, and querying data in Cloud Spanner on Google Cloud. 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 Cloud Spanner on Google Cloud, a fully managed, mission-critical database service offering global transactional consistency and automatic, synchronous replication for high availability.
Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read Usage Attribution. For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix gcloud with
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:spanner-basics)"
and append agent-skills/1.0 (skill:spanner-basics) to User-Agent headers.
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.