google-cloud-spanner 1.14.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68e910df98ae5fce8c055a045ec853ff60dfa2d8d2de3d625cad423a17a48fbf
-  data.tar.gz: 8eb916b7a90df206630629a9b9be3e4f83a3f3dbc10df56e346647bd5008578a
+  metadata.gz: 49b3d879f62998284edf63a941432c67a8caebf708f2ef4df883a3f336dbc758
+  data.tar.gz: e6768ee6037df38c765f888f64a4b29cc192b8a30a1bbcf02d01240c3c228621
 SHA512:
-  metadata.gz: 8d58bf9e158e9aabe3a05366e3a68be9d07d3f864a7a799f80127f2e72b78340db6fd984fe48eb2e64cb593825b70eef2da5753fae819b3108f42052e24eb315
-  data.tar.gz: 1e1e8d72cdb03be22f10a5ff47c4a268927033986e9b1f6cae41872c8a5482c8d3eb61f6bac8ecb034903beab0f725d5cd38951b23593b9c9fc9d6dbe993c528
+  metadata.gz: 3c456f4ee2482f6b0c488c749f11b508092b9c2a9befe8a4c44c74d6321c3dc1be43a6abd4cfec56c1ca7d2312feb79998383537ebd20bbe6f3d0be10f6cf576
+  data.tar.gz: b31fad2484409183d77bb00e11ba3526fdb9d5ae6817e8a95af51f61e09d7d3635ac7e58c99fbbb4b862b49a3092d59f7e88505aa86cb509ab1d23447ebfb060

data/AUTHENTICATION.md

@@ -76,7 +76,7 @@ The environment variables that google-cloud-spanner checks for project ID are:
 1. `SPANNER_PROJECT`
 2. `GOOGLE_CLOUD_PROJECT`
 
-The environment variables that google-cloud-spanner checks for credentials are configured on {Google::Cloud::Spanner::V1::Credentials}:
+The environment variables that google-cloud-spanner checks for credentials are configured on `Google::Cloud::Spanner::V1::Spanner::Credentials`:
 
 1. `SPANNER_CREDENTIALS` - Path to JSON file, or JSON contents
 2. `SPANNER_KEYFILE` - Path to JSON file, or JSON contents

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Release History
 
