Available interfaces
You can use one of several programmatic interfaces when interacting with Cloud Spanner. These are the available interfaces, in the order that we recommend using them:
- Client libraries: The Cloud Spanner client libraries are available in multiple languages and are built on gRPC. These client libraries provide a layer of abstraction on top of gRPC and handle the details of session management, transaction execution, retries, and more.
- ORM and framework drivers: Google supports open-source Cloud Spanner drivers for several popular object-relational mapping libraries (ORMs) and frameworks, such as JDBC. These drivers allow the use of Cloud Spanner databases through APIs defined by those frameworks.
- RPC API: If a client library or ORM driver is not available for your programming language of choice, use the RPC API, which is built on gRPC. gRPC offers a number of performance benefits compared with using the REST API, including representing objects in protocol buffer format (which are faster to produce and consume compared with JSON) and persistent connections (which result in less per-request overhead). Read more about these and other benefits in gRPC Concepts.
- REST API: If you're unable to use Cloud Spanner's client libraries or the RPC API, use the REST API. Note that some features that are available in the RPC API are not supported in the REST API, as documented below.
RPC versus REST API
This table compares Cloud Spanner features available through its RPC and REST API interfaces.
| Feature | Supported in the RPC API? | Supported in the REST API? |
|---|---|---|
| Cancelling a request | Yes | No |
| Setting a deadline or timeout on a request | Yes | No |
| Sending a streaming request | Yes. see ExecuteStreamingSQL and StreamingRead. |
Partial. HTTP Streaming is supported but application-level flow control is not. |
Third-party ORM and framework support
The following table lists all the open-source Cloud Spanner ORM and framework drivers provided by Google, noting the major Cloud Spanner features that each one supports.
| Feature | JDBC | Hibernate | Spring Data | R2DBC* | Entity Framework | Active Record | SQLAlchemy |
|---|---|---|---|---|---|---|---|
| Language | Java | Java | Java | Java | C# | Ruby | Python |
| Statement hints | † | ||||||
| Mutations | |||||||
| Batch DML | |||||||
| Stale reads | |||||||
| Interleaved tables | |||||||
| Partitioned DML | |||||||
| Session labeling | |||||||
| Request priority | |||||||
| JSON type | |||||||
| Request tagging | |||||||
| Limitations | View | View | View | View |
* This column describes R2DBC when used specifically with Spring Data.
† Available only when sending literal SQL queries, through Spring Data's
@Query annotation.
Cloud Spanner also supports a Django-compatible ORM with limited features. See Current limitations.