google-cloud-spanner 1.6.4 → 1.7.1

data/lib/google/cloud/spanner/snapshot.rb

@@ -33,7 +33,7 @@ module Google
       #   db = spanner.client "my-instance", "my-database"
       #
       #   db.snapshot do |snp|
-      #     results = snp.execute "SELECT * FROM users"
+      #     results = snp.execute_query "SELECT * FROM users"
       #
       #     results.rows.each do |row|
       #       puts "User #{row[:id]} is #{row[:name]}"
@@ -128,7 +128,7 @@ module Google
         #   db = spanner.client "my-instance", "my-database"
         #
         #   db.snapshot do |snp|
-        #     results = snp.execute "SELECT * FROM users"
+        #     results = snp.execute_query "SELECT * FROM users"
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -142,7 +142,7 @@ module Google
         #   db = spanner.client "my-instance", "my-database"
         #
         #   db.snapshot do |snp|
-        #     results = snp.execute "SELECT * FROM users " \
+        #     results = snp.execute_query "SELECT * FROM users " \
         #                           "WHERE active = @active",
         #                           params: { active: true }
         #
@@ -160,11 +160,13 @@ module Google
         #   db.snapshot do |snp|
         #      user_hash = { id: 1, name: "Charlie", active: false }
         #
-        #     results = snp.execute "SELECT * FROM users WHERE " \
-        #                           "ID = @user_struct.id " \
-        #                           "AND name = @user_struct.name " \
-        #                           "AND active = @user_struct.active",
-        #                           params: { user_struct: user_hash }
+        #     results = snp.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_hash }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -181,12 +183,14 @@ module Google
         #      user_type = snp.fields id: :INT64, name: :STRING, active: :BOOL
         #      user_hash = { id: 1, name: nil, active: false }
         #
-        #     results = snp.execute "SELECT * FROM users WHERE " \
-        #                           "ID = @user_struct.id " \
-        #                           "AND name = @user_struct.name " \
-        #                           "AND active = @user_struct.active",
-        #                           params: { user_struct: user_hash },
-        #                           types: { user_struct: user_type }
+        #     results = snp.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_hash },
+        #       types: { user_struct: user_type }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -203,30 +207,34 @@ module Google
         #      user_type = snp.fields id: :INT64, name: :STRING, active: :BOOL
         #   user_data = user_type.struct id: 1, name: nil, active: false
         #
-        #     results = snp.execute "SELECT * FROM users WHERE " \
-        #                           "ID = @user_struct.id " \
-        #                           "AND name = @user_struct.name " \
-        #                           "AND active = @user_struct.active",
-        #                           params: { user_struct: user_data }
+        #     results = snp.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_data }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
         #     end
         #   end
         #
-        def execute sql, params: nil, types: nil
+        def execute_query sql, params: nil, types: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
 
-          session.execute sql, params: params, types: types,
-                               transaction: tx_selector
+          session.execute_query sql, params: params, types: types,
+                                     transaction: tx_selector
         end
-        alias query execute
+        alias execute execute_query
+        alias query execute_query
+        alias execute_sql execute_query
 
         ##
         # Read rows from a database table, as a simple alternative to
-        # {#execute}.
+        # {#execute_query}.
         #
         # @param [String] table The name of the table in the database to be
         #   read.

data/lib/google/cloud/spanner/transaction.rb

@@ -79,6 +79,7 @@ module Google
 
         def initialize
           @commit = Commit.new
+          @seqno = 0
         end
 
         ##
@@ -157,7 +158,7 @@ module Google
         #   db = spanner.client "my-instance", "my-database"
         #
         #   db.transaction do |tx|
-        #     results = tx.execute "SELECT * FROM users"
+        #     results = tx.execute_query "SELECT * FROM users"
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -171,8 +172,10 @@ module Google
         #   db = spanner.client "my-instance", "my-database"
         #
         #   db.transaction do |tx|
-        #     results = tx.execute "SELECT * FROM users WHERE active = @active",
-        #                          params: { active: true }
+        #     results = tx.execute_query(
+        #       "SELECT * FROM users WHERE active = @active",
+        #       params: { active: true }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -188,11 +191,13 @@ module Google
         #   db.transaction do |tx|
         #     user_hash = { id: 1, name: "Charlie", active: false }
         #
