Class: Google::Cloud::Spanner::Transaction

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/spanner/transaction.rb

Overview

# Transaction

A transaction in Cloud Spanner is a set of reads and writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.

All changes are accumulated in memory until the block passed to Client#transaction completes. Transactions will be automatically retried when possible. See Client#transaction.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  # Read the second album budget.
  second_album_result = tx.read "Albums", ["marketing_budget"],
                                keys: [[2, 2]], limit: 1
  second_album_row = second_album_result.rows.first
  second_album_budget = second_album_row.values.first

  transfer_amount = 200000

  if second_album_budget < 300000
    # Raising an exception will automatically roll back the
    # transaction.
    raise "The second album doesn't have enough funds to transfer"
  end

  # Read the first album's budget.
  first_album_result = tx.read "Albums", ["marketing_budget"],
                                keys: [[1, 1]], limit: 1
  first_album_row = first_album_result.rows.first
  first_album_budget = first_album_row.values.first

  # Update the budgets.
  second_album_budget -= transfer_amount
  first_album_budget += transfer_amount
  puts "Setting first album's budget to #{first_album_budget} and " \
       "the second album's budget to #{second_album_budget}."

  # Update the rows.
  rows = [
    {singer_id: 1, album_id: 1, marketing_budget: first_album_budget},
    {singer_id: 2, album_id: 2, marketing_budget: second_album_budget}
  ]
  tx.update "Albums", rows
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Transaction

Returns a new instance of Transaction.



79
80
81
 
# File 'lib/google/cloud/spanner/transaction.rb', line 79

def initialize
  @commit = Commit.new
end

Instance Attribute Details

#session ⇒ Object 



77
78
79
 
# File 'lib/google/cloud/spanner/transaction.rb', line 77

def session
  @session
end

Class Method Details

.from_grpc(grpc, session) ⇒ Object

Google::Spanner::V1::Transaction.



532
533
534
535
536
537
 
# File 'lib/google/cloud/spanner/transaction.rb', line 532

def self.from_grpc grpc, session
  new.tap do |s|
    s.instance_variable_set :@grpc,    grpc
    s.instance_variable_set :@session, session
  end
end

Instance Method Details

#delete(table, keys = []) ⇒ Object

Deletes rows from a table. Succeeds whether or not the specified rows were present.

All changes are accumulated in memory until the block passed to Client#transaction completes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction { |tx| tx.delete "users", [1, 2, 3] }

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • keys (Object, Array<Object>) (defaults to: []) —

    A single, or list of keys or key ranges to match returned data to. Values should have exactly as many elements as there are columns in the primary key.



431
432
433
434
 
# File 'lib/google/cloud/spanner/transaction.rb', line 431

def delete table, keys = []
  ensure_session!
  @commit.delete table, keys
end

#execute(sql, params: nil, types: nil) ⇒ Google::Cloud::Spanner::Results Also known as: query

Executes a SQL query.

Arguments can be passed using ‘params`, Ruby types are mapped to Spanner types as follows:

| Spanner | Ruby | Notes | |————-|—————-|—| | ‘BOOL` | `true`/`false` | | | `INT64` | `Integer` | | | `FLOAT64` | `Float` | | | `STRING` | `String` | | | `DATE` | `Date` | | | `TIMESTAMP` | `Time`, `DateTime` | | | `BYTES` | `File`, `IO`, `StringIO`, or similar | | | `ARRAY` | `Array` | Nested arrays are not supported. |

