google-cloud-spanner 1.6.4 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a7e4d511e0da87129eb3b33152dda498583baf5832222808867822a7097d79a
-  data.tar.gz: 18ada9b93ec395b625c1439a90a2968c495c62eb1fdee3f1ecbbcae79c33f329
+  metadata.gz: 1f10305755bd4e6a4e31255e8fa54067a6725190a7bd8465321d3db6ab85e5b8
+  data.tar.gz: d6d33eaf5b1e84649fd7ab4d65565acf350afa2f073f2697106444f0a07ccdf1
 SHA512:
-  metadata.gz: 50c14a7f74a351318c61fe1ad2b2342231f8997db010c5793d5d0112e4e545399476c2a2ab3aa3b0505cdef63430d710d864346bca611be19a78861af82a04d0
-  data.tar.gz: d244fd5a527e3759536e797bee8354a7263898a5ac6bd7941d4815c02de432d4b83ef72dbe81cd8fbd7c4d259b59b21bc70311d9e81b5f7ed62ea3d5ee8da9ec
+  metadata.gz: a17174bd2315f5252835be530aa64b264426eef1ba3285682d6546101127203059fb2878733b5f1056e25181cd592828dfd7113916be667503dc7251c60521d6
+  data.tar.gz: 7bce7dd07f441fffd5a56017f92220ad088465dc269a9dc9c967bf24b81e4017487f6bc601e22912c2e0c1206f9dc2488d21788e050f2864c73812f127548547

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 1.7.1 / 2018-10-08
+
+* Add DML and Partitioned DML support
+  * Add execute_update to process DML statements
+  * Add execute_partition_update for Partitioned DML
+* Rename execute_query method
+  * Maintain naming consistency with execute_update method.
+  * Maintain compatibility by adding query, execute and execute_sql aliases.
+
 ### 1.6.4 / 2018-09-20
 
 * Update Spanner generated files.

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

@@ -200,7 +200,7 @@ module Google
 
           results.partitions.map do |grpc|
             # Convert partition protos to execute sql request protos
-            execute_grpc = Google::Spanner::V1::ExecuteSqlRequest.new(
+            execute_sql_grpc = Google::Spanner::V1::ExecuteSqlRequest.new(
               {
                 session: session.path,
                 sql: sql,
@@ -210,7 +210,7 @@ module Google
                 partition_token: grpc.partition_token
               }.delete_if { |_, v| v.nil? }
             )
-            Partition.from_execute_grpc execute_grpc
+            Partition.from_execute_sql_grpc execute_sql_grpc
           end
         end
 
@@ -425,7 +425,7 @@ module Google
         #   batch_client = spanner.batch_client "my-instance", "my-database"
         #   batch_snapshot = batch_client.batch_snapshot
         #
-        #   results = batch_snapshot.execute "SELECT * FROM users"
+        #   results = batch_snapshot.execute_query "SELECT * FROM users"
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -438,9 +438,11 @@ module Google
         #   batch_client = spanner.batch_client "my-instance", "my-database"
         #   batch_snapshot = batch_client.batch_snapshot
         #
-        #   results = batch_snapshot.execute "SELECT * FROM users " \
-        #                                    "WHERE active = @active",
-        #                                    params: { active: true }
+        #   results = batch_snapshot.execute_query(
+        #      "SELECT * FROM users " \
+        #      "WHERE active = @active",
+        #      params: { active: true }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -455,11 +457,13 @@ module Google
         #
         #   user_hash = { id: 1, name: "Charlie", active: false }
         #
-        #   results = batch_snapshot.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 = batch_snapshot.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]}"
@@ -477,12 +481,14 @@ module Google
         #   )
         #   user_hash = { id: 1, name: nil, active: false }
         #
-        #   results = batch_snapshot.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 = batch_snapshot.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]}"
@@ -500,29 +506,33 @@ module Google
         #   )
         #   user_data = user_type.struct id: 1, name: nil, active: false
         #
-        #   results = batch_snapshot.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 = batch_snapshot.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
         #
-        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.
@@ -651,11 +661,12 @@ module Google
         end
 
         def execute_partition_query partition
-          session.execute partition.execute.sql,
-                          params: partition.execute.params,
-                          types: partition.execute.param_types.to_h,
-                          transaction: partition.execute.transaction,
-                          partition_token: partition.execute.partition_token
+          session.execute_query \
+            partition.execute.sql,
+            params: partition.execute.params,
+            types: partition.execute.param_types.to_h,
+            transaction: partition.execute.transaction,
+            partition_token: partition.execute.partition_token
         end
 
         def execute_partition_read partition

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

@@ -42,7 +42,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]}"
@@ -218,7 +218,7 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users"
+        #   results = db.execute_query "SELECT * FROM users"
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -231,8 +231,10 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users WHERE active = @active",
-        #                        params: { active: true }
+        #   results = db.execute_query(
+        #     "SELECT * FROM users WHERE active = @active",
+        #     params: { active: true }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -247,11 +249,13 @@ module Google
         #
         #   user_hash = { id: 1, name: "Charlie", active: false }
         #
