Text of docs.cloud.google.com › spanner › docs › sessions as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Sessions | Spanner | Google Cloud Documentation

Skip to main content Console English Deutsch Español Español – América Latina Français Indonesia Italiano Português Português – Brasil עברית 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in Spanner Start free Home Documentation Databases Spanner Guides Sessions Stay organized with collections Save and categorize content based on your preferences. This page describes the advanced concept of sessions in Spanner, including best practices for sessions when creating a client library, using the REST or RPC APIs, or using the Google client libraries.

A session provides a context for database operations with the Spanner database service. A session is used to execute transactions that read, write, or modify data in a Spanner database. Each session applies to a single database. Sessions can execute a single or multiple transactions at a time. When performing multiple transactions, the session is called a multiplexed session . Standalone reads, writes, and queries use one transaction internally.

Manage session performance Sessions are the context for a database operation, so how you manage them directly affects your application's latency and resource usage. You can manage session performance in the following three ways: Use a session pool . Use multiplexed sessions . Optimize the gRPC channel configuration . Use a session pool Creating a session adds latency because each new session requires a round trip to the Spanner database service.

To reduce this latency, use a session pool : a collection of available sessions that are ready to use. Rather than creating a session for every operation, the pool returns an existing session and reclaims it for reuse afterward. This spreads the session-creation latency across many operations rather than eliminating it entirely. The pool stores existing sessions, returns the appropriate type of session when requested, and cleans up unused sessions.

Sessions are intended to be long-lived, so after a session is used for a database operation, the client should return the session to the pool for reuse. Use multiplexed sessions Multiplexed sessions let you make multiple concurrent requests on a single session, which reduces backend overhead and resource consumption. For more information, see Multiplexed sessions . Optimize the gRPC channel configuration Reduce high tail latency (p95/p99) caused by gRPC channel congestion during high traffic by tuning the gRPC channel pool.

In supported client libraries, dynamic channel pooling automatically resizes the channel pool as load changes. This helps reduce congestion-related tail latency and helps avoid under-provisioning or over-provisioning channels. Overview of gRPC channels gRPC channels are used by the Spanner client for communication. One gRPC channel is roughly equivalent to a TCP connection. One gRPC channel can handle up to 100 concurrent requests.

This means that an application will need at least as many gRPC channels as the number of concurrent requests the application will execute, divided by 100. The Spanner client creates a pool of gRPC channels when you create it. Best practices when using Google client libraries The following describes best practices when using the Google client libraries for Spanner. Configure the number of sessions and gRPC channels in the pools How you manage sessions and gRPC channels depends on the client library.

Client libraries that support multiplexed sessions, such as the Go and Java client libraries, don't require you to configure a session pool and can manage the gRPC channel pool for you through dynamic channel pooling. The other client libraries use a session pool with a default minimum and maximum number of sessions, and a default number of gRPC channels. The defaults are adequate for most cases. The following sections describe the defaults and configuration options for each programming language.

C++ MinSessions: 100 MaxSessions: 400 NumChannels: 4 C# MinSessions : 100 MaxSessions : 400 NumChannels : 4 Go Multiplexed sessions are enabled by default and require no configuration. Dynamic channel pooling is an opt-in feature. If you don't enable it, the client uses four gRPC channels. To use a different fixed number of gRPC channels, use the option.WithGRPCConnectionPool option when you create the client: // Use 16 gRPC channels instead of the default of four. client , err := spanner .

NewClient ( ctx , "projects/ PROJECT_ID /instances/ INSTANCE_ID /databases/ DATABASE_ID " , option . WithGRPCConnectionPool ( 16 ), ) This example requires the google.golang.org/api/option package. To enable dynamic channel pooling, set the DCPEnabled option to true in DynamicChannelPoolConfig : client , err := spanner . NewClientWithConfig ( ctx , "projects/ PROJECT_ID /instances/ INSTANCE_ID /databases/ DATABASE_ID " , spanner .

ClientConfig { DynamicChannelPoolConfig : spanner . DynamicChannelPoolConfig { DCPEnabled : true , }, }) When you enable dynamic channel pooling without setting custom options, the Go client library applies the following defaults: Initial pool size: 4 channels Minimum pool size: 2 channels Maximum pool size: 10 channels Scale-up threshold: 25 concurrent RPCs per channel Scale-down threshold: 15 concurrent RPCs per channel Scale-down check interval: 3 minutes To customize the pool, set the fields of the DynamicChannelPoolConfig struct, such as DCPInitialChannels , DCPMinChannels , DCPMaxChannels , DCPMaxRPCPerChannel , and DCPMinRPCPerChannel .

Java Multiplexed sessions are enabled by default in version 6.98.0 or later of the Java client library and require no configuration. For more information, see Multiplexed sessions . Dynamic channel pooling is disabled by default for the Java client library and must be enabled using SpannerOptions . If dynamic channel pooling isn't enabled, the Java client library uses 4 gRPC channels (8 channels when the gRPC-GCP extension is enabled).

When dynamic channel pooling is enabled, the client library resizes the gRPC channel pool to adapt to changing workloads, which helps prevent performance issues from under-provisioned or over-provisioned channels. To enable dynamic channel pooling, include enableDynamicChannelPool in SpannerOptions : SpannerOptions options = SpannerOptions . newBuilder () . setProjectId ( " PROJECT_ID " ) . enableDynamicChannelPool () . build (); If you configure the number of channels using setNumChannels , then Spanner disables dynamic channel pooling and uses a static number of channels.

When you enable dynamic channel pooling without setting custom options through setGcpChannelPoolOptions , the Java client library applies the following defaults, which are optimized for typical workloads: Initial pool size: 4 channels Minimum pool size: 2 channels Maximum pool size: 10 channels (hard cap: 256 channels) Scale-up threshold: 25 concurrent RPCs per channel Scale-down threshold: 15 concurrent RPCs per channel Scale-down interval: 3 minutes To customize dynamic channel pooling, use setGcpChannelPoolOptions .

For example: SpannerOptions options = SpannerOptions . newBuilder () . setProjectId ( " PROJECT_ID " ) . enableDynamicChannelPool () . setGcpChannelPoolOptions ( GcpChannelPoolOptions . newBuilder () . setMaxSize ( 15 ) . setMinSize ( 3 ) . setInitSize ( 5 ) // setDynamicScaling(minRpcPerChannel, maxRpcPerChannel, // scaleDownInterval): scale up as soon as a channel's load // exceeds 30 concurrent RPCs. Scale-up is event-driven, so // the pool grows immediately as load rises.

Scale-down is // periodic: a channel is removed only after it stays under // 10 concurrent RPCs across the check that runs every 5 // minutes. . setDynamicScaling ( 10 , 30 , Duration . ofMinutes ( 5 )) . build ()) . build (); Consider the following tradeoffs of dynamic channel pooling: Scaling overhead : Scaling the pool involves overhead from creating and destroying gRPC channels and TCP connections. For latency sensitive workloads with sharp bursts, a large static pool might be

The rest of this page is on the live site.