google-cloud-spanner 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe7bf5ea7f7d653d908671aa73e72ae3f2916e045daace8dafcfdf13a56a886b
-  data.tar.gz: 20347421634b0f6e1ece36c787f62bb99bf5388b2ae2f873f06f38cc79dda647
+  metadata.gz: 3ed2386d9ad779724db65c4f41c42e78271e5cd94fe6785bb576083057b8cfae
+  data.tar.gz: 19a748cfaf89324614928996273a424aa0416d3804c60aa86eb6404736f2c30e
 SHA512:
-  metadata.gz: ec44b85b8bd9455526338e7c5f41872755ebbc1427110bee0c346b1dbcd2a1311aa867e02b08f495503f85306f30360afc3f8896ea5b0318bfc74740cb346db8
-  data.tar.gz: '08df6524da2309df130b8b4ad12ef3ed8a736511087d8bb2b1164146a332c6056136a65bb7a792ce03f8c24bb55884837b60d15111007883d9fe75547f53f114'
+  metadata.gz: bd287ff170bdd0c48aad7407b8a7cf92af5e0cc1479396a477c579e01d15de61c5f8d1e935fd54bff9ed035f35f66788aaec17b26a96695374d203644702fa88
+  data.tar.gz: 4fe37f4d9e0b166a941fb631704e43e54a698e1eba6b74d7c16b2afc7fc6dc9e5b39e947e3f3a99d2035302f8eb2949913fca2e35fb922942f2f74599c125ecf

data/lib/google-cloud-spanner.rb

@@ -20,6 +20,8 @@
 
 gem "google-cloud-core"
 require "google/cloud"
+require "google/cloud/config"
+require "googleauth"
 
 module Google
   module Cloud
@@ -107,3 +109,26 @@ module Google
     end
   end
 end
+
+# Set the default spanner configuration
+Google::Cloud.configure.add_config! :spanner do |config|
+  default_project = Google::Cloud::Config.deferred do
+    ENV["SPANNER_PROJECT"]
+  end
+  default_creds = Google::Cloud::Config.deferred do
+    Google::Cloud::Config.credentials_from_env(
+      "SPANNER_CREDENTIALS", "SPANNER_CREDENTIALS_JSON",
+      "SPANNER_KEYFILE", "SPANNER_KEYFILE_JSON"
+    )
+  end
+
+  config.add_field! :project_id, default_project, match: String, allow_nil: true
+  config.add_alias! :project, :project_id
+  config.add_field! :credentials, default_creds,
+                    match: [String, Hash, Google::Auth::Credentials],
+                    allow_nil: true
+  config.add_alias! :keyfile, :credentials
+  config.add_field! :scope, nil, match: [String, Array]
+  config.add_field! :timeout, nil, match: Integer
+  config.add_field! :client_config, nil, match: Hash
+end

data/lib/google/cloud/spanner.rb

@@ -15,6 +15,8 @@
 
 require "google-cloud-spanner"
 require "google/cloud/spanner/project"
+require "google/cloud/config"
+require "google/cloud/env"
 
 module Google
   module Cloud
@@ -30,11 +32,12 @@ module Google
     # Spanner Documentation](https://cloud.google.com/spanner/docs/).
     #
     # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#spanner}. You can
-    # provide the project and credential information to connect to the Cloud
-    # Spanner service, or if you are running on Google Compute Engine this
-    # configuration is taken care of for you. You can read more about the
-    # options for connecting in the [Authentication
+    # Rubyists. Your authentication credentials are detected automatically in
+    # Google Cloud Platform environments such as Google Compute Engine, Google
+    # App Engine and Google Kubernetes Engine. In other environments you can
+    # configure authentication easily, either directly in your code or via
+    # environment variables. Read more about the options for connecting in the
+    # [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
     # ## Creating instances
@@ -61,7 +64,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
     # ```
     #
     # ## Creating databases
@@ -83,7 +91,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
     # ```
     #
     # ## Updating database schemas
@@ -370,11 +383,14 @@ module Google
       #
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    client_config: nil, project: nil, keyfile: nil
-        project_id ||= (project || Spanner::Project.default_project_id)
+        project_id ||= (project || default_project_id)
         project_id = project_id.to_s # Always cast to a string
-        fail ArgumentError, "project_id is missing" if project_id.empty?
+        raise ArgumentError, "project_id is missing" if project_id.empty?
 
-        credentials ||= (keyfile || Spanner::Credentials.default(scope: scope))
+        scope ||= configure.scope
+        timeout ||= configure.timeout
+        client_config ||= configure.client_config
+        credentials ||= (keyfile || default_credentials(scope: scope))
         unless credentials.is_a? Google::Auth::Credentials
           credentials = Spanner::Credentials.new credentials, scope: scope
         end