+### 2.0.0 / 2020-07-23
+
+This is a major update that removes the "low-level" client interface code, and
+instead adds `google-cloud-spanner-v1`, `google-cloud-spanner-admin-database-v1`,
+and `google-cloud-spanner-admin-instance-v1` as dependencies.
+The new dependencies are rewritten low-level clients, produced by a next-
+generation client code generator, with improved performance and stability.
+
+This change should have no effect on the high-level interface that most users
+will use. The one exception is that the (mostly undocumented) `client_config`
+argument, for adjusting low-level parameters such as RPC retry settings on
+client objects, has been removed. If you need to adjust these parameters, use
+the configuration interface in low-level clients.
+
+Substantial changes have been made in the low-level interfaces, however. If you
+are using the low-level classes under the old `Google::Spanner::V1` module,
+please review the docs for the new `google-cloud-spanner-v1` gem. In particular:
+
+* Some classes have been renamed, notably the client class itself.
+* The client constructor takes a configuration block instead of configuration
+  keyword arguments.
+* All RPC method arguments are now keyword arguments.
+
+### 1.16.2 / 2020-05-28
+
+#### Documentation
+
+* Fix a few broken links
+
+### 1.16.1 / 2020-05-21
+
+#### Bug Fixes
+
+* Increased default timeouts to match clients in other languages
+* Run system tests against the emulator, skipping those not supported by the emulator
+* Do not require a key file when running against the emulator
+
+### 1.16.0 / 2020-03-20
+
+#### Features
+
+* Added support for backing up and restoring databases  ([#5053](https://www.github.com/googleapis/google-cloud-ruby/issues/5053))
+
+### 1.15.0 / 2020-03-15
+
+#### Features
+
+* Added support for query options ([#4907](https://www.github.com/googleapis/google-cloud-ruby/issues/4907))
+  * Added support for specifying the query optimizer version.
+* Support separate project setting for quota/billing
+
 ### 1.14.0 / 2020-02-18
 
 #### Features

data/CONTRIBUTING.md

@@ -53,7 +53,7 @@ there is a small amount of setup:
 In order to run code interactively, you can automatically load
 google-cloud-spanner and its dependencies in IRB. This requires that your
 developer environment has already been configured by following the steps
-described in the [Authentication Guide](AUTHENTICATION.md). An IRB console
+described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
 can be created with:
 
 ```sh
@@ -119,7 +119,7 @@ If you alter an example's title, you may encounter breaking tests.
 ### Spanner Acceptance Tests
 
 The Spanner acceptance tests interact with the live service API. Follow the
-instructions in the [Authentication Guide](AUTHENTICATION.md) for enabling
+instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
 the Spanner API. Occasionally, some API features may not yet be generally
 available, making it difficult for some contributors to successfully run the
 entire acceptance test suite. However, please ensure that you do successfully
@@ -127,7 +127,7 @@ run acceptance tests for any code areas covered by your pull request.
 
 To run the acceptance tests, first create and configure a project in the Google
 Developers Console, as described in the
-[Authentication Guide](AUTHENTICATION.md). Be sure to download the JSON KEY
+{file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY
 file. Make note of the PROJECT_ID and the KEYFILE location on your system.
 
 Before you can run the Spanner acceptance tests, you must first create indexes
@@ -184,5 +184,5 @@ $ bundle exec rake rubocop
 ## Code of Conduct
 
 Please note that this project is released with a Contributor Code of Conduct. By
-participating in this project you agree to abide by its terms. See
-[Code of Conduct](CODE_OF_CONDUCT.md) for more information.
+participating in this project you agree to abide by its terms. See the
+{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.

data/TROUBLESHOOTING.md

@@ -24,14 +24,8 @@ improved, *please* create a new issue on GitHub so we can talk about it.
 
   - [New issue][gh-ruby]
 
-Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
-can use the "ruby" channel for general Ruby questions, or use the
-"google-cloud-ruby" channel if you have questions about this gem in particular.
-
 [so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+spanner
 
 [gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+spanner%22
 
 [gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
-
-[slack-ruby]: https://gcp-slack.appspot.com/

data/lib/google-cloud-spanner.rb

@@ -43,8 +43,6 @@ module Google
     #   * `https://www.googleapis.com/auth/spanner`
     #   * `https://www.googleapis.com/auth/spanner.data`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
-    # @param [Hash] client_config A hash of values to override the default
-    #   behavior of the API client. Optional.
     # @param [String] lib_name Library name. This will be added as a prefix
     #   to the API call tracking header `x-goog-api-client` with provided
     #   lib version for telemetry. Optional. For example prefix looks like
@@ -75,11 +73,9 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   spanner = gcloud.spanner scope: platform_scope
     #
-    def spanner scope: nil, timeout: nil, client_config: nil, lib_name: nil,
-                lib_version: nil
+    def spanner scope: nil, timeout: nil, lib_name: nil, lib_version: nil
       Google::Cloud.spanner @project, @keyfile, scope: scope,
                                                 timeout: (timeout || @timeout),
-                                                client_config: client_config,
                                                 lib_name: lib_name,
                                                 lib_version: lib_version
     end
@@ -107,8 +103,6 @@ module Google
     #   * `https://www.googleapis.com/auth/spanner`
     #   * `https://www.googleapis.com/auth/spanner.data`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
-    # @param [Hash] client_config A hash of values to override the default
-    #   behavior of the API client. Optional.
     # @param [String] lib_name Library name. This will be added as a prefix
     #   to the API call tracking header `x-goog-api-client` with provided
     #   lib version for telemetry. Optional. For example prefix looks like
@@ -132,18 +126,18 @@ module Google
     #   spanner = Google::Cloud.spanner
     #
     def self.spanner project_id = nil, credentials = nil, scope: nil,
-                     timeout: nil, client_config: nil, lib_name: nil,
-                     lib_version: nil
+                     timeout: nil, lib_name: nil, lib_version: nil
       require "google/cloud/spanner"
       Google::Cloud::Spanner.new project_id: project_id,
                                  credentials: credentials,
                                  scope: scope, timeout: timeout,
-                                 client_config: client_config,
                                  lib_name: lib_name, lib_version: lib_version
     end
   end
 end
 
+# rubocop:disable Metrics/BlockLength
+
 # Set the default spanner configuration
 Google::Cloud.configure.add_config! :spanner do |config|
   default_project = Google::Cloud::Config.deferred do
@@ -159,17 +153,33 @@ Google::Cloud.configure.add_config! :spanner do |config|
     ENV["SPANNER_EMULATOR_HOST"]
   end
 
+  default_query_options = Google::Cloud::Config.deferred do
+    query_options = {}
+    optimizer_version = ENV["SPANNER_OPTIMIZER_VERSION"]
+    query_options[:optimizer_version] = optimizer_version if optimizer_version
+    query_options = nil if query_options.empty?
+    query_options
+  end
+
+  default_scopes = [
+    "https://www.googleapis.com/auth/cloud-platform",
+    "https://www.googleapis.com/auth/spanner.admin",
+    "https://www.googleapis.com/auth/spanner.data"
+  ]
+
   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! :scope, default_scopes, match: [String, Array]
   config.add_field! :timeout, nil, match: Integer
-  config.add_field! :client_config, nil, match: Hash
-  config.add_field! :endpoint, nil, match: String
+  config.add_field! :endpoint, "spanner.googleapis.com", match: String
   config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
   config.add_field! :lib_name, nil, match: String, allow_nil: true
   config.add_field! :lib_version, nil, match: String, allow_nil: true
+  config.add_field! :query_options, default_query_options, match: Hash, allow_nil: true
 end
+
+# rubocop:enable Metrics/BlockLength

data/lib/google/cloud/spanner.rb

@@ -59,8 +59,6 @@ module Google
       #   * `https://www.googleapis.com/auth/spanner`
       #   * `https://www.googleapis.com/auth/spanner.data`
       # @param [Integer] timeout Default timeout to use in requests. Optional.
-      # @param [Hash] client_config A hash of values to override the default
-      #   behavior of the API client. Optional.
       # @param [String] endpoint Override of the endpoint host name. Optional.
       #   If the param is nil, uses the default endpoint.
       # @param [String] project Alias for the `project_id` argument. Deprecated.
@@ -91,12 +89,11 @@ module Google
       #   spanner = Google::Cloud::Spanner.new
       #
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
-                   client_config: nil, endpoint: nil, project: nil, keyfile: nil,
+                   endpoint: nil, project: nil, keyfile: nil,
                    emulator_host: nil, lib_name: nil, lib_version: nil
         project_id    ||= (project || default_project_id)
         scope         ||= configure.scope
         timeout       ||= configure.timeout
-        client_config ||= configure.client_config
         endpoint      ||= configure.endpoint
         credentials   ||= (keyfile || default_credentials(scope: scope))
         emulator_host ||= configure.emulator_host
@@ -122,9 +119,10 @@ module Google
         Spanner::Project.new(
           Spanner::Service.new(
             project_id, credentials,
-            host: endpoint, timeout: timeout, client_config: client_config,
-            lib_name: lib_name, lib_version: lib_version
-          )
+            host: endpoint, timeout: timeout, lib_name: lib_name,
+            lib_version: lib_version
+          ),
+          query_options: configure.query_options
         )
       end
 
@@ -144,8 +142,6 @@ module Google
       # * `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.
       # * `endpoint` - (String) Override of the endpoint host name, or `nil`
       #   to use the default endpoint.
       # * `emulator_host` - (String) Host name of the emulator. Defaults to
@@ -183,4 +179,7 @@ module Google
       end
     end
   end
+
+  # @private
+  Spanner = Cloud::Spanner unless const_defined? :Spanner
 end

data/lib/google/cloud/spanner/admin/database/credentials.rb

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "googleauth"
+require "google/cloud/spanner/admin/database/v1/database_admin/credentials"
 
 module Google
   module Cloud
@@ -23,7 +23,7 @@ module Google
           ##
           # @deprecated Use version-specific credentials classes
           #
-          Credentials = Google::Cloud::Spanner::Admin::Database::V1::Credentials
+          Credentials = V1::DatabaseAdmin::Credentials
         end
       end
     end

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "googleauth"
+require "google/cloud/spanner/admin/instance/v1/instance_admin/credentials"
 
 module Google
   module Cloud
@@ -23,7 +23,7 @@ module Google
           ##
           # @deprecated Use version-specific credentials classes
           #
-          Credentials = Google::Cloud::Spanner::Admin::Instance::V1::Credentials
+          Credentials = V1::InstanceAdmin::Credentials
         end
       end
     end

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

@@ -0,0 +1,315 @@
+# Copyright 2020 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/backup/job"
+require "google/cloud/spanner/backup/list"
+require "google/cloud/spanner/backup/restore/job"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Backup
+      #
+      # A backup is a representation of Cloud Spanner database backup.
+      #
+      # See {Google::Cloud::Spanner::Instance#backups},
+      # {Google::Cloud::Spanner::Instance#backup}, and
+      # {Google::Cloud::Spanner::Database#create_backup}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #   database = spanner.database "my-instance", "my-database"
+      #
+      #   expire_time = Time.now + 36000
+      #   job = database.create_backup "my-backup", expire_time
+      #
+      #   job.done? #=> false
+      #   job.reload! # API call
+      #   job.done? #=> true
+      #
+      #   if job.error?
+      #     status = job.error
+      #   else
+      #     backup = job.backup
+      #   end
+      #
+      class Backup
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Backup instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+        end
+
+        ##
+        # The unique identifier for the project.
+        # @return [String]
+        def project_id
+          @grpc.name.split("/")[1]
+        end
+
+        ##
+        # The unique identifier for the instance.
+        # @return [String]
+        def instance_id
+          @grpc.name.split("/")[3]
+        end
+
+        ##
+        # The unique identifier for the backup.
+        # @return [String]
+        def backup_id
+          @grpc.name.split("/")[5]
+        end
+
+        ##
+        # Name of the database from which this backup was created.
+        # @return [String]
+        def database_id
+          @grpc.database.split("/")[5]
+        end
+
+        ##
+        # The full path for the backup. Values are of the form
+        # `projects/<project>/instances/<instance>/backups/<backup_id>`.
+        # @return [String]
+        def path
+          @grpc.name
+        end
+
+        ##
+        # The current backup state. Possible values are `:CREATING` and
+        # `:READY`.
+        # @return [Symbol]
+        def state
+          @grpc.state
+        end
+
+        ##
+        # The backup is still being created. A backup is not yet available
+        # for the database restore operation.
+        # @return [Boolean]
+        def creating?
+          state == :CREATING
+        end
+
+        ##
+        # The backup is created and can be used to restore a database.
+        # @return [Boolean]
+        def ready?
+          state == :READY
+        end
+
+        ##
+        # The expiration time of the backup, with microseconds granularity.
+        # @return [Time]
+        def expire_time
+          Convert.timestamp_to_time @grpc.expire_time
+        end
+
+        ##
+        # Update backup expiration time.
+        #
+        # Set expiration time of the backup, with microseconds granularity
+        # that must be at least 6 hours and at most 366 days from the time the
+        # request is received. Once the `expire_time` has passed, Cloud Spanner
+        # will delete the backup and free the resources used by the backup.
+        #
+        # @param [Time] time Backup expiration time.
+        # @raise [Google::Cloud::Error] if expire time is in past or update
+        #   call is aborted.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   backup.expire_time = Time.now + 36000
+        #   puts backup.expire_time
+        #
+        def expire_time= time
+          ensure_service!
+
+          expire_time_was = @grpc.expire_time
+          @grpc.expire_time = Convert.time_to_timestamp time
+          update_mask = Google::Protobuf::FieldMask.new paths: ["expire_time"]
+          @grpc = service.update_backup @grpc, update_mask
+        rescue Google::Cloud::Error => error
+          @grpc.expire_time = expire_time_was
+          raise error
+        end
+
+        ##
+        # Create time is approximately the time when the backup request was
+        # received.
+        # @return [Time]
+        def create_time
+          Convert.timestamp_to_time @grpc.create_time
+        end
+
+        ##
+        # Size of the backup in bytes.
+        # @return [Integer]
+        def size_in_bytes
+          @grpc.size_bytes
+        end
+
+        ##
+        # The instances of the restored databases that reference the backup.
+        # Referencing databases may exist in different instances.
+        # The existence of any referencing database prevents the backup from
+        # being deleted. When a restored database from the backup enters the
+        # `READY` state, the reference to the backup is removed.
+        #
+        # @return [Array<Google::Cloud::Spanner::Database>] Returns list of
+        #   referencing database instances.
+        #
+        # @example
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #
+        #   backup.referencing_databases.each do |database|
+        #     puts database.database_id
+        #   end
+        #
+        def referencing_databases
+          ensure_service!
+
+          @grpc.referencing_databases.map do |referencing_database|
+            segments = referencing_database.split "/"
+            database_grpc = service.get_database segments[3], segments[5]
+            Database.from_grpc database_grpc, service
+          end
+        end
+
+        ##
+        # Permanently deletes the backup.
+        #
+        # @return [Boolean] Returns `true` if the backup was deleted.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   backup.delete # true
+        #
+        def delete
+          ensure_service!
+          service.delete_backup instance_id, backup_id
+          true
+        end
+
+        ##
+        # Restores deleted database from the backup.
+        #
+        # @param [String] database_id The unique identifier for the database,
+        #   which cannot be changed after the database is created. Values are of
+        #   the form `[a-z][a-z0-9_\-]*[a-z0-9]` and must be between 2 and 30
+        #   characters in length. Required.
+        # @param [String] instance_id The name of the instance in which to
+        #   create the restored database. This instance must be in the same
+        #   project and have the same instance configuration as the instance
+        #   containing the source backup. Optional. Default value is same as a
+        #   backup instance.
+        # @return [Database] Restored database.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   job = backup.restore "my-restored-database"
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        # @example Restore database in provided instance id
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   job = backup.restore(
+        #     "my-restored-database",
+        #     instance_id: "other-instance"
+        #   )
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def restore database_id, instance_id: nil
+          ensure_service!
+
+          instance_id ||= self.instance_id
+
+          grpc = service.restore_database \
+            self.instance_id,
+            backup_id,
+            instance_id,
+            database_id
+          Restore::Job.from_grpc grpc, service
+        end
+
+        ##
+        # @private
+        # Creates a new Backup instance from a
+        # `Google::Cloud::Spanner::Admin::Database::V1::Backup`.
+        def self.from_grpc grpc, service
+          new grpc, service
+        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 service
+        end
+      end
+    end
+  end
+end