google-cloud-spanner 1.2.0 → 1.3.1

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

@@ -53,7 +53,11 @@ module Google
       #   job.reload! # API call
       #   job.done? #=> true
       #
-      #   instance = spanner.instance "my-new-instance"
+      #   if job.error?
+      #     status = job.error
+      #   else
+      #     instance = job.instance
+      #   end
       #
       class Instance
         ##
@@ -93,7 +97,7 @@ module Google
         def name
           @grpc.display_name
         end
-        alias_method :display_name, :name
+        alias display_name name
 
         ##
         # The instance configuration resource.
@@ -112,7 +116,7 @@ module Google
         def name= display_name
           @grpc.display_name = display_name
         end
-        alias_method :display_name=, :name=
+        alias display_name= name=
 
         ##
         # The number of nodes allocated to this instance.
@@ -120,7 +124,7 @@ module Google
         def nodes
           @grpc.node_count
         end
-        alias_method :node_count, :nodes
+        alias node_count nodes
 
         ##
         # Updates the number of nodes allocated to this instance.
@@ -128,7 +132,7 @@ module Google
         def nodes= nodes
           @grpc.node_count = nodes
         end
-        alias_method :node_count=, :nodes=
+        alias node_count= nodes=
 
         ##
         # The current instance state. Possible values are `:CREATING` and
@@ -180,14 +184,15 @@ module Google
         def labels= labels
           @grpc.labels = Google::Protobuf::Map.new(
             :string, :string,
-            Hash[labels.map { |k, v| [String(k), String(v)] }])
+            Hash[labels.map { |k, v| [String(k), String(v)] }]
+          )
         end
 
         def save
           job_grpc = service.update_instance @grpc
           Instance::Job.from_grpc job_grpc, service
         end
-        alias_method :update, :save
+        alias update save
 
         ##
         # Permanently deletes the instance.
@@ -316,7 +321,12 @@ module Google
         #   job.done? #=> false
         #   job.reload! # API call
         #   job.done? #=> true
-        #   database = job.database
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
         #
         def create_database database_id, statements: []
           grpc = service.create_database instance_id, database_id,
@@ -364,7 +374,7 @@ module Google
           policy = Policy.from_grpc grpc
           return policy unless block_given?
           yield policy
-          self.policy = policy
+          update_policy policy
         end
 
         ##
@@ -394,13 +404,14 @@ module Google
         #
         #   policy.add "roles/owner", "user:owner@example.com"
         #
-        #   instance.policy = policy # API call
+        #   instance.update_policy policy # API call
         #
-        def policy= new_policy
+        def update_policy new_policy
           ensure_service!
           grpc = service.set_instance_policy path, new_policy.to_grpc
           Policy.from_grpc grpc
         end
+        alias policy= update_policy
 
         ##
         # Tests the specified permissions against the [Cloud
@@ -456,13 +467,14 @@ module Google
         # @private Raise an error unless an active connection to the service is
         # available.
         def ensure_service!
-          fail "Must have active connection to service" unless service
+          raise "Must have active connection to service" unless service
         end
 
         def instance_config_path name
           return name if name.to_s.include? "/"
           Admin::Instance::V1::InstanceAdminClient.instance_config_path(
-            project, name.to_s)
+            project, name.to_s
+          )
         end
       end
     end

data/lib/google/cloud/spanner/instance/config.rb

@@ -73,7 +73,7 @@ module Google
           def name
             @grpc.display_name
           end
-          alias_method :display_name, :name
+          alias display_name name
 
           ##
           # @private Creates a new Instance::Config instance from a
@@ -88,7 +88,7 @@ module Google
           # @private Raise an error unless an active connection to the service
           # is available.
           def ensure_service!
-            fail "Must have active connection to service" unless service
+            raise "Must have active connection to service" unless service
           end
         end
       end

data/lib/google/cloud/spanner/instance/config/list.rb

@@ -161,7 +161,7 @@ module Google
             ##
             # Raise an error unless an active service is available.
             def ensure_service!
-              fail "Must have active connection" unless @service
+              raise "Must have active connection" unless @service
             end
           end
         end

data/lib/google/cloud/spanner/instance/job.rb

@@ -44,7 +44,12 @@ module Google
         #   job.done? #=> false
         #   job.reload! # API call
         #   job.done? #=> true
-        #   instance = job.instance
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     instance = job.instance
+        #   end
         #
         class Job
           ##
@@ -187,7 +192,7 @@ module Google
             @grpc.reload!
             self
           end
-          alias_method :refresh!, :reload!
+          alias refresh! reload!
 
           ##
           # Reloads the job until the operation is complete. The delay between

data/lib/google/cloud/spanner/instance/list.rb

@@ -158,7 +158,7 @@ module Google
           ##
           # Raise an error unless an active service is available.
           def ensure_service!
-            fail "Must have active connection" unless @service
+            raise "Must have active connection" unless @service
           end
         end
       end

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