@@ -382,7 +398,51 @@ module Google
         Spanner::Project.new(
           Spanner::Service.new(
             project_id, credentials, timeout: timeout,
-                                     client_config: client_config))
+                                     client_config: client_config
+          )
+        )
+      end
+
+      ##
+      # Configure the Google Cloud Spanner library.
+      #
+      # The following Spanner configuration parameters are supported:
+      #
+      # * `project_id` - (String) Identifier for a Spanner project. (The
+      #   parameter `project` is considered deprecated, but may also be used.)
+      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Spanner::Credentials}) (The
+      #   parameter `keyfile` is considered deprecated, but may also be used.)
+      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      # * `timeout` - (Integer) Default timeout to use in requests.
+      # * `client_config` - (Hash) A hash of values to override the default
+      #   behavior of the API client.
+      #
+      # @return [Google::Cloud::Config] The configuration object the
+      #   Google::Cloud::Spanner library uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.spanner if block_given?
+
+        Google::Cloud.configure.spanner
+      end
+
+      ##
+      # @private Default project.
+      def self.default_project_id
+        Google::Cloud.configure.spanner.project_id ||
+          Google::Cloud.configure.project_id ||
+          Google::Cloud.env.project_id
+      end
+
+      ##
+      # @private Default credentials.
+      def self.default_credentials scope: nil
+        Google::Cloud.configure.spanner.credentials ||
+          Google::Cloud.configure.credentials ||
+          Spanner::Credentials.default(scope: scope)
       end
     end
   end

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

@@ -0,0 +1,355 @@
+# 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 "google/cloud/spanner/errors"
+require "google/cloud/spanner/project"
+require "google/cloud/spanner/session"
+require "google/cloud/spanner/batch_snapshot"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # BatchClient
+      #
+      # Provides a batch client that can be used to read data from a Cloud
+      # Spanner database. An instance of this class is tied to a specific
+      # database.
+      #
+      # BatchClient is useful when one wants to read or query a large amount of
+      # data from Cloud Spanner across multiple processes, even across different
+      # machines. It allows to create partitions of Cloud Spanner database and
+      # then read or query over each partition independently yet at the same
+      # snapshot.
+      #
+      # See {Google::Cloud::Spanner::Project#batch_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
+      #
+      #   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
+      #
+      class BatchClient
+        ##
+        # @private Creates a new Spanner BatchClient instance.
+        def initialize project, instance_id, database_id
+          @project = project
+          @instance_id = instance_id
+          @database_id = database_id
+        end
+
+        # The unique identifier for the project.
+        # @return [String]
+        def project_id
+          @project.service.project
+        end
+
+        # The unique identifier for the instance.
+        # @return [String]
+        def instance_id
+          @instance_id
+        end
+
+        # The unique identifier for the database.
+        # @return [String]
+        def database_id
+          @database_id
+        end
+
+        # The Spanner project connected to.
+        # @return [Project]
+        def project
+          @project
+        end
+
+        # The Spanner instance connected to.
+        # @return [Instance]
+        def instance
+          @project.instance instance_id
+        end
+
+        # The Spanner database connected to.
+        # @return [Database]
+        def database
+          @project.database instance_id, database_id
+        end
+
+        ##
+        # Returns a {BatchSnapshot} context in which multiple reads and/or
+        # queries can be performed. All reads/queries will use the same
+        # timestamp, and the timestamp can be inspected after this transaction
+        # is created successfully. This is a blocking method since it waits to
+        # finish the RPCs.
+        #
+        # @param [true, false] strong Read at a timestamp where all previously
+        #   committed transactions are visible.
+        # @param [Time, DateTime] timestamp Executes all reads at the given
+        #   timestamp. Unlike other modes, reads at a specific timestamp are
+        #   repeatable; the same read at the same timestamp always returns the
+        #   same data. If the timestamp is in the future, the read will block
+        #   until the specified timestamp, modulo the read's deadline.
+        #
+        #   Useful for large scale consistent reads such as mapreduces, or for
+        #   coordinating many reads against a consistent snapshot of the data.
+        #   (See
+        #   [TransactionOptions](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#transactionoptions).)
+        # @param [Time, DateTime] read_timestamp Same as `timestamp`.
+        # @param [Numeric] staleness Executes all reads at a timestamp that is
+        #   `staleness` seconds old. For example, the number 10.1 is translated
+        #   to 10 seconds and 100 milliseconds.
+        #
+        #   Guarantees that all writes that have committed more than the
+        #   specified number of seconds ago are visible. Because Cloud Spanner
+        #   chooses the exact timestamp, this mode works even if the client's
+        #   local clock is substantially skewed from Cloud Spanner commit
+        #   timestamps.
+        #
+        #   Useful for reading at nearby replicas without the distributed
+        #   timestamp negotiation overhead of single-use `staleness`. (See
+        #   [TransactionOptions](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#transactionoptions).)
+        # @param [Numeric] exact_staleness Same as `staleness`.
+        #
+        # @yield [snapshot] The block for reading and writing data.
+        # @yieldparam [Google::Cloud::Spanner::Snapshot] snapshot The Snapshot
+        #   object.
+        #
+        # @return [Google::Cloud::Spanner::BatchSnapshot]
+        #
+        # @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 batch_snapshot strong: nil, timestamp: nil, read_timestamp: nil,
+                           staleness: nil, exact_staleness: nil
+          validate_snapshot_args! strong: strong, timestamp: timestamp,
+                                  read_timestamp: read_timestamp,
+                                  staleness: staleness,
+                                  exact_staleness: exact_staleness
+
+          ensure_service!
+          snp_session = session
+          snp_grpc = @project.service.create_snapshot \
+            snp_session.path, strong: strong,
+                              timestamp: (timestamp || read_timestamp),
+                              staleness: (staleness || exact_staleness)
+          BatchSnapshot.from_grpc snp_grpc, snp_session
+        end
+
+        ##
+        # Returns a {BatchSnapshot} context in which multiple reads and/or
+        # queries can be performed. All reads/queries will use the same
+        # timestamp, and the timestamp can be inspected after this transaction
+        # is created successfully. This method does not perform an RPC.
+        #
+        # @param [String] serialized_snapshot The serialized representation of
+        #   an existing batch snapshot. See {BatchSnapshot#dump}.
+        #
+        # @return [Google::Cloud::Spanner::BatchSnapshot]
+        #
+        # @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 load_batch_snapshot serialized_snapshot
+          ensure_service!
+
+          BatchSnapshot.load serialized_snapshot, service: @project.service
+        end
+
+        ##
+        # Returns a {Partition} from a serialized representation. See
+        # {Partition.load}.
+        #
+        # @param [String] serialized_partition 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 = batch_client.load_partition \
+        #     serialized_partition
+        #
+        #   results = new_batch_snapshot.execute_partition \
+        #     new_partition
+        #
+        def load_partition serialized_partition
+          Partition.load serialized_partition
+        end
+
+        ##
+        # Creates a Spanner Range. This can be used in place of a Ruby Range
+        # when needing to exclude the beginning value.
+        #
+        # @param [Object] beginning The object that defines the beginning of the
+        #   range.
+        # @param [Object] ending The object that defines the end of the range.
+        # @param [Boolean] exclude_begin Determines if the range excludes its
+        #   beginning value. Default is `false`.
+        # @param [Boolean] exclude_end Determines if the range excludes its
+        #   ending value. Default is `false`.
+        #
+        # @return [Google::Cloud::Spanner::Range] The new Range instance.
+        #
+        # @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
+        #
+        #   key_range = batch_client.range 1, 100
+        #
+        #   partitions = batch_snapshot.partition_read "users", [:id, :name],
+        #                                           keys: key_range
+        #
+        def range beginning, ending, exclude_begin: false, exclude_end: false
+          Range.new beginning, ending,
+                    exclude_begin: exclude_begin,
+                    exclude_end: exclude_end
+        end
+
+        # @private
+        def to_s
+          "(project_id: #{project_id}, instance_id: #{instance_id}, " \
+            "database_id: #{database_id})"
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name} #{self}>"
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          raise "Must have active connection to service" unless @project.service
+        end
+
+        ##
+        # New session for each use.
+        def session
+          ensure_service!
+          grpc = @project.service.create_session \
+            Admin::Database::V1::DatabaseAdminClient.database_path(
+              project_id, instance_id, database_id
+            )
+          Session.from_grpc(grpc, @project.service)
+        end
+
+        ##
+        # Check for valid snapshot arguments
+        def validate_snapshot_args! strong: nil,
+                                    timestamp: nil, read_timestamp: nil,
+                                    staleness: nil, exact_staleness: nil
+          valid_args_count = [strong, timestamp, read_timestamp, staleness,
+                              exact_staleness].compact.count
+          return true if valid_args_count <= 1
+          raise ArgumentError,
+                "Can only provide one of the following arguments: " \
+                "(strong, timestamp, read_timestamp, staleness, " \
+                "exact_staleness)"
+        end
+      end
+    end
+  end
+end