feat(spanner): add support for snapshot isolation

Author: alkatrivedi

src/database.ts

@@ -316,6 +316,10 @@ export interface RestoreOptions {
   gaxOptions?: CallOptions;
 }
 
+export interface WriteAtLeastOnceOptions extends CallOptions {
+  isolationLevel?: spannerClient.spanner.v1.TransactionOptions.IsolationLevel;
+}
+
 /**
  * Create a Database object to interact with a Cloud Spanner database.
  *
@@ -3252,6 +3256,9 @@ class Database extends common.GrpcServiceObject {
         ? (optionsOrRunFn as RunTransactionOptions)
         : {};
 
+    const defaultTransactionOptions =
+      this._getSpanner().defaultTransactionOptions;
+
     startTrace('Database.runTransaction', this._traceConfig, span => {
       this.pool_.getSession((err, session?, transaction?) => {
         if (err) {
@@ -3280,6 +3287,13 @@ class Database extends common.GrpcServiceObject {
         if (options.excludeTxnFromChangeStreams) {
           transaction!.excludeTxnFromChangeStreams();
         }
+        if (options.isolationLevel) {
+          transaction!.setIsolationLevel(options.isolationLevel);
+        } else if (defaultTransactionOptions) {
+          transaction!.setIsolationLevel(
+            defaultTransactionOptions.isolationLevel
+          );
+        }
 
         const release = () => {
           this.pool_.release(session!);
@@ -3390,6 +3404,9 @@ class Database extends common.GrpcServiceObject {
         ? (optionsOrRunFn as RunTransactionOptions)
         : {};
 
+    const defaultTransactionOptions =
+      this._getSpanner().defaultTransactionOptions;
+
     let sessionId = '';
     const getSession = this.pool_.getSession.bind(this.pool_);
     return startTrace(
@@ -3412,6 +3429,13 @@ class Database extends common.GrpcServiceObject {
             if (options.excludeTxnFromChangeStreams) {
               transaction.excludeTxnFromChangeStreams();
             }
+            if (options.isolationLevel) {
+              transaction!.setIsolationLevel(options.isolationLevel);
+            } else if (defaultTransactionOptions) {
+              transaction!.setIsolationLevel(
+                defaultTransactionOptions.isolationLevel
+              );
+            }
             sessionId = session?.id;
             span.addEvent('Using Session', {'session.id': sessionId});
             const runner = new AsyncTransactionRunner<T>(
@@ -3638,17 +3662,17 @@ class Database extends common.GrpcServiceObject {
   writeAtLeastOnce(mutations: MutationSet): Promise<CommitResponse>;
   writeAtLeastOnce(
     mutations: MutationSet,
-    options: CallOptions
+    options: WriteAtLeastOnceOptions
   ): Promise<CommitResponse>;
   writeAtLeastOnce(mutations: MutationSet, callback: CommitCallback): void;
   writeAtLeastOnce(
     mutations: MutationSet,
-    options: CallOptions,
+    options: WriteAtLeastOnceOptions,
     callback: CommitCallback
   ): void;
   writeAtLeastOnce(
     mutations: MutationSet,
-    optionsOrCallback?: CallOptions | CommitCallback,
+    optionsOrCallback?: WriteAtLeastOnceOptions | CommitCallback,
     callback?: CommitCallback
   ): void | Promise<CommitResponse> {
     const cb =
@@ -3657,9 +3681,12 @@ class Database extends common.GrpcServiceObject {
         : callback;
     const options =
       typeof optionsOrCallback === 'object' && optionsOrCallback
-        ? (optionsOrCallback as CallOptions)
+        ? (optionsOrCallback as WriteAtLeastOnceOptions)
         : {};
 
+    const defaultTransactionOptions =
+      this._getSpanner().defaultTransactionOptions;
+
     return startTrace('Database.writeAtLeastOnce', this._traceConfig, span => {
       this.sessionFactory_.getSession((err, session?, transaction?) => {
         if (
@@ -3683,6 +3710,13 @@ class Database extends common.GrpcServiceObject {
         span.addEvent('Using Session', {'session.id': session?.id});
         this._releaseOnEnd(session!, transaction!, span);
         try {
+          if (options.isolationLevel) {
+            transaction!.setIsolationLevel(options.isolationLevel);
+          } else if (defaultTransactionOptions) {
+            transaction!.setIsolationLevel(
+              defaultTransactionOptions.isolationLevel
+            );
+          }
           transaction?.setQueuedMutations(mutations.proto());
           return transaction?.commit(options, (err, resp) => {
             if (err) {

src/index.ts

@@ -145,6 +145,7 @@ export interface SpannerOptions extends GrpcClientOptions {
   sslCreds?: grpc.ChannelCredentials;
   routeToLeaderEnabled?: boolean;
   directedReadOptions?: google.spanner.v1.IDirectedReadOptions | null;
+  defaultTransactionOptions?: google.spanner.v1.ITransactionOptions | null;
   observabilityOptions?: ObservabilityOptions;
 }
 export interface RequestConfig {
@@ -247,6 +248,7 @@ class Spanner extends GrpcService {
   commonHeaders_: {[k: string]: string};
   routeToLeaderEnabled = true;
   directedReadOptions: google.spanner.v1.IDirectedReadOptions | null;
+  defaultTransactionOptions: google.spanner.v1.ITransactionOptions | null;
   _observabilityOptions: ObservabilityOptions | undefined;
 
   /**
@@ -331,6 +333,11 @@ class Spanner extends GrpcService {
       : null;
     delete options.directedReadOptions;
 
+    const defaultTransactionOptions = options.defaultTransactionOptions
+      ? options.defaultTransactionOptions
+      : null;
+    delete options.defaultTransactionOptions;
+
     const emulatorHost = Spanner.getSpannerEmulatorHost();
     if (
       emulatorHost &&
@@ -371,6 +378,7 @@ class Spanner extends GrpcService {
     this.projectIdReplaced_ = false;
     this.projectFormattedName_ = 'projects/' + this.projectId;
     this.directedReadOptions = directedReadOptions;
+    this.defaultTransactionOptions = defaultTransactionOptions;
     this._observabilityOptions = options.observabilityOptions;
     this.commonHeaders_ = getCommonHeaders(
       this.projectFormattedName_,

src/table.ts

@@ -37,6 +37,7 @@ import {
   setSpanError,
   traceConfig,
 } from './instrument';
+import {protos} from '.';
 
 export type Key = string | string[];
 
@@ -53,6 +54,7 @@ export type DropTableCallback = UpdateSchemaCallback;
 interface MutateRowsOptions extends CommitOptions {
   requestOptions?: Omit<IRequestOptions, 'requestTag'>;
   excludeTxnFromChangeStreams?: boolean;
+  isolationLevel?: protos.google.spanner.v1.TransactionOptions.IsolationLevel;
 }
 
 export type DeleteRowsCallback = CommitCallback;
@@ -1100,10 +1102,14 @@ class Table {
           ? options.excludeTxnFromChangeStreams
           : false;
 
+      const isolationLevel =
+        'isolationLevel' in options ? options.isolationLevel : undefined;
+
       this.database.runTransaction(
         {
           requestOptions: requestOptions,
           excludeTxnFromChangeStreams: excludeTxnFromChangeStreams,
+          isolationLevel: isolationLevel,
         },
         (err, transaction) => {
           if (err) {

src/transaction-runner.ts

@@ -26,6 +26,7 @@ import {isSessionNotFoundError} from './session-pool';
 import {Database} from './database';
 import {google} from '../protos/protos';
 import IRequestOptions = google.spanner.v1.IRequestOptions;
+import {protos} from '.';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const jsonProtos = require('../protos/protos.json');
@@ -46,6 +47,7 @@ export interface RunTransactionOptions {
   requestOptions?: Pick<IRequestOptions, 'transactionTag'>;
   optimisticLock?: boolean;
   excludeTxnFromChangeStreams?: boolean;
+  isolationLevel?: protos.google.spanner.v1.TransactionOptions.IsolationLevel;
 }
 
 /**

src/transaction.ts

@@ -2697,6 +2697,13 @@ export class Transaction extends Dml {
   excludeTxnFromChangeStreams(): void {
     this._options.excludeTxnFromChangeStreams = true;
   }
+
+  /**
+   * Use option isolationLevel to add the isolation level in the transaction.
+   */
+  setIsolationLevel(isolationLevel: any): void {
+    this._options.isolationLevel = isolationLevel;
+  }
 }
 
 /*! Developer Documentation

test/database.ts

@@ -177,6 +177,9 @@ class FakeTransaction extends EventEmitter {
   setQueuedMutations(mutation) {
     this._queuedMutations = mutation;
   }
+  setIsolationLevel(isolationLevel) {
+    this._options.isolationLevel = isolationLevel;
+  }
   commit(
     options?: CommitOptions,
     callback?: CommitCallback
@@ -3166,6 +3169,19 @@ describe('Database', () => {
       assert.strictEqual(options, fakeOptions);
     });
 
+    it('should optionally accept runner `option` isolationLevel', async () => {
+      const fakeOptions = {
+        isolationLevel:
+          protos.google.spanner.v1.TransactionOptions.IsolationLevel
+            .REPEATABLE_READ,
+      };
+
+      await database.runTransaction(fakeOptions, assert.ifError);
+
+      const options = fakeTransactionRunner.calledWith_[3];
+      assert.strictEqual(options, fakeOptions);
+    });
+
     it('should release the session when finished', done => {
       const releaseStub = (
         sandbox.stub(pool, 'release') as sinon.SinonStub
@@ -3237,6 +3253,19 @@ describe('Database', () => {
       assert.strictEqual(options, fakeOptions);
     });
 
+    it('should optionally accept runner `option` isolationLevel', async () => {
+      const fakeOptions = {
+        isolationLevel:
+          protos.google.spanner.v1.TransactionOptions.IsolationLevel
+            .REPEATABLE_READ,
+      };
+
+      await database.runTransactionAsync(fakeOptions, assert.ifError);
+
+      const options = fakeAsyncTransactionRunner.calledWith_[3];
+      assert.strictEqual(options, fakeOptions);
+    });
+
     it('should return the runners resolved value', async () => {
       const fakeValue = {};
 

test/index.ts

@@ -327,6 +327,22 @@ describe('Spanner', () => {
       assert.strictEqual(spanner.directedReadOptions, fakeDirectedReadOptions);
     });
 
+    it('should optionally accept defaultTransactionOptions', () => {
+      const fakeDefaultTxnOptions = {
+        isolationLevel:
+          protos.google.spanner.v1.TransactionOptions.IsolationLevel
+            .REPEATABLE_READ,
+      };
+
+      const spanner = new Spanner({
+        defaultTransactionOptions: fakeDefaultTxnOptions,
+      });
+      assert.strictEqual(
+        spanner.defaultTransactionOptions,
+        fakeDefaultTxnOptions
+      );
+    });
+
     it('should set projectFormattedName_', () => {
       assert.strictEqual(
         spanner.projectFormattedName_,

test/spanner.ts

@@ -23,6 +23,7 @@ import {
   Database,
   Instance,
   MutationSet,
+  protos,
   SessionPool,
   Snapshot,
   Spanner,
@@ -3575,6 +3576,33 @@ describe('Spanner with mock server', () => {
       assert.strictEqual(commitRequest.mutations.length, 2);
     });
 
+    it('should apply blind writes only once with isolationLevel option', async () => {
+      const database = newTestDatabase();
+      const mutations = new MutationSet();
+      mutations.upsert('Singers', {
+        SingerId: 1,
+        FirstName: 'Marc',
+        LastName: 'Terry',
+      });
+      mutations.upsert('Singers', {
+        SingerId: 2,
+        FirstName: 'Scarlet',
+      });
+      await database.writeAtLeastOnce(mutations, {
+        isolationLevel:
+          protos.google.spanner.v1.TransactionOptions.IsolationLevel
+            .REPEATABLE_READ,
+      });
+      await database.close();
+      const request = spannerMock.getRequests().find(val => {
+        return (val as v1.CommitRequest).singleUseTransaction?.isolationLevel;
+      }) as v1.CommitRequest;
+      assert.strictEqual(
+        request.singleUseTransaction?.isolationLevel,
+        'REPEATABLE_READ'
+      );
+    });
+
     it('should apply blind writes only once with excludeTxnFromChangeStreams option', async () => {
       const database = newTestDatabase();
       await database.runTransactionAsync(