See [Data types](cloud.google.com/spanner/docs/data-definition-language#data_types).

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Query using query parameters:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute "SELECT * FROM users WHERE active = @active",
                       params: { active: true }

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Parameters:

  • sql (String) —

    The SQL query string. See [Query syntax](cloud.google.com/spanner/docs/query-syntax).

    The SQL query string can contain parameter placeholders. A parameter placeholder consists of “@” followed by the parameter name. Parameter names consist of any combination of letters, numbers, and underscores.

  • params (Hash) (defaults to: nil) —

    SQL parameters for the query string. The parameter placeholders, minus the “@”, are the the hash keys, and the literal values are the hash values. If the query string contains something like “WHERE id > @msg_id”, then the params must contain something like ‘:msg_id => 1`.

  • types (Hash) (defaults to: nil) —

    Types of the SQL parameters in ‘params`. It is not always possible for Cloud Spanner to infer the right SQL type from a value in `params`. In these cases, the `types` hash can be used to specify the exact SQL type for some or all of the SQL query parameters.

    The keys of the hash should be query string parameter placeholders, minus the “@”. The values of the hash should be Cloud Spanner type codes from the following list:

    • ‘:BOOL`

    • ‘:BYTES`

    • ‘:DATE`

    • ‘:FLOAT64`

    • ‘:INT64`

    • ‘:STRING`

    • ‘:TIMESTAMP`

    Arrays are specified by providing the type code in an array. For example, an array of integers are specified as ‘[:INT64]`.

    Structs are not yet supported in query parameters.

    Types are optional.

Returns:



179
180
181
182
183
 
# File 'lib/google/cloud/spanner/transaction.rb', line 179

def execute sql, params: nil, types: nil
  ensure_session!
  session.execute sql, params: params, types: types,
                       transaction: tx_selector
end

#fields_for(table) ⇒ Hash, Array

Returns the field names and types for a table.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  users_types = tx.fields_for "users"
  tx.insert "users", [{ id: 1, name: "Charlie", active: false },
                      { id: 2, name: "Harvey",  active: true }],
            types: users_types
end

Parameters:

  • table (String) —

    The name of the table in the database to retrieve types for

Returns:

  • (Hash, Array) —

    The types of the returned data. The default is a Hash. Is a nested Array of Arrays when ‘pairs` is specified.



459
460
461
 
# File 'lib/google/cloud/spanner/transaction.rb', line 459

def fields_for table
  execute("SELECT * FROM #{table} WHERE 1 = 0").fields
end

#idle_since?(duration) ⇒ Boolean

Determines if the transaction has been idle longer than the given duration.

Returns:

  • (Boolean) 


518
519
520
 
# File 'lib/google/cloud/spanner/transaction.rb', line 518

def idle_since? duration
  session.idle_since? duration
end

#insert(table, *rows) ⇒ Object

Inserts new rows in a table. If any of the rows already exist, the write or request fails with error AlreadyExistsError.

All changes are accumulated in memory until the block passed to Client#transaction completes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  tx.insert "users", [{ id: 1, name: "Charlie", active: false },
                      { id: 2, name: "Harvey",  active: true }]
end

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table’s columns, and the hash values matching the table’s values.

    Ruby types are mapped to Spanner types as follows:

    | Spanner | Ruby | Notes | |————-|—————-|—| | ‘BOOL` | `true`/`false` | | | `INT64` | `Integer` | | | `FLOAT64` | `Float` | | | `STRING` | `String` | | | `DATE` | `Date` | | | `TIMESTAMP` | `Time`, `DateTime` | | | `BYTES` | `File`, `IO`, `StringIO`, or similar | | | `ARRAY` | `Array` | Nested arrays are not supported. |

    See [Data types](cloud.google.com/spanner/docs/data-definition-language#data_types).



313
314
315
316
 
# File 'lib/google/cloud/spanner/transaction.rb', line 313

def insert table, *rows
  ensure_session!
  @commit.insert table, rows
end

#keepalive! ⇒ Object

Keeps the transaction current by creating a new transaction.



501
502
503
504
 
# File 'lib/google/cloud/spanner/transaction.rb', line 501

def keepalive!
  ensure_session!
  @grpc = session.create_transaction.instance_variable_get :@grpc
end

#mutations ⇒ Object

All of the mutations created in the transaction block.



525
526
527
 
# File 'lib/google/cloud/spanner/transaction.rb', line 525

def mutations
  @commit.mutations
end

#range(beginning, ending, exclude_begin: false, exclude_end: false) ⇒ Google::Cloud::Spanner::Range

Creates a Cloud Spanner Range. This can be used in place of a Ruby Range when needing to exclude the beginning value.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  key_range = tx.range 1, 100
  results = tx.read "users", [:id, :name], keys: key_range

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Parameters:

  • beginning (Object) —

    The object that defines the beginning of the range.

  • ending (Object) —

    The object that defines the end of the range.

  • exclude_begin (Boolean) (defaults to: false) —

    Determines if the range excludes its beginning value. Default is ‘false`.

  • exclude_end (Boolean) (defaults to: false) —

    Determines if the range excludes its ending value. Default is ‘false`.

Returns:



492
493
494
495
496
 
# File 'lib/google/cloud/spanner/transaction.rb', line 492

def range beginning, ending, exclude_begin: false, exclude_end: false
  Range.new beginning, ending,
            exclude_begin: exclude_begin,
            exclude_end: exclude_end
end

#read(table, columns, keys: nil, index: nil, limit: nil) ⇒ Google::Cloud::Spanner::Results

Read rows from a database table, as a simple alternative to #execute.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.read "users", [:id, :name]

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Parameters:

  • table (String) —

    The name of the table in the database to be read.

  • columns (Array<String, Symbol>) —

    The columns of table to be returned for each row matching this request.

  • keys (Object, Array<Object>) (defaults to: nil) —

    A single, or list of keys or key ranges to match returned data to. Values should have exactly as many elements as there are columns in the primary key.

  • index (String) (defaults to: nil) —

    The name of an index to use instead of the table’s primary key when interpreting ‘id` and sorting result rows. Optional.

  • limit (Integer) (defaults to: nil) —

    If greater than zero, no more than this number of rows will be returned. The default is no limit.

Returns:



220
221
222
223
224
 
# File 'lib/google/cloud/spanner/transaction.rb', line 220

def read table, columns, keys: nil, index: nil, limit: nil
  ensure_session!
  session.read table, columns, keys: keys, index: index, limit: limit,
                               transaction: tx_selector
end

#release! ⇒ Object

Permanently deletes the transaction and session.



509
510
511
512
 
# File 'lib/google/cloud/spanner/transaction.rb', line 509

def release!
  ensure_session!
  session.release!
end

#replace(table, *rows) ⇒ Object

Inserts or replaces rows in a table. If any of the rows already exist, it is deleted, and the column values provided are inserted instead. Unlike #upsert, this means any values not explicitly written become ‘NULL`.

All changes are accumulated in memory until the block passed to Client#transaction completes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  tx.replace "users", [{ id: 1, name: "Charlie", active: false },
                       { id: 2, name: "Harvey",  active: true }]
end

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table’s columns, and the hash values matching the table’s values.

    Ruby types are mapped to Spanner types as follows:

    | Spanner | Ruby | Notes | |————-|—————-|—| | ‘BOOL` | `true`/`false` | | | `INT64` | `Integer` | | | `FLOAT64` | `Float` | | | `STRING` | `String` | | | `DATE` | `Date` | | | `TIMESTAMP` | `Time`, `DateTime` | | | `BYTES` | `File`, `IO`, `StringIO`, or similar | | | `ARRAY` | `Array` | Nested arrays are not supported. |

    See [Data types](cloud.google.com/spanner/docs/data-definition-language#data_types).



405
406
407
408
 
# File 'lib/google/cloud/spanner/transaction.rb', line 405

def replace table, *rows
  ensure_session!
  @commit.replace table, rows
end

#transaction_id ⇒ String

Identifier of the transaction results were run in.

Returns:

  • (String) —

    The transaction id.



86
87
88
89
 
# File 'lib/google/cloud/spanner/transaction.rb', line 86

def transaction_id
  return nil if @grpc.nil?
  @grpc.id
end

#update(table, *rows) ⇒ Object

Updates existing rows in a table. If any of the rows does not already exist, the request fails with error NotFoundError.

All changes are accumulated in memory until the block passed to Client#transaction completes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  tx.update "users", [{ id: 1, name: "Charlie", active: false },
                      { id: 2, name: "Harvey",  active: true }]
end

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table’s columns, and the hash values matching the table’s values.

    Ruby types are mapped to Spanner types as follows:

    | Spanner | Ruby | Notes | |————-|—————-|—| | ‘BOOL` | `true`/`false` | | | `INT64` | `Integer` | | | `FLOAT64` | `Float` | | | `STRING` | `String` | | | `DATE` | `Date` | | | `TIMESTAMP` | `Time`, `DateTime` | | | `BYTES` | `File`, `IO`, `StringIO`, or similar | | | `ARRAY` | `Array` | Nested arrays are not supported. |

    See [Data types](cloud.google.com/spanner/docs/data-definition-language#data_types).



358
359
360
361
 
# File 'lib/google/cloud/spanner/transaction.rb', line 358

def update table, *rows
  ensure_session!
  @commit.update table, rows
end

#upsert(table, *rows) ⇒ Object Also known as: save

Inserts or updates rows in a table. If any of the rows already exist, then its column values are overwritten with the ones provided. Any column values not explicitly written are preserved.

All changes are accumulated in memory until the block passed to Client#transaction completes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  tx.upsert "users", [{ id: 1, name: "Charlie", active: false },
                      { id: 2, name: "Harvey",  active: true }]
end

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table’s columns, and the hash values matching the table’s values.

    Ruby types are mapped to Spanner types as follows:

    | Spanner | Ruby | Notes | |————-|—————-|—| | ‘BOOL` | `true`/`false` | | | `INT64` | `Integer` | | | `FLOAT64` | `Float` | | | `STRING` | `String` | | | `DATE` | `Date` | | | `TIMESTAMP` | `Time`, `DateTime` | | | `BYTES` | `File`, `IO`, `StringIO`, or similar | | | `ARRAY` | `Array` | Nested arrays are not supported. |

    See [Data types](cloud.google.com/spanner/docs/data-definition-language#data_types).



267
268
269
270
 
# File 'lib/google/cloud/spanner/transaction.rb', line 267

def upsert table, *rows
  ensure_session!
  @commit.upsert table, rows
end