fix(spanner): client-level read lock mode setting (#9084)

skuruppu · web-flow · commit e21a5b5e3796 · 2026-04-09T14:16:54.000-04:00
Allows the read lock mode to be set at the client-level. The existing
support to set the read lock mode at a transaction level can be used to
override the client-level setting at a per-transaction level.

Also adds unit tests for setting the isolation level at the client level
and being able to override it at the transaction level.
diff --git a/Spanner/src/Database.php b/Spanner/src/Database.php
@@ -55,6 +55,7 @@
 use Google\Cloud\Spanner\V1\Mutation\Delete;
 use Google\Cloud\Spanner\V1\Mutation\Write;
 use Google\Cloud\Spanner\V1\TransactionOptions\IsolationLevel;
+use Google\Cloud\Spanner\V1\TransactionOptions\ReadWrite\ReadLockMode;
 use Google\Cloud\Spanner\V1\TypeCode;
 use Google\LongRunning\ListOperationsRequest;
 use Google\LongRunning\Operation as OperationProto;
@@ -128,6 +129,7 @@ class Database
     private CacheItemPoolInterface $cacheItemPool;
     private array $info;
     private int $isolationLevel;
+    private int $readLockMode;
     private TransactionOptionsBuilder $transactionOptionsBuilder;
 
     /**
@@ -175,6 +177,7 @@ public function __construct(
         $this->returnInt64AsObject = $options['returnInt64AsObject'] ?? false;
         $this->info = $options['database'] ?? [];
         $this->isolationLevel = $options['isolationLevel'] ?? IsolationLevel::ISOLATION_LEVEL_UNSPECIFIED;
+        $this->readLockMode = $options['readLockMode'] ?? ReadLockMode::READ_LOCK_MODE_UNSPECIFIED;
         $this->operation = new Operation(
             $this->spannerClient,
             $serializer,
@@ -807,7 +810,8 @@ public function transaction(array $options = []): Transaction
         $txnOptions = $options['transactionOptions'] ?? [];
         $options['transactionOptions'] = $this->transactionOptionsBuilder
             ->configureReadWriteTransactionOptions($txnOptions + [
-                'isolationLevel' => $this->isolationLevel
+                'isolationLevel' => $this->isolationLevel,
+                'readLockMode' => $this->readLockMode
             ]);
 
         return $this->operation->transaction($this->session, $options);
@@ -915,7 +919,8 @@ public function runTransaction(callable $operation, array $options = []): mixed
         $txnOptions = $options['transactionOptions'] ?? [];
         $options['transactionOptions'] = $this->transactionOptionsBuilder
             ->configureReadWriteTransactionOptions($txnOptions + [
-                'isolationLevel' => $this->isolationLevel
+                'isolationLevel' => $this->isolationLevel,
+                'readLockMode' => $this->readLockMode
             ]);
 
         $attempt = 0;
diff --git a/Spanner/src/Instance.php b/Spanner/src/Instance.php
@@ -44,6 +44,7 @@
 use Google\Cloud\Spanner\Session\SessionCache;
 use Google\Cloud\Spanner\V1\Client\SpannerClient as GapicSpannerClient;
 use Google\Cloud\Spanner\V1\TransactionOptions\IsolationLevel;
+use Google\Cloud\Spanner\V1\TransactionOptions\ReadWrite\ReadLockMode;
 use Google\LongRunning\ListOperationsRequest;
 use Google\LongRunning\Operation as OperationProto;
 use InvalidArgumentException;
@@ -79,6 +80,7 @@ class Instance
     private bool $returnInt64AsObject;
     private array $info;
     private int $isolationLevel;
+    private int $readLockMode;
     private CacheItemPoolInterface|null $cacheItemPool;
 
     /**
@@ -122,6 +124,7 @@ public function __construct(
         $this->name = $this->fullyQualifiedInstanceName($name);
         $this->directedReadOptions = $options['directedReadOptions'] ?? [];
         $this->isolationLevel = $options['isolationLevel'] ?? IsolationLevel::ISOLATION_LEVEL_UNSPECIFIED;
+        $this->readLockMode = $options['readLockMode'] ?? ReadLockMode::READ_LOCK_MODE_UNSPECIFIED;
         $this->routeToLeader = $options['routeToLeader'] ?? true;
         $this->defaultQueryOptions = $options['defaultQueryOptions'] ?? [];
         $this->returnInt64AsObject = $options['returnInt64AsObject'] ?? false;
@@ -571,6 +574,7 @@ public function database(string $name, array $options = []): Database
                 'defaultQueryOptions' => $this->defaultQueryOptions,
                 'returnInt64AsObject' => $this->returnInt64AsObject,
                 'isolationLevel' => $this->isolationLevel,
+                'readLockMode' => $this->readLockMode,
             ]
         );
     }
diff --git a/Spanner/src/SpannerClient.php b/Spanner/src/SpannerClient.php
@@ -42,6 +42,7 @@
 use Google\Cloud\Spanner\Middleware\SpannerMiddleware;
 use Google\Cloud\Spanner\V1\Client\SpannerClient as GapicSpannerClient;
 use Google\Cloud\Spanner\V1\TransactionOptions\IsolationLevel;
+use Google\Cloud\Spanner\V1\TransactionOptions\ReadWrite\ReadLockMode;
 use Google\LongRunning\Operation as OperationProto;
 use Google\Protobuf\Duration;
 use Psr\Cache\CacheItemPoolInterface;
@@ -130,6 +131,7 @@ class SpannerClient
     private bool $routeToLeader;
     private array $defaultQueryOptions;
     private int $isolationLevel;
+    private int $readLockMode;
     private CacheItemPoolInterface|null $cacheItemPool;
     private static array $activeChannels = [];
     private static int $totalActiveChannels = 0;
@@ -202,6 +204,7 @@ public function __construct(array $options = [])
             'queryOptions' => [],
             'directedReadOptions' => [],
             'isolationLevel' => IsolationLevel::ISOLATION_LEVEL_UNSPECIFIED,
+            'readLockMode' => ReadLockMode::READ_LOCK_MODE_UNSPECIFIED,
             'routeToLeader' => true,
             'cacheItemPool' => null
         ];
@@ -211,6 +214,7 @@ public function __construct(array $options = [])
         $this->routeToLeader = $options['routeToLeader'];
         $this->defaultQueryOptions = $options['queryOptions'];
         $this->isolationLevel = $options['isolationLevel'];
+        $this->readLockMode = $options['readLockMode'];
 
         $options = $this->configureKeepAlive($options);
 
@@ -589,6 +593,7 @@ public function instance(string $name, array $instance = []): Instance
                 'defaultQueryOptions' => $this->defaultQueryOptions,
                 'returnInt64AsObject' => $this->returnInt64AsObject,
                 'isolationLevel' => $this->isolationLevel,
+                'readLockMode' => $this->readLockMode,
                 'cacheItemPool' => $this->cacheItemPool,
                 'instance' => $instance,
             ],
diff --git a/Spanner/tests/Unit/DatabaseTest.php b/Spanner/tests/Unit/DatabaseTest.php
@@ -2378,6 +2378,99 @@ function (Transaction $t) use ($sql) {
         );
     }
 
+    public function testRunTransactionWithClientLevelIsolationLevel()
+    {
+        $sql = 'SELECT example FROM sql_query';
+        $stream = $this->prophesize(ServerStream::class);
+        $stream->readAll()
+            ->shouldBeCalledOnce()
+            ->willReturn([new ResultSet(['stats' => new ResultSetStats(['row_count_exact' => 0])])]);
+
+        $this->spannerClient->executeStreamingSql(
+            Argument::that(function (ExecuteSqlRequest $request) {
+                $txnOptions = $request->getTransaction()->getBegin();
+                $this->assertNotNull($txnOptions);
+                $this->assertEquals(IsolationLevel::SERIALIZABLE, $txnOptions->getIsolationLevel());
+                return true;
+            }),
+            Argument::type('array')
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($stream->reveal());
+
+        $session = $this->prophesize(SessionCache::class);
+        $session->name()->willReturn($this->sessionName);
+
+        $database = new Database(
+            $this->spannerClient->reveal(),
+            $this->databaseAdminClient->reveal(),
+            $this->serializer,
+            $this->instance,
+            self::PROJECT,
+            self::DATABASE,
+            $session->reveal(),
+            ['isolationLevel' => IsolationLevel::SERIALIZABLE]
+        );
+
+        $database->runTransaction(
+            function (Transaction $t) use ($sql) {
+                // Run a fake query
+                $t->executeUpdate($sql);
+
+                // Simulate calling Transaction::commmit()
+                $prop = new \ReflectionProperty($t, 'state');
+                $prop->setValue($t, Transaction::STATE_COMMITTED);
+            }
+        );
+    }
+
+    public function testRunTransactionWithClientLevelIsolationLevelOverride()
+    {
+        $sql = 'SELECT example FROM sql_query';
+        $stream = $this->prophesize(ServerStream::class);
+        $stream->readAll()
+            ->shouldBeCalledOnce()
+            ->willReturn([new ResultSet(['stats' => new ResultSetStats(['row_count_exact' => 0])])]);
+
+        $this->spannerClient->executeStreamingSql(
+            Argument::that(function (ExecuteSqlRequest $request) {
+                $txnOptions = $request->getTransaction()->getBegin();
+                $this->assertNotNull($txnOptions);
+                $this->assertEquals(IsolationLevel::REPEATABLE_READ, $txnOptions->getIsolationLevel());
+                return true;
+            }),
+            Argument::type('array')
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($stream->reveal());
+
+        $session = $this->prophesize(SessionCache::class);
+        $session->name()->willReturn($this->sessionName);
+
+        $database = new Database(
+            $this->spannerClient->reveal(),
+            $this->databaseAdminClient->reveal(),
+            $this->serializer,
+            $this->instance,
+            self::PROJECT,
+            self::DATABASE,
+            $session->reveal(),
+            ['isolationLevel' => IsolationLevel::SERIALIZABLE]
+        );
+
+        $database->runTransaction(
+            function (Transaction $t) use ($sql) {
+                // Run a fake query
+                $t->executeUpdate($sql);
+
+                // Simulate calling Transaction::commmit()
+                $prop = new \ReflectionProperty($t, 'state');
+                $prop->setValue($t, Transaction::STATE_COMMITTED);
+            },
+            ['transactionOptions' => ['isolationLevel' => IsolationLevel::REPEATABLE_READ]]
+        );
+    }
+
     public function testRunTransactionWithReadLockMode()
     {
         $sql = 'SELECT example FROM sql_query';
@@ -2415,6 +2508,101 @@ function (Transaction $t) use ($sql) {
         );
     }
 
+    public function testRunTransactionWithClientLevelReadLockMode()
+    {
+        $sql = 'SELECT example FROM sql_query';
+        $stream = $this->prophesize(ServerStream::class);
+        $stream->readAll()
+            ->shouldBeCalledOnce()
+            ->willReturn([new ResultSet(['stats' => new ResultSetStats(['row_count_exact' => 0])])]);
+
+        $this->spannerClient->executeStreamingSql(
+            Argument::that(function (ExecuteSqlRequest $request) {
+                $txnOptions = $request->getTransaction()->getBegin();
+                $this->assertNotNull($txnOptions);
+                $this->assertNotNull($readWriteTxnOptions = $txnOptions->getReadWrite());
+                $this->assertEquals(ReadLockMode::PESSIMISTIC, $readWriteTxnOptions->getReadLockMode());
+                return true;
+            }),
+            Argument::type('array')
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($stream->reveal());
+
+        $session = $this->prophesize(SessionCache::class);
+        $session->name()->willReturn($this->sessionName);
+
+        $database = new Database(
+            $this->spannerClient->reveal(),
+            $this->databaseAdminClient->reveal(),
+            $this->serializer,
+            $this->instance,
+            self::PROJECT,
+            self::DATABASE,
+            $session->reveal(),
+            ['readLockMode' => ReadLockMode::PESSIMISTIC]
+        );
+
+        $database->runTransaction(
+            function (Transaction $t) use ($sql) {
+                // Run a fake query
+                $t->executeUpdate($sql);
+
+                // Simulate calling Transaction::commmit()
+                $prop = new \ReflectionProperty($t, 'state');
+                $prop->setValue($t, Transaction::STATE_COMMITTED);
+            }
+        );
+    }
+
+    public function testRunTransactionWithClientLevelReadLockModeOverride()
+    {
+        $sql = 'SELECT example FROM sql_query';
+        $stream = $this->prophesize(ServerStream::class);
+        $stream->readAll()
+            ->shouldBeCalledOnce()
+            ->willReturn([new ResultSet(['stats' => new ResultSetStats(['row_count_exact' => 0])])]);
+
+        $this->spannerClient->executeStreamingSql(
+            Argument::that(function (ExecuteSqlRequest $request) {
+                $txnOptions = $request->getTransaction()->getBegin();
+                $this->assertNotNull($txnOptions);
+                $this->assertNotNull($readWriteTxnOptions = $txnOptions->getReadWrite());
+                $this->assertEquals(ReadLockMode::OPTIMISTIC, $readWriteTxnOptions->getReadLockMode());
+                return true;
+            }),
+            Argument::type('array')
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($stream->reveal());
+
+        $session = $this->prophesize(SessionCache::class);
+        $session->name()->willReturn($this->sessionName);
+
+        $database = new Database(
+            $this->spannerClient->reveal(),
+            $this->databaseAdminClient->reveal(),
+            $this->serializer,
+            $this->instance,
+            self::PROJECT,
+            self::DATABASE,
+            $session->reveal(),
+            ['readLockMode' => ReadLockMode::PESSIMISTIC]
+        );
+
+        $database->runTransaction(
+            function (Transaction $t) use ($sql) {
+                // Run a fake query
+                $t->executeUpdate($sql);
+
+                // Simulate calling Transaction::commmit()
+                $prop = new \ReflectionProperty($t, 'state');
+                $prop->setValue($t, Transaction::STATE_COMMITTED);
+            },
+            ['transactionOptions' => ['readLockMode' => ReadLockMode::OPTIMISTIC]]
+        );
+    }
+
     public function testTransactionWithReadLockMode()
     {
         $this->spannerClient->beginTransaction(
diff --git a/Spanner/tests/Unit/SpannerClientTest.php b/Spanner/tests/Unit/SpannerClientTest.php