@@ -0,0 +1,208 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "json"
+require "base64"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Partition
+      #
+      # Defines the segments of data to be read in a batch read/query context. A
+      # Partition instance can be serialized and used across several different
+      # machines or processes.
+      #
+      # See {BatchSnapshot#partition_read}, {BatchSnapshot#partition_query}, and
+      # {BatchSnapshot#execute_partition}.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   batch_client = spanner.batch_client "my-instance", "my-database"
+      #
+      #   batch_snapshot = batch_client.batch_snapshot
+      #   partitions = batch_snapshot.partition_read "users", [:id, :name]
+      #
+      #   partition = partitions.first
+      #
+      #   results = batch_snapshot.execute_partition partition
+      #
+      class Partition
+        # @ private
+        attr_reader :execute, :read
+
+        ##
+        # @private Creates a Partition object.
+        def initialize; end
+
+        ##
+        # Whether the partition was created for an execute/query operation.
+        # @return [Boolean]
+        def execute?
+          !@execute.nil?
+        end
+
+        ##
+        # Whether the partition was created for a read operation.
+        # @return [Boolean]
+        def read?
+          !@read.nil?
+        end
+
+        ##
+        # @private
+        # Whether the partition does not have an execute or read operation.
+        # @return [Boolean]
+        def empty?
+          @execute.nil? && @read.nil?
+        end
+
+        ##
+        # @private
+        # Converts the the batch partition object to a Hash ready for
+        # serialization.
+        #
+        # @return [Hash] A hash containing a representation of the batch
+        #   partition object.
+        #
+        def to_h
+          {}.tap do |h|
+            h[:execute] = Base64.strict_encode64(@execute.to_proto) if @execute
+            h[:read] = Base64.strict_encode64(@read.to_proto) if @read
+          end
+        end
+
+        ##
+        # Serializes the batch partition object so it can be recreated on
+        # another process. See {Partition.load} and
+        # {BatchClient#load_partition}.
+        #
+        # @return [String] The serialized representation of the batch partition.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #
+        #   batch_snapshot = batch_client.batch_snapshot
+        #
+        #   partitions = batch_snapshot.partition_read "users", [:id, :name]
+        #
+        #   partition = partitions.first
+        #
+        #   serialized_snapshot = batch_snapshot.dump
+        #   serialized_partition = partition.dump
+        #
+        #   # In a separate process
+        #   new_batch_snapshot = batch_client.load_batch_snapshot \
+        #     serialized_snapshot
+        #
+        #   new_partition = batch_client.load_partition \
+        #     serialized_partition
+        #
+        #   results = new_batch_snapshot.execute_partition \
+        #     new_partition
+        #
+        def dump
+          JSON.dump to_h
+        end
+        alias serialize dump
+
+        ##
+        # Returns a {Partition} from a serialized representation.
+        #
+        # @param [String] data The serialized representation of an existing
+        #   batch partition. See {Partition#dump}.
+        #
+        # @return [Google::Cloud::Spanner::Partition]
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #
+        #   batch_snapshot = batch_client.batch_snapshot
+        #
+        #   partitions = batch_snapshot.partition_read "users", [:id, :name]
+        #
+        #   partition = partitions.first
+        #
+        #   serialized_snapshot = batch_snapshot.dump
+        #   serialized_partition = partition.dump
+        #
+        #   # In a separate process
+        #   new_batch_snapshot = batch_client.load_batch_snapshot \
+        #     serialized_snapshot
+        #
+        #   new_partition = Google::Cloud::Spanner::Partition.load \
+        #     serialized_partition
+        #
+        #   results = new_batch_snapshot.execute_partition \
+        #     new_partition
+        #
+        def self.load data
+          data = JSON.parse data, symbolize_names: true unless data.is_a? Hash
+
+          # TODO: raise if hash[:execute].nil? && hash[:read].nil?
+          new.tap do |p|
+            if data[:execute]
+              execute_grpc = Google::Spanner::V1::ExecuteSqlRequest.decode \
+                Base64.decode64(data[:execute])
+              p.instance_variable_set :@execute, execute_grpc
+            end
+            if data[:read]
+              read_grpc = Google::Spanner::V1::ReadRequest.decode \
+                Base64.decode64(data[:read])
+              p.instance_variable_set :@read, read_grpc
+            end
+          end
+        end
+
+        # @private
+        def inspect
+          status = "empty"
+          status = "execute" if execute?
+          status = "read" if read?
+          "#<#{self.class.name} #{status}>"
+        end
+
+        ##
+        # @private New Partition from a Google::Spanner::V1::ExecuteSqlRequest
+        # object.
+        def self.from_execute_grpc grpc
+          new.tap do |p|
+            p.instance_variable_set :@execute, grpc
+          end
+        end
+
+        ##
+        # @private New Partition from a Google::Spanner::V1::ReadRequest object.
+        def self.from_read_grpc grpc
+          new.tap do |p|
+            p.instance_variable_set :@read, grpc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -64,7 +64,7 @@ module Google
           action = nil
           @mutex.synchronize do
             loop do