-        #   results = db.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 = db.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]}"
@@ -267,12 +271,14 @@ module Google
         #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
         #   user_hash = { id: 1, name: nil, active: false }
         #
-        #   results = db.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 = db.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]}"
@@ -288,17 +294,19 @@ module Google
         #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
         #   user_data = user_type.struct id: 1, name: nil, active: false
         #
-        #   results = db.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 = db.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
         #
-        def execute sql, params: nil, types: nil, single_use: nil
+        def execute_query sql, params: nil, types: nil, single_use: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -307,16 +315,197 @@ module Google
           single_use_tx = single_use_transaction single_use
           results = nil
           @pool.with_session do |session|
-            results = session.execute \
+            results = session.execute_query \
               sql, params: params, types: types, transaction: single_use_tx
           end
           results
         end
-        alias query execute
+        alias execute execute_query
+        alias query execute_query
+        alias execute_sql execute_query
+
+        ##
+        # Executes a Partitioned DML SQL statement.
+        #
+        # Partitioned DML is an alternate implementation with looser semantics
+        # to enable large-scale changes without running into transaction size
+        # limits or (accidentally) locking the entire table in one large
+        # transaction. At a high level, it partitions the keyspace and executes
+        # the statement on each partition in separate internal transactions.
+        #
+        # Partitioned DML does not guarantee database-wide atomicity of the
+        # statement - it guarantees row-based atomicity, which includes updates
+        # to any indices. Additionally, it does not guarantee that it will
+        # execute exactly one time against each row - it guarantees "at least
+        # once" semantics.
+        #
+        # Where DML statements must be executed using Transaction (see
+        # {Transaction#execute_update}), Paritioned DML statements are executed
+        # outside of a read/write transaction.
+        #
+        # Not all DML statements can be executed in the Partitioned DML mode and
+        # the backend will return an error for the statements which are not
+        # supported.
+        #
+        # DML statements must be fully-partitionable. Specifically, the
+        # statement must be expressible as the union of many statements which
+        # each access only a single row of the table.
+        # {Google::Cloud::InvalidArgumentError} is raised if the statement does
+        # not qualify.
+        #
+        # The method will block until the update is complete. Running a DML
+        # statement with this method does not offer exactly once semantics, and
+        # therefore the DML statement should be idempotent. The DML statement
+        # must be fully-partitionable. Specifically, the statement must be
+        # expressible as the union of many statements which each access only a
+        # single row of the table. This is a Partitioned DML transaction in
+        # which a single Partitioned DML statement is executed. Partitioned DML
+        # partitions the and runs the DML statement over each partition in
+        # parallel using separate, internal transactions that commit
+        # independently. Partitioned DML transactions do not need to be
+        # committed.
+        #
+        # Partitioned DML updates are used to execute a single DML statement
+        # with a different execution strategy that provides different, and often
+        # better, scalability properties for large, table-wide operations than
+        # DML in a {Transaction#execute_update} transaction. Smaller scoped
+        # statements, such as an OLTP workload, should prefer using
+        # {Transaction#execute_update}.
+        #
+        # That said, Partitioned DML is not a drop-in replacement for standard
+        # DML used in {Transaction#execute_update}.
+        #
+        # * The DML statement must be fully-partitionable. Specifically, the
+        #   statement must be expressible as the union of many statements which
+        #   each access only a single row of the table.
+        # * The statement is not applied atomically to all rows of the table.
+        #   Rather, the statement is applied atomically to partitions of the
+        #   table, in independent internal transactions. Secondary index rows
+        #   are updated atomically with the base table rows.
+        # * Partitioned DML does not guarantee exactly-once execution semantics
+        #   against a partition. The statement will be applied at least once to
+        #   each partition. It is strongly recommended that the DML statement
+        #   should be idempotent to avoid unexpected results. For instance, it
+        #   is potentially dangerous to run a statement such as `UPDATE table
+        #   SET column = column + 1` as it could be run multiple times against
+        #   some rows.
+        # * The partitions are committed automatically - there is no support for
+        #   Commit or Rollback. If the call returns an error, or if the client
+        #   issuing the DML statement dies, it is possible that some rows had
+        #   the statement executed on them successfully. It is also possible
+        #   that statement was never executed against other rows.
+        # * If any error is encountered during the execution of the partitioned
+        #   DML operation (for instance, a UNIQUE INDEX violation, division by
+        #   zero, or a value that cannot be stored due to schema constraints),
+        #   then the operation is stopped at that point and an error is
+        #   returned. It is possible that at this point, some partitions have
+        #   been committed (or even committed multiple times), and other
+        #   partitions have not been run at all.
+        #
+        # Given the above, Partitioned DML is good fit for large, database-wide,
+        # operations that are idempotent, such as deleting old rows from a very
+        # large table.
+        #
+        # @param [String] sql The Partitioned DML statement string. See [Query
+        #   syntax](https://cloud.google.com/spanner/docs/query-syntax).
+        #
+        #   The Partitioned 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 Partitioned 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 lower bound number of rows that were modified.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   row_count = db.execute_partition_update \
+        #    "UPDATE users SET friends = NULL WHERE active = false"
+        #
+        # @example Query using query parameters:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   row_count = db.execute_partition_update \
+        #    "UPDATE users SET friends = NULL WHERE active = @active",
+        #    params: { active: false }
+        #
+        def execute_partition_update sql, params: nil, types: nil
+          ensure_service!
+
+          params, types = Convert.to_input_params_and_types params, types
+
+          results = nil
+          @pool.with_session do |session|
+            results = session.execute_query \
+              sql, params: params, types: types,
+                   transaction: pdml_transaction(session)
+          end
+          # 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,
+                  "Partitioned DML statement is invalid."
+          end
+          results.row_count
+        end
+        alias execute_pdml execute_partition_update
 
         ##
         # 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.
@@ -764,7 +953,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]}"
@@ -883,7 +1072,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]}"
@@ -1012,7 +1201,7 @@ module Google
         #             types: users_types
         #
         def fields_for table
-          execute("SELECT * FROM #{table} WHERE 1 = 0").fields
+          execute_query("SELECT * FROM #{table} WHERE 1 = 0").fields
         end
 
         ##
@@ -1159,6 +1348,11 @@ module Google
               }.delete_if { |_, v| v.nil? })))
         end
 
+        def pdml_transaction session
+          pdml_tx_grpc = @project.service.create_pdml session.path
+          Google::Spanner::V1::TransactionSelector.new id: pdml_tx_grpc.id
+        end
+
         ##
         # Check for valid snapshot arguments
         def validate_snapshot_args! strong: nil,