Class Transaction (5.15.2)

This type of transaction is the only way to write data into Cloud Spanner. These transactions rely on pessimistic locking and, if necessary, two-phase commit. Locking read-write transactions may abort, requiring the application to retry.

Calling either or signals that the transaction is finished and no further requests will be made. If for some reason you decide not to call one of the aformentioned methods, call to release the underlying Session.

Running a transaction via or automatically re-runs the transaction on ABORTED errors.

returns a plain Transaction object, requiring the user to retry manually.

Snapshot

Inheritance

Dml > Transaction

Package

@google-cloud/spanner

Examples


const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

database.runTransaction(function(err, transaction) {
  // The `transaction` object is ready for use.
});

To manually control retrying the transaction, use the getTransaction method.


database.getTransaction(function(err, transaction) {
  // The `transaction` object is ready for use.
});

Constructors

(constructor)(session, options, queryOptions, requestOptions)

constructor(session: Session, options?: spannerClient.spanner.v1.TransactionOptions.ReadWrite, queryOptions?: IQueryOptions, requestOptions?: Pick<IRequestOptions, 'transactionTag'>);

Execute a DML statement and get the affected row count.

Transaction#runUpdate

Parameters
Name Description
session Session
options google.spanner.v1.TransactionOptions.ReadWrite
queryOptions IQueryOptions
requestOptions Pick<google.spanner.v1.IRequestOptions, 'transactionTag'>
Example 

const query = 'UPDATE Account SET Balance = 1000 WHERE Key = 1';

transaction.runUpdate(query, (err, rowCount) => {
  if (err) {
    // Error handling omitted.
  }
});

Properties

commitTimestamp

commitTimestamp?: PreciseDate;

commitTimestampProto

commitTimestampProto?: spannerClient.protobuf.ITimestamp;

Methods

batchUpdate(queries, options)

batchUpdate(queries: Array<string | Statement>, options?: BatchUpdateOptions | CallOptions): Promise<BatchUpdateResponse>;

Execute a series of DML statements and get the affected row counts.

If any of the DML statements fail, the returned error will contain a list of results for all successfully executed statements.

Parameters
Name Description
queries Array<string | Statement>
options BatchUpdateOptions | CallOptions

Options for configuring the request.
Returns
Type Description
Promise<BatchUpdateResponse>

{Promise
Examples 

const queries = [
  {
    sql: 'INSERT INTO MyTable (Key, Value) VALUES (@key, @value)',
    params: {key: 'my-key', value: 'my-value'},
  },
  {
    sql: 'UPDATE MyTable t SET t.Value = @value WHERE t.KEY = @key',
    params: {key: 'my-other-key', value: 'my-other-value'}
  }
];

transaction.batchUpdate(queries, (err, rowCounts, apiResponse) => {
  if (err) {
    // Error handling omitted.
  }
});

If the callback is omitted, we'll return a Promise.


const [rowCounts, apiResponse] = await transaction.batchUpdate(queries);

batchUpdate(queries, callback)

batchUpdate(queries: Array<string | Statement>, callback: BatchUpdateCallback): void;
Parameters
Name Description
queries Array<string | Statement>
callback BatchUpdateCallback
Returns
Type Description
void

batchUpdate(queries, options, callback)

batchUpdate(queries: Array<string | Statement>, options: BatchUpdateOptions | CallOptions, callback: BatchUpdateCallback): void;
Parameters
Name Description
queries Array<string | Statement>
options BatchUpdateOptions | CallOptions
callback BatchUpdateCallback
Returns
Type Description
void

commit(options)

commit(options?: CommitOptions | CallOptions): Promise<CommitResponse>;

Commit the transaction.

Wrapper around .

Parameter
Name Description
options CommitOptions | CallOptions

Options for configuring the request.
Returns
Type Description
Promise<CommitResponse>

{Promise
Example 

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue a mutation (note that there is no callback passed to `insert`).
  transaction.insert('Singers', {
    SingerId: 'Id3b',
    Name: 'Joe West'
  });

  // Commit the transaction.
  transaction.commit(function(err, apiResponse) {
    if (!err) {
      // Get the commit timestamp on successful commits.
      const {commitTimestamp} = apiResponse;
    }
  });
});

commit(callback)

commit(callback: CommitCallback): void;
Parameter
Name Description
callback CommitCallback
Returns
Type Description
void

commit(options, callback)

