Read lease

The page describes and explains how to use Spanner read leases. Read leases help your databases reduce read latency in non-leader regions for transactions that require strong consistency.

By default, when Spanner receives a strong read request in a non-leader region, the replica serving the read contacts the instance's leader read-write region. This contact confirms that its data is up-to-date before serving the request. This process incurs a network round trip between the region that receives the request and the leader region. Unlike communication within a single region, the geographic distance between regions adds additional latency to the request.

Using Spanner read leases eliminate the need for this round trip. When you set one or more read lease regions for your database, Spanner gives the right to serve reads locally to one or more non-leader, read-write, or read-only regions. This allows the non-leader regions to directly serve strong reads without communicating with the leader region. Serving strong reads from a non-leader region that is closer to the client reduces latency across regions. This achieves intra-region latency for strong reads in dual-region or multi-region instances.

Enabling or disabling the read leases feature on a region doesn't require downtime. However, writes experience higher latency when you use the feature, because enabling read lease requires the leader to contact read lease regions when serving writes. As a side effect, writes hold locks for longer, which can impact high-contention write workloads. For more information, see When to use read leases. Read lease is most suitable for applications that are willing to trade off increased write latency for faster strong reads. For example, an access control system where the workload has frequent reads but rare writes.

To learn how to enable read leases in a non-leader region, see Use read leases.

When to use read leases

Enable read leases if your application and workload meet the following criteria:

Low latency for strong reads is more important than low latency for writes.
Your workload can tolerate longer write lock durations, or has low write contention.

Enabling read leases increases write latency, which causes write locks to be held for longer. If your write workload already has high write contention, this feature can make write latency worse and reduce throughput.

When there are concurrent writes, the choice between using the query APIs or the read APIs affects the performance of a database that uses read lease regions.

Executing SQL statements in Spanner involves reading data from multiple rows or ranges. When using query APIs with read leases enabled, reads need to wait for concurrent writes for correctness. Consequently, you might observe higher latency, especially when there is more write load. Read APIs are generally more tolerant of concurrent writes than query APIs. If you frequently use query APIs with high write loads, consider reducing the frequency of writes or using stale reads instead.

Read APIs are optimized for reading specific rows or ranges of data. They only need to wait for writes that modify the exact data they're trying to read. If you're using read APIs, only writes on the exact same data ranges block your reads. As a result, when there are concurrent writes and you use read lease regions, Spanner strong reads perform better and have lower latency.

To learn more about monitoring latency, see Monitor.

Example use case

Consider a globally deployed application that performs writes in the US and has clients in the US, Europe, and Asia. You can configure a multi-region Spanner instance, such as nam-eur-asia1, with a leader region in us-central1 and read-only replicas in europe-west1 and asia-east1.

When you enable read lease in the europe-west1 and asia-east1 read-only regions, Spanner serves strong reads from Europe and Asia from those local replicas, reducing latency. The trade-off is an increase in write latency for all writes. The increased latency is equivalent to the round-trip time between the leader us-central1 region and the farthest read lease regions.

Limitations

Spanner read leases have the following limitations:

You can't enable read lease on a witness region.
You can't use read lease with geo-partitioning.
Read leases don't reduce latency for reads that are part of a read-write transaction. Even if a read-write transaction only contains reads, those reads are still served from the leader region.
If you move your instance to a different instance configuration, the read lease settings aren't preserved. You must re-enable read lease on the database after the move completes.

Use read leases

You must enable read leases before you can use it.

Access control with IAM

To set read lease regions, a user needs the spanner.databases.create or spanner.databases.updateDdl IAM permission. The predefined Database Admin role (roles/spanner.databaseAdmin) includes these permissions. For more information, see IAM overview for Spanner.

For information on how to grant permissions, see Apply IAM permissions.

Before you begin for PostgreSQL database users

If you want to use read lease in a PostgreSQL database, make one of the following configuration changes to your database. Otherwise, your reads are still served by the leader region even if you have set read lease regions.

If you only use read-only transactions, configure your PostgreSQL connection so that the default status of each new transaction in the database is set to read-only. To do so, set the default_transaction_read_only option to true.
```
postgres://USER_ID:PASSWORD@localhost:5432/DATABASE_ID?sslmode=disable&options=-c \
  default_transaction_read_only=true
host=/tmp port=5432 database=DATABASE_ID \
  options='-c default_transaction_read_only=true'
```
Replace the following:
- USER_ID with the unique identifier of your user.
- PASSWORD with your password.
- DATABASE_ID with the unique identifier of your database.

Enable read leases

To enable read leases when you create a new database, set the read_lease_regions option in the ALTER DATABASE (GoogleSQL, PostgreSQL) DDL statement:

Console

Go to the Instances page in the Google Cloud console.

Instances
Select the instance in which you want to enable read lease.
In the Instance overview page that opens, click Create database.
For the database name, enter a name.
Select a database dialect.
Click Create.

The Google Cloud console displays the Overview page for the database you created.
In the navigation menu, click Spanner Studio.
In the Spanner Studio page, click New tab or use the empty editor tab.
Enter the following ALTER DATABASE DDL statement.
GoogleSQL
```
ALTER DATABASE DATABASE_ID
SET OPTIONS (read_lease_regions = 'READ_LEASE_REGION');
```
Replace the following:
- DATABASE_ID with the unique identifier of your database.
- READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.
PostgreSQL
```
ALTER DATABASE DATABASE_ID
SET "spanner.read_lease_regions" = 'READ_LEASE_REGION';
```
Replace the following:
- DATABASE_ID with the unique identifier of your database.
- READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.
Click Run.

