# Google Cloud Spanner v1 API - Class PooledSession (5.13.0-beta07)

5.13.0-beta07 5.13.0-beta06 5.12.0 (latest) 5.11.0 5.10.0 5.9.0 5.8.0 5.7.0 5.6.0 5.5.0 5.4.0 5.3.0 5.2.0 5.1.0 5.0.0 4.6.0 4.5.0 4.4.0 4.3.0 4.2.0 4.1.0 4.0.0 3.15.1 3.14.0 3.13.0 3.12.0 3.11.0 3.10.0 3.9.0 3.8.0 3.7.0 3.6.0 3.5.0

    public sealed class PooledSession : IDisposable

Reference documentation and code samples for the Google Cloud Spanner v1 API class PooledSession.

A session from a [SessionPool](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SessionPool), with an associated transaction if
requested. Instances must be released back to the pool via [ReleaseToPool(bool)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_ReleaseToPool_System_Boolean_).

## Inheritance

[object](https://learn.microsoft.com/dotnet/api/system.object) \> PooledSession

## Implements

[IDisposable](https://learn.microsoft.com/dotnet/api/system.idisposable)

## Inherited Members

[object.GetHashCode()](https://learn.microsoft.com/dotnet/api/system.object.gethashcode) [object.GetType()](https://learn.microsoft.com/dotnet/api/system.object.gettype) [object.ToString()](https://learn.microsoft.com/dotnet/api/system.object.tostring)

## Namespace

[Google.Cloud.Spanner.V1](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1)

## Assembly

Google.Cloud.Spanner.V1.dll

## Remarks


Each method in this class modifies requests passed as arguments to RPC methods, to populate
the session and transaction properties.


This class keeps track of successful RPCs to update its internal refresh timer. This can't
be applied for streaming SQL calls, as [ReliableStreamReader](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader) performs the actual
RPCs in that case.

## Properties

### IsDetached

    public bool IsDetached { get; }

Whether this session is detached from the session pool or not.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.boolean` |   |

**Remarks** Detached sessions are used for transactional operations performed across several processes,
for instance, partitioned reads. See the [ReleaseToPool(bool)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_ReleaseToPool_System_Boolean_) documentation for
information on how to release resources of a detached session gracefully.

### ReadTimestamp

    public Timestamp ReadTimestamp { get; }

The read timestamp of the transaction. May be null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://cloud.google.com/dotnet/docs/reference/Google.Protobuf/latest/Google.Protobuf.WellKnownTypes.Timestamp.html` |   |

**Remarks** Will be set iif a transaction has been started and [TransactionOptions](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.TransactionOptions) represents read-only options
with [ReturnReadTimestamp](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.TransactionOptions.Types.ReadOnly#Google_Cloud_Spanner_V1_TransactionOptions_Types_ReadOnly_ReturnReadTimestamp) set to true
or if this session was created using [CreateDetachedSession(SessionName, ByteString, ModeOneofCase, Timestamp)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SessionPool#Google_Cloud_Spanner_V1_SessionPool_CreateDetachedSession_Google_Cloud_Spanner_V1_SessionName_Google_Protobuf_ByteString_Google_Cloud_Spanner_V1_TransactionOptions_ModeOneofCase_Google_Protobuf_WellKnownTypes_Timestamp_)
and a value was provided for the [Timestamp](https://cloud.google.com/dotnet/docs/reference/Google.Protobuf/latest/Google.Protobuf.WellKnownTypes.Timestamp.html) parameter.

### SessionName

    public SessionName SessionName { get; }

The name of the session. This is never null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SessionName` |   |

### TransactionId

    public ByteString TransactionId { get; }

The ID of the transaction. May be null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://cloud.google.com/dotnet/docs/reference/Google.Protobuf/latest/Google.Protobuf.ByteString.html` |   |

**Remarks** Transactions are acquired when they are needed so this will be null in the
following cases:

- [TransactionOptions](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.TransactionOptions) is [None](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.TransactionOptions.ModeOneofCase#Google_Cloud_Spanner_V1_TransactionOptions_ModeOneofCase_None), including when the session is idle in the pool.
- This is a single use transaction. No transactions will exist client side.
- The session has been acquired from the pool with some transaction options but no command execution has been attempted since.
- The first command execution is underway and the transaction is being created either by inlining or explicitly.

## Methods

### CommitAsync(CommitRequest, CallSettings)

    public Task<CommitResponse> CommitAsync(CommitRequest request, CallSettings callSettings)

Executes a Commit RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.CommitRequest` The commit request. Must not be null. The request will be modified with session and transaction details from this object. |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.CommitResponse` | A task representing the asynchronous operation. When the task completes, the result is the response from the RPC. |

### Dispose()

    public void Dispose()

Releases this session back to the session pool. This method should only be called once per instance; subsequent
calls are ignored. No other methods can be called after this.
**Remarks** This method is equivalent to calling [ReleaseToPool(bool)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_ReleaseToPool_System_Boolean_) with an argument of `false`.

### ExecuteBatchDmlAsync(ExecuteBatchDmlRequest, CallSettings)

    public Task<ExecuteBatchDmlResponse> ExecuteBatchDmlAsync(ExecuteBatchDmlRequest request, CallSettings callSettings)

Executes an ExecuteBatchDml RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ExecuteBatchDmlRequest` The query request. Must not be null. The request will be modified with session and transaction details from this object. If this object's [TransactionId](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_TransactionId) is null, the request's transaction is not modified. |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ExecuteBatchDmlResponse` | A task representing the asynchronous operation. When the task completes, the result is the response from the RPC. |

### ExecuteSqlAsync(ExecuteSqlRequest, CallSettings)

    public Task<ResultSet> ExecuteSqlAsync(ExecuteSqlRequest request, CallSettings callSettings)

Executes an ExecuteSql RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ExecuteSqlRequest` The query request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying [SpannerClient](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SpannerClient). |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ResultSet` | A task representing the asynchronous operation. When the task completes, the result is the response from the RPC. |

### ExecuteSqlStreamReader(ExecuteSqlRequest, CallSettings)

    public ReliableStreamReader ExecuteSqlStreamReader(ExecuteSqlRequest request, CallSettings callSettings)

Creates a [ReliableStreamReader](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader) for the given request.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ExecuteSqlRequest` The query request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying [SpannerClient](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SpannerClient). |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader` | A [ReliableStreamReader](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader) for the streaming SQL request. |

### PartitionQueryAsync(PartitionQueryRequest, CallSettings)

    public Task<PartitionResponse> PartitionQueryAsync(PartitionQueryRequest request, CallSettings callSettings)

Executes a PartitionQuery RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PartitionQueryRequest` The partitioning request. Must not be null. The request will be modified with session details from this object. |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PartitionResponse` | A task representing the asynchronous operation. When the task completes, the result is the response from the RPC. |

### PartitionReadAsync(PartitionReadRequest, CallSettings)

    public Task<PartitionResponse> PartitionReadAsync(PartitionReadRequest request, CallSettings callSettings)

Executes a PartitionRead RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PartitionReadRequest` The partitioning request. Must not be null. The request will be modified with session details from this object. |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PartitionResponse` | A task representing the asynchronous operation. When the task completes, the result is the response from the RPC. |

### ReadStreamReader(ReadRequest, CallSettings)

    public ReliableStreamReader ReadStreamReader(ReadRequest request, CallSettings callSettings)

Creates a [ReliableStreamReader](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader) for the given request.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReadRequest` The read request. Must not be null. Will be modified to include session information from this pooled session. May be modified to include transaction and directed read options information from this pooled session and its underlying [SpannerClient](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.SpannerClient). |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader` | A [ReliableStreamReader](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.ReliableStreamReader) for the streaming SQL request. |

### RefreshedOrNewAsync(CancellationToken)

    public Task<PooledSession> RefreshedOrNewAsync(CancellationToken cancellationToken)

Always returns a new instance of [PooledSession](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession). The new instance can:

1. represent the same session as this one, with the same transaction options, but it won't have a transaction associated to it
2. represent an entirely different session with the same transaction options as this [PooledSession](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession) did and no transaction associated to it If this session has expired then this method will acquire a new session in the normal way. This [PooledSession](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession) instance will be disposed of to ensure that all operations with the underlying session are done through the new instance.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession` |   |

**Remarks** Use this method when executing operations that are best done using the same
session. For instance, when retrying aborted commits it is better if the transaction work and commit
are retried with the same session, because after each abort the sessions' lock priority increments.

### ReleaseToPool(bool)

    public void ReleaseToPool(bool forceDelete)

Returns this session to the session pool from which it was acquired, unless this is a detached session
or it has become invalid. This method should only be called once per instance; subsequent
calls are ignored. No other methods can be called after this.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `forceDelete` | `https://learn.microsoft.com/dotnet/api/system.boolean` true to force the session to be deleted; false to allow the session to be reused. |

**Remarks** If [IsDetached](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_IsDetached) is true, the session won't be returned to the pool because its underlying
resources may be being used by other processes. The last process to use this session's underlying resources should
call [ReleaseToPool(bool)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.PooledSession#Google_Cloud_Spanner_V1_PooledSession_ReleaseToPool_System_Boolean_) with `forceDelete` set to true, so that the session resources
are gracefully freed.

### RollbackAsync(RollbackRequest, CallSettings)

    public Task RollbackAsync(RollbackRequest request, CallSettings callSettings)

Executes a Rollback RPC asynchronously.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.V1/latest/Google.Cloud.Spanner.V1.RollbackRequest` The rollback request. Must not be null. The request will be modified with session and transaction details from this object. |
| `callSettings` | `https://cloud.google.com/dotnet/docs/reference/Google.Api.Gax/latest/Google.Api.Gax.Grpc.CallSettings.html` If not null, applies overrides to this RPC call. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task` | A task representing the asynchronous operation. |