-              fail ClientClosedError if @closed
+              raise ClientClosedError if @closed
 
               read_session = session_queue.shift
               return read_session if read_session
@@ -77,7 +77,7 @@ module Google
                 break
               end
 
-              fail SessionLimitError if @fail
+              raise SessionLimitError if @fail
 
               @resource.wait @mutex
             end
@@ -89,7 +89,7 @@ module Google
         def checkin_session session
           @mutex.synchronize do
             unless all_sessions.include? session
-              fail ArgumentError, "Cannot checkin session"
+              raise ArgumentError, "Cannot checkin session"
             end
 
             session_queue.push session
@@ -117,7 +117,7 @@ module Google
           action = nil
           @mutex.synchronize do
             loop do
-              fail ClientClosedError if @closed
+              raise ClientClosedError if @closed
 
               write_transaction = transaction_queue.shift
               return write_transaction if write_transaction
@@ -133,7 +133,7 @@ module Google
                 break
               end
 
-              fail SessionLimitError if @fail
+              raise SessionLimitError if @fail
 
               @resource.wait @mutex
             end
@@ -147,7 +147,7 @@ module Google
         def checkin_transaction tx
           @mutex.synchronize do
             unless all_sessions.include? tx.session
-              fail ArgumentError, "Cannot checkin session"
+              raise ArgumentError, "Cannot checkin session"
             end
 
             transaction_queue.push tx

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

@@ -14,9 +14,9 @@
 
 
 require "google/cloud/spanner/errors"
-require "google/cloud/env"
 require "google/cloud/spanner/service"
 require "google/cloud/spanner/client"
+require "google/cloud/spanner/batch_client"
 require "google/cloud/spanner/instance"
 require "google/cloud/spanner/database"
 require "google/cloud/spanner/range"
@@ -92,16 +92,7 @@ module Google
         def project_id
           service.project
         end
-        alias_method :project, :project_id
-
-        ##
-        # @private Default project.
-        def self.default_project_id
-          ENV["SPANNER_PROJECT"] ||
-            ENV["GOOGLE_CLOUD_PROJECT"] ||
-            ENV["GCLOUD_PROJECT"] ||
-            Google::Cloud.env.project_id
-        end
+        alias project project_id
 
         ##
         # Retrieves the list of Cloud Spanner instances for the project.
@@ -218,7 +209,12 @@ module Google
         #   job.done? #=> false
         #   job.reload! # API call
         #   job.done? #=> true
-        #   instance = job.instance
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     instance = job.instance
+        #   end
         #
         def create_instance instance_id, name: nil, config: nil, nodes: nil,
                             labels: nil
@@ -396,7 +392,12 @@ module Google
         #   job.done? #=> false
         #   job.reload! # API call
         #   job.done? #=> true
-        #   database = job.database
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
         #
         def create_database instance_id, database_id, statements: []
           grpc = service.create_database instance_id, database_id,
@@ -457,22 +458,64 @@ module Google
                      valid_session_pool_options(pool)
         end
 
+        ##
+        # Creates a Cloud Spanner batch client. A batch client is used to read
+        # data across multiple machines or processes.
+        #
+        # @param [String] instance_id The unique identifier for the instance.
+        #   Required.
+        # @param [String] database_id The unique identifier for the database.
+        #   Required.
+        #
+        # @return [Client] The newly created client.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #
+        #   batch_snapshot = batch_client.batch_snapshot
+        #   serialized_snapshot = batch_snapshot.dump
+        #
+        #   partitions = batch_snapshot.partition_read "users", [:id, :name]
+        #
+        #   partition = partitions.first
+        #   serialized_partition = partition.dump
+        #
+        #   # In a separate process
+        #   new_batch_snapshot = batch_client.load_batch_snapshot \
+        #     serialized_snapshot
+        #
+        #   new_partition = batch_client.load_partition \
+        #     serialized_partition
+        #
+        #   results = new_batch_snapshot.execute_partition \
+        #     new_partition
+        #
+        def batch_client instance_id, database_id
+          BatchClient.new self, instance_id, database_id
+        end
+
         protected
 
         ##
         # @private Raise an error unless an active connection to the service is
         # available.
         def ensure_service!
-          fail "Must have active connection to service" unless service
+          raise "Must have active connection to service" unless service
         end
 
         def database_path instance_id, database_id
           Admin::Database::V1::DatabaseAdminClient.database_path(
-            project, instance_id, database_id)
+            project, instance_id, database_id
+          )
         end
 
         def valid_session_pool_options opts = {}
-          { min: opts[:min], max: opts[:max], keepalive: opts[:keepalive],
+          {
+            min: opts[:min], max: opts[:max], keepalive: opts[:keepalive],
             write_ratio: opts[:write_ratio], fail: opts[:fail],
             threads: opts[:threads]
           }.delete_if { |_k, v| v.nil? }