gcloud

To set the read_lease_regions database option when creating your database, use gcloud spanner databases create.

GoogleSQL

gcloud spanner databases create DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET OPTIONS (read_lease_regions = 'READ_LEASE_REGION');"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.
READ_LEASE_REGION: the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.

PostgreSQL

gcloud spanner databases create DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID \
    SET "spanner.read_lease_regions" = 'READ_LEASE_REGION';"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.
READ_LEASE_REGION: the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.

To enable read lease when you update an existing database, set the read_lease_regions option in the ALTER DATABASE (GoogleSQL, PostgreSQL) DDL statement:

Console

Go to the Instances page in the Google Cloud console.

Instances
Select the instance in which you want to enable read lease.
Select the database in which you want to enable read lease.
In the navigation menu, click Spanner Studio.
In the Spanner Studio page, click New tab or use the empty editor tab.
Enter the following ALTER DATABASE DDL statement.
GoogleSQL
```
ALTER DATABASE DATABASE_ID \
SET OPTIONS (read_lease_regions = 'READ_LEASE_REGION');
```
Replace the following:
- DATABASE_ID with the unique identifier of your database.
- READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.
PostgreSQL
```
ALTER DATABASE DATABASE_ID \
SET "spanner.read_lease_regions" = 'READ_LEASE_REGION';
```
Replace the following:
- DATABASE_ID with the unique identifier of your database.
- READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.
Click Run.

gcloud

To set the read_lease_regions database option, use gcloud spanner databases ddl update.

GoogleSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID \
    SET OPTIONS (read_lease_regions = 'READ_LEASE_REGION');"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.
READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.

PostgreSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID \
    SET "spanner.read_lease_regions" = 'READ_LEASE_REGION';"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.
READ_LEASE_REGION with the region where you want to enable read lease. For example, europe-west1. You can enable read lease for multiple regions. Separate each region with a comma.

Disable read leases

Read lease is disabled by default.

To update and disable the feature on an existing database, set the read_lease_regions option in the ALTER DATABASE (GoogleSQL, PostgreSQL) DDL statement to NULL:

Console

Go to the Instances page in the Google Cloud console.

Instances
Select the instance in which you want to disable read lease.
Select the database in which you want to disable read lease.
In the navigation menu, click Spanner Studio.
In the Spanner Studio page, click New tab or use the empty editor tab.
Enter the following ALTER DATABASE DDL statement.
GoogleSQL
```
ALTER DATABASE DATABASE_ID SET OPTIONS (read_lease_regions = NULL);
```
Replace DATABASE_ID with the unique identifier of your database.
PostgreSQL
```
ALTER DATABASE DATABASE_ID SET "spanner.read_lease_regions" = NULL;
```
Replace DATABASE_ID with the unique identifier of your database.
Click Run.

gcloud

To set the read_lease_regions database option, use gcloud spanner databases ddl update.

GoogleSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET OPTIONS (read_lease_regions = NULL);"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.

PostgreSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET "spanner.read_lease_regions" = NULL;"

Replace the following:

DATABASE_ID: the permanent identifier for your Spanner database.
INSTANCE_ID: the permanent identifier for your Spanner instance.

Best practices

To maximize the benefits of using this feature, use multiplexed sessions, which let you create a large number of concurrent requests on a single session.

Monitor

After enabling read lease, it's important to monitor latency to confirm that the feature achieves the intended effect. To do so, identify the leader region and the regions with read lease enabled by querying the data_options information schema table (GoogleSQL, PostgreSQL) or your database. Regions that have read lease enabled expect strong reads to have intra-region latency. Simultaneously, write latency increases between the leader region and the farthest region with read lease enabled.

You can also use the following Spanner latency metric to help you monitor read request latencies in your instances:

spanner.googleapis.com/api/read_request_latencies_by_serving_location

You can filter this metric using the /serving_location field. The /serving location field indicates the location of the Spanner server where the request is served from.

For a full list of available metrics, see metrics list for Spanner.

Cost considerations

Strong reads served from regions with the read lease feature enabled use slightly fewer compute resources. On the other hand, writes for databases with the read lease feature enabled use slightly more compute resources. For more information, see Spanner compute capacity pricing.

The feature doesn't impact other pricing components such as storage and network.

What's next

Learn more about Spanner replication.
Learn more about Reads outside of transactions.

Read lease Stay organized with collections Save and categorize content based on your preferences.

When to use read leases

Example use case

Limitations

Use read leases

Access control with IAM

Before you begin for PostgreSQL database users

Enable read leases

Console

GoogleSQL

PostgreSQL

gcloud

GoogleSQL

PostgreSQL

Console

GoogleSQL

PostgreSQL

gcloud

GoogleSQL

PostgreSQL

Disable read leases

Console

GoogleSQL

PostgreSQL

gcloud

GoogleSQL

PostgreSQL

Best practices

Monitor

Cost considerations

What's next

Read lease