canonical: https://jentic.com/apis/googleapis.com/spanner

# Google Cloud Spanner API

The Cloud Spanner API exposes Google's globally distributed, strongly consistent relational database as REST operations. It covers instance and database lifecycle (create, list, update, drop), schema management via DDL, session-based read and write transactions, partitioned reads for parallel scans, and backup, restore, and point-in-time database operations. Long-running operations for backups, restores, and database moves are tracked through standard operations endpoints.

## For AI agents

Run SQL queries and DML against globally distributed Cloud Spanner databases, manage schemas and instances, and orchestrate backups and restores. Sessions and transactions are first-class.

## Scope

Does not handle ETL pipelines, BI dashboards, or Postgres-compatible drivers - use for Spanner instance, database, session, and backup management only.

## Capabilities

- Provision Spanner instances and databases with chosen node counts and configurations
- Apply DDL changes to evolve a database schema online
- Open sessions, run SQL or partitioned reads, and commit or rollback transactions
- Execute batched DML statements for high-throughput writes within a transaction
- Take, list, and restore from backups, including copying backups across instances
- Move a database between instance configurations or change quorum for regional failover

## Use cases

### Provision Spanner for a New Service

When a team launches a new globally distributed service, automation creates a Spanner instance, then a database with an initial DDL script defining tables and indexes. The Cloud Spanner API exposes instance creation as a long-running operation and database creation with extraStatements for first-pass schema, so a service can be storage-ready in minutes.

Example prompt: POST /v1/{+parent}/instances with config 'regional-us-central1' and nodeCount=3, then POST /v1/{+parent}/databases with createStatement and the initial DDL extraStatements.

### Read-Only Analytics Query

Issue a read-only SQL query against a Spanner database from a reporting agent. The flow opens a session, executes the SQL with single-use bounded staleness for cheaper reads, and returns rows. Cloud Spanner's strong consistency makes this safe for cross-region analytics.

Example prompt: POST /v1/{+database}/sessions to open a session, POST sessions/{session}:executeSql with sql='SELECT name, count FROM Metrics WHERE day=@d' and a 60-second staleness.

### Scheduled Backup and Restore Drill

Run a nightly backup of a production Spanner database and periodically test the restore path into a staging instance. The API supports POST /v1/{+parent}/backups for take, GET listing, and POST /v1/{+parent}/databases:restore for the restore path. Each is a long-running operation trackable via the operations endpoint.

Example prompt: Create a backup of database prod-db with expireTime=now+30d, then poll the returned operation until done; in staging, POST databases:restore with the backup name.

### AI Agent Schema Evolution

An AI agent reviewing a feature request decides a new column is needed on a Spanner table. The agent searches Jentic for the DDL update operation, loads the schema, and submits an updateDdl request. Jentic returns a long-running operation handle so the agent can poll for completion before proceeding.

Example prompt: Search Jentic for 'apply DDL to a Spanner database', execute PATCH /v1/{+database}/ddl with statements=['ALTER TABLE Orders ADD COLUMN region STRING(2)'].

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/{+database}/sessions | Create a session for executing reads and transactions |
| POST | /v1/{+database}/sessions:batchCreate | Create multiple sessions in one call |
| PATCH | /v1/{+database}/ddl | Apply DDL statements to evolve a database schema |
| GET | /v1/{+name} | Get an instance, database, backup, or operation by resource name |
| POST | /v1/{+name}:cancel | Cancel a long-running operation |
| POST | /v1/{+name}:move | Move a database between instance configurations |
| POST | /v1/{+name}:changequorum | Change the quorum configuration of a database |

## Key resources

- **projects.instances** — Create, list, get, update, and delete Spanner instances; manage their configs and IAM.
- **projects.instances.databases** — Create, list, get, drop, restore, and update DDL on databases; export and copy databases.
- **projects.instances.databases.sessions** — Open sessions, execute SQL and DML, manage transactions, and run partitioned reads.
- **projects.instances.backups** — Take, list, copy, and delete backups, and restore databases from them.
- **projects.instances.operations** — Track long-running operations such as backup, restore, and instance updates.

## Why Jentic

- **Setup:** Wiring the Cloud Spanner API by hand means configuring a service account, minting OAuth access tokens against spanner.googleapis.com, and managing sessions and long-running operations yourself. Through Jentic you install once, import the Cloud Spanner API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Spanner puts the database or instance in the URL path (/v1/{database}/sessions, /v1/{name}:move), so a rule can pin your agent to one database: it can create sessions and apply DDL there and nothing else. You choose the operations it may call, so instance moves or changequorum are not included unless you add them.
- **Credential handling:** Your Spanner OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a SQL query against a Spanner database' or 'back up a Spanner database', and Jentic returns the matching Spanner operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BigQuery API** — BigQuery is an analytics warehouse; Spanner is an OLTP database with strong consistency.
- **Cloud Firestore API** — Firestore is a document database with simpler scaling; Spanner is relational with horizontal SQL.
- **Google IAM API** — IAM controls the roles that grant access to Spanner instances, databases, and backups.
- **AlloyDB API** — AlloyDB is PostgreSQL-compatible with regional scaling; Spanner offers global strong consistency.

## FAQ

### What authentication does the Cloud Spanner API use?

The Cloud Spanner API uses OAuth 2.0 with the cloud-platform or spanner.data scope. Through Jentic, OAuth credentials are stored in your Jentic One instance and exchanged for short-lived access tokens, so service-account JSON keys never enter the agent context.

### Can I run arbitrary SQL against a Spanner database with the API?

Yes. Open a session under POST /v1/{+database}/sessions, then call POST .../sessions/{session}:executeSql with the SQL string and any parameters. For DML, wrap the call in a transaction by including a transaction selector with begin or id fields.

### What are the rate limits for the Cloud Spanner API?

Cloud Spanner enforces per-instance throughput limits scaled by node count rather than per-call quotas. There are also admin-API quotas (default ~5 requests per second for instance and database admin calls). Heavy DML or large reads should be chunked across sessions to fit within node throughput.

### How do I take a Spanner backup through Jentic?

Search Jentic for 'back up a Cloud Spanner database', load the backups.create schema, then execute POST /v1/{+parent}/backups with the source database name and an expireTime. The response returns a long-running operation that Jentic surfaces so the agent can poll for completion.

### Is the Cloud Spanner API free?

Cloud Spanner itself is billed per node hour and per GB of storage, with backup storage charged separately. The API surface has no per-call charge - costs come from the underlying instance running the queries.

### Can I run a partitioned read for a large scan?

Yes. Call POST .../sessions/{session}:partitionRead or partitionQuery to get partition tokens, then issue parallel POST .../sessions/{session}:streamingRead calls - one per partition - to scan the table in parallel.

### Can I limit what my agent is allowed to do with the Cloud Spanner API?

Yes. Because you run Jentic One yourself, your own rules decide which Spanner operations and which OAuth credential the agent can use. Since Spanner puts the database or instance in the URL path, such as /v1/{database}/sessions, you can pin the agent to a single database so it may only open sessions, run SQL, and apply DDL there. Destructive operations like moving a database or changing quorum stay off limits unless you explicitly add them.