commit(options: CommitOptions | CallOptions, callback: CommitCallback): void;
Parameters
Name Description
options CommitOptions | CallOptions
callback CommitCallback
Returns
Type Description
void

deleteRows(table, keys)

deleteRows(table: string, keys: Key[]): void;

Delete rows from a table.

Parameters
Name Description
table string

The name of the table.
keys Key[]

The keys for the rows to delete. If using a composite key, provide an array within this array. See the example below.
Returns
Type Description
void
Examples 

const keys = ['Id1', 'Id2', 'Id3'];

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue this mutation until later calling `commit`.
  // Note that a callback is not passed to `deleteRows`.
  transaction.deleteRows('Singers', keys);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The rows were deleted successfully.
    }
  });
});

Provide an array for keys to delete rows with a composite key.


const keys = [
  [
    'Id1',
    'Name1'
  ],
  [
    'Id2',
    'Name2'
  ]
];

getUniqueKeys(rows)

static getUniqueKeys(rows: object[]): string[];

Takes a list of rows and returns all unique column names.

Parameter
Name Description
rows object[]

The rows.
Returns
Type Description
string[]

{string[]}

insert(table, rows)

insert(table: string, rows: object | object[]): void;

Insert rows of data into this table.

Parameters
Name Description
table string

The name of the table.
rows object | object[]

A map of names to values of data to insert into this table.
Returns
Type Description
void
Examples 

const row = {
  SingerId: 'Id3',
  Name: 'Eddie Wilson'
};

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue this mutation until later calling `commit`.
  // Note that a callback is not passed to `insert`.
  transaction.insert('Singers', row);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The row was inserted successfully.
    }
  });
});

Multiple rows can be inserted at once.


const row2 = {
  SingerId: 'Id3b',
  Name: 'Joe West'
};

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue multiple mutations until later calling `commit`.
  // Note that a callback is not passed to `insert`.
  transaction.insert('Singers', [
    row,
    row2
  ]);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The rows were inserted successfully.
    }
  });
});

replace(table, rows)

replace(table: string, rows: object | object[]): void;

Replace rows of data within a table.

Parameters
Name Description
table string

The table to read from.
rows object | object[]

A map of names to values of data to insert into this table.
Returns
Type Description
void
Example 

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue this mutation until later calling `commit`.
  // Note that a callback is not passed to `replace`.
  transaction.replace('Singers', row);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The row was replaced successfully.
    }
  });
});

rollback(gaxOptions)

rollback(gaxOptions?: CallOptions): Promise<void>;

Roll back a transaction, releasing any locks it holds. It is a good idea to call this for any transaction that includes one or more queries that you decide not to commit.

Wrapper around .

Parameter
Name Description
gaxOptions CallOptions

Request configuration options, See CallOptions for more details.
Returns
Type Description
Promise<void>

{Promise
Example 

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  transaction.rollback(function(err) {
    if (!err) {
      // Transaction rolled back successfully.
    }
  });
});

rollback(callback)

rollback(callback: spannerClient.spanner.v1.Spanner.RollbackCallback): void;
Parameter
Name Description
callback spannerClient.spanner.v1.Spanner.RollbackCallback
Returns
Type Description
void

rollback(gaxOptions, callback)

rollback(gaxOptions: CallOptions, callback: spannerClient.spanner.v1.Spanner.RollbackCallback): void;
Parameters
Name Description
gaxOptions CallOptions
callback spannerClient.spanner.v1.Spanner.RollbackCallback
Returns
Type Description
void

update(table, rows)

update(table: string, rows: object | object[]): void;

Update rows of data within a table.

Parameters
Name Description
table string

The table to read from.
rows object | object[]

A map of names to values of data to insert into this table.
Returns
Type Description
void
Example 

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue this mutation until later calling `commit`.
  // Note that a callback is not passed to `update`.
  transaction.update('Singers', row);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The row was updated successfully.
    }
  });
});

upsert(table, rows)

upsert(table: string, rows: object | object[]): void;

Insert or update rows of data within a table.

Parameters
Name Description
table string

The table to read from.
rows object | object[]

A map of names to values of data to insert into this table.
Returns
Type Description
void
Example 

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

database.runTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  // Queue this mutation until later calling `commit`.
  // Note that a callback is not passed to `upsert`.
  transaction.upsert('Singers', row);

  // Commit the transaction.
  transaction.commit(function(err) {
    if (!err) {
      // The row was updated or inserted successfully.
    }
  });
});