-        #     results = tx.execute "SELECT * FROM users WHERE " \
-        #                          "ID = @user_struct.id " \
-        #                          "AND name = @user_struct.name " \
-        #                          "AND active = @user_struct.active",
-        #                          params: { user_struct: user_hash }
+        #     results = tx.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_hash }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -209,12 +214,14 @@ module Google
         #     user_type = tx.fields id: :INT64, name: :STRING, active: :BOOL
         #     user_hash = { id: 1, name: nil, active: false }
         #
-        #     results = tx.execute "SELECT * FROM users WHERE " \
-        #                          "ID = @user_struct.id " \
-        #                          "AND name = @user_struct.name " \
-        #                          "AND active = @user_struct.active",
-        #                          params: { user_struct: user_hash },
-        #                          types: { user_struct: user_type }
+        #     results = tx.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_hash },
+        #       types: { user_struct: user_type }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
@@ -231,30 +238,133 @@ module Google
         #     user_type = tx.fields id: :INT64, name: :STRING, active: :BOOL
         #     user_data = user_type.struct id: 1, name: nil, active: false
         #
-        #     results = tx.execute "SELECT * FROM users WHERE " \
-        #                          "ID = @user_struct.id " \
-        #                          "AND name = @user_struct.name " \
-        #                          "AND active = @user_struct.active",
-        #                          params: { user_struct: user_data }
+        #     results = tx.execute_query(
+        #       "SELECT * FROM users WHERE " \
+        #       "ID = @user_struct.id " \
+        #       "AND name = @user_struct.name " \
+        #       "AND active = @user_struct.active",
+        #       params: { user_struct: user_data }
+        #     )
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"
         #     end
         #   end
         #
-        def execute sql, params: nil, types: nil
+        def execute_query sql, params: nil, types: nil
           ensure_session!
 
+          @seqno += 1
+
           params, types = Convert.to_input_params_and_types params, types
 
-          session.execute sql, params: params, types: types,
-                               transaction: tx_selector
+          session.execute_query sql, params: params, types: types,
+                                     transaction: tx_selector, seqno: @seqno
+        end
+        alias execute execute_query
+        alias query execute_query
+        alias execute_sql execute_query
+
+        ##
+        # Executes a DML statement.
+        #
+        # @param [String] sql The DML statement string. See [Query
+        #   syntax](https://cloud.google.com/spanner/docs/query-syntax).
+        #
+        #   The DML statement 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.
+        # @param [Hash] params Parameters for the DML statement 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`.
+        #
+        #   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. |
+        #   | `STRUCT`    | `Hash`, {Data} | |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        #   See [Data Types - Constructing a
+        #   STRUCT](https://cloud.google.com/spanner/docs/data-types#constructing-a-struct).
+        # @param [Hash] types 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`
+        #   * `Array` - Lists are specified by providing the type code in an
+        #     array. For example, an array of integers are specified as
+        #     `[:INT64]`.
+        #   * {Fields} - Nested Structs are specified by providing a Fields
+        #     object.
+        #
+        # @return [Integer] The exact number of rows that were modified.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     row_count = tx.execute_update(
+        #       "UPDATE users SET name = 'Charlie' WHERE id = 1",
+        #     )
+        #   end
+        #
+        # @example Update using SQL parameters:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     row_count = tx.execute_update(
+        #       "UPDATE users SET name = @name WHERE id = @id",
+        #       params: { id: 1, name: "Charlie" }
+        #     )
+        #   end
+        #
+        def execute_update sql, params: nil, types: nil
+          results = execute_query sql, params: params, types: types
+          # Stream all PartialResultSet to get ResultSetStats
+          results.rows.to_a
+          # Raise an error if there is not a row count returned
+          if results.row_count.nil?
+            raise Google::Cloud::InvalidArgumentError,
+                  "DML statement is invalid."
+          end
+          results.row_count
         end
-        alias query execute
 
         ##
         # Read rows from a database table, as a simple alternative to
-        # {#execute}.
+        # {#execute_query}.
         #
         # @param [String] table The name of the table in the database to be
         #   read.
@@ -530,7 +640,7 @@ module Google
         #   end
         #
         def fields_for table
-          execute("SELECT * FROM #{table} WHERE 1 = 0").fields
+          execute_query("SELECT * FROM #{table} WHERE 1 = 0").fields
         end
 
         ##

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "1.6.4".freeze
+      VERSION = "1.7.1".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 1.6.4
+  version: 1.7.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-21 00:00:00.000000000 Z
+date: 2018-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core