google-cloud-spanner 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0beabc13ee4d11f2c6c0cc632bcf78359fc6e9d090ae53beed550fd86409feca
-  data.tar.gz: c24820a5fafff86d5a668df2715ae6b81420fab10a4aea60654c48ae0456a502
+  metadata.gz: 18756346d168b932d199c46b4d4cdecfadb95949f033d03da083ed0b4527ab3a
+  data.tar.gz: 4adaf5992dc2be079f2b6d82bb5adc55b09b91af496b4651f0ba7e4eca784c9f
 SHA512:
-  metadata.gz: 4322a66151a30d42daaecbedbf3a49e78ca80b34d3c991f196beb2af3293ae173ce99ce7e49338e383dbe6da29c2ec9877c94e3ed6973d6935da07421bcdee61
-  data.tar.gz: d78c1bc68027481ddc8674a958df3e32a93191618829aa9a16fa87fb9d407d49c8243c9482fc07e39022d2c54144a6edc98d2934bde4736a7a276ed669e2d645
+  metadata.gz: 7e6bcb561edc3b947af1b7ce426b59483692a08566b50bd1bfe4e7a6c2174f26183fc42e830589201278e7af7af4563f14ca06f53251d4db27386d2c98fad712
+  data.tar.gz: 343a05ccc2f546fd99a2a9b759db7cce6903d40e60a71c800abf7cb00543be3cc35250b7dec1365ee424f0dca3d479b2105282de5091caeee8760f80ce0fc5b8

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 2.11.0 / 2021-12-10
+
+#### Features
+
+* add admin instance wrapper ([#16080](https://www.github.com/googleapis/google-cloud-ruby/issues/16080))
+* Updated benchwrapper and proto for spanner. ([#16152](https://www.github.com/googleapis/google-cloud-ruby/issues/16152))
+* use gRPC clients for instance/database management ([#13157](https://www.github.com/googleapis/google-cloud-ruby/issues/13157))
+* wrapper to create generated admin database client. ([#13456](https://www.github.com/googleapis/google-cloud-ruby/issues/13456))
+
 ### 2.10.1 / 2021-11-09
 
 #### Documentation

data/OVERVIEW.md

@@ -23,29 +23,36 @@ create an instance, you choose where your data is stored and how many nodes are
 used for your data. (For more information, see [Configuration
 Guide](https://googleapis.dev/ruby/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION.html).
 
-Use {Google::Cloud::Spanner::Project#create_instance Project#create_instance} to
-create an instance:
+Use {Google::Cloud::Spanner::Admin::Instance#instance_admin
+Client#create_instance} to create an instance:
 
 ```ruby
 require "google/cloud/spanner"
 
-spanner = Google::Cloud::Spanner.new
-
-job = spanner.create_instance "my-instance",
-                              name: "My Instance",
-                              config: "regional-us-central1",
-                              nodes: 5,
-                              labels: { production: :env }
-
-job.done? #=> false
-job.reload! # API call
-job.done? #=> true
-
-if job.error?
-  status = job.error
-else
-  instance = job.instance
-end
+instance_admin_client = \
+  Google::Cloud::Spanner::Admin::Instance.instance_admin project_id: "my-project"
+
+project_path = \
+  instance_admin_client.project_path project: "my-project"
+config_path = \
+  instance_admin_client.instance_config_path project: "my-project",
+  instance_config: "regional-us-central1"
+instance_path = \
+  instance_admin_client.instance_path project: "my-project",
+  instance: "my-instance"
+
+job = instance_admin_client.create_instance parent: project_path,
+  instance_id: "my-instance",
+  instance: Google::Cloud::Spanner::Admin::Instance::V1::Instance.new({
+    name: instance_path
+    display_name: "My Instance",
+    config: config_path,
+    node_count: 5,
+    labels: { "production": :env }
+  })
+
+job.wait_until_done!
+instance = job.results
 ```
 
 ## Creating databases
@@ -54,26 +61,23 @@ Now that you have created an instance, you can create a database. Cloud
 Spanner databases hold the tables and indexes that allow you to read and
 write data. You may create multiple databases in an instance.
 
-Use {Google::Cloud::Spanner::Project#create_database Project#create_database}
-(or {Google::Cloud::Spanner::Instance#create_database Instance#create_database})
-to create a database:
+Use {Google::Cloud::Spanner::Admin::Database#database_admin
+Client#create_database} to create a database:
 
 ```ruby
 require "google/cloud/spanner"
 
-spanner = Google::Cloud::Spanner.new
+db_admin_client = \
+  Google::Cloud::Spanner::Admin::Database.database_admin project_id: "my-project"
 
-job = spanner.create_database "my-instance", "my-database"
+instance_path = \
+  db_admin_client.instance_path project: "my-project", instance: "my-instance"
 
-job.done? #=> false
-job.reload! # API call
-job.done? #=> true
+job = db_admin_client.create_database parent: instance_path,
+  create_statement: "CREATE DATABASE my-database",
 
-if job.error?
-  status = job.error
-else
-  database = job.database
-end
+job.wait_until_done!
+database = job.results
 ```
 
 ## Updating database schemas
@@ -83,16 +87,19 @@ continues to serve traffic. Schema updates do not require taking the
 database offline and they do not lock entire tables or columns; you can
 continue writing data to the database during the schema update.
 
-Use {Google::Cloud::Spanner::Database#update Database#update} to execute one or
-more statements in Cloud Spanner's Data Definition Language (DDL):
+Use {Google::Cloud::Spanner::Admin::Database#database_admin
+Client#update_database_ddl} to execute one or more statements in Cloud Spanner's
+Data Definition Language (DDL):
 
 ```ruby
 require "google/cloud/spanner"
 
-spanner = Google::Cloud::Spanner.new
-
-database = spanner.database "my-instance", "my-database"
+db_admin_client = \
+  Google::Cloud::Spanner::Admin::Database.database_admin project_id: "my-project"
 
+db_path = db_admin_client.database_path project: "my-project",
+                                        instance: "my-instance",
+                                        database: "my-database"
 add_users_table_sql = %q(
   CREATE TABLE users (
     id INT64 NOT NULL,
@@ -102,13 +109,17 @@ add_users_table_sql = %q(
   ) PRIMARY KEY(id)
 )
 
-database.update statements: [add_users_table_sql]
+job = db_admin_client.update_database_ddl database: db_path,
+                                          statements: [add_users_table_sql]
+
+job.wait_until_done!
+database = job.results
 ```
 
 ## Creating clients
 
-In order to read and/or write data, you must create a database client. You can
-think of a client as a database connection: All of your interactions with Cloud
+In order to read and/or write data, you must create a data client. You can think
+of a client as a database connection: All of your interactions with Cloud
 Spanner data must go through a client. Typically you create a client when your
 application starts up, then you re-use that client to read, write, and execute
 transactions.
@@ -289,33 +300,41 @@ end
 
 ## Deleting databases
 
-Use {Google::Cloud::Spanner::Database#drop Database#drop} to delete a database:
+Use {Google::Cloud::Spanner::Admin::Database#database_admin
+Client#drop_database} to delete a database:
 
 ```ruby
 require "google/cloud/spanner"
 
-spanner = Google::Cloud::Spanner.new
+db_admin_client = \
+  Google::Cloud::Spanner::Admin::Database.database_admin project_id: "my-project"
 
-database = spanner.database "my-instance", "my-database"
-
-database.drop
+db_path = db_admin_client.database_path project: "my-project",
+                                        instance: "my-instance",
+                                        database: "my-database"
+db_admin_client.drop_database database: db_path
 ```
 
 ## Deleting instances
 
 When you delete an instance, all databases within it are automatically deleted.
 (If you only delete databases and not your instance, you will still incur
-charges for the instance.) Use {Google::Cloud::Spanner::Instance#delete
-Instance#delete} to delete an instance:
+charges for the instance.)
+
+Use {Google::Cloud::Spanner::Admin::Instance#instance_admin
+Client#delete_instance} to delete an instance:
 
 ```ruby
 require "google/cloud/spanner"
 
-spanner = Google::Cloud::Spanner.new
+instance_admin_client = \
+  Google::Cloud::Spanner::Admin::Instance.instance_admin project_id: "my-project"
 
-instance = spanner.instance "my-instance"
+instance_path = \
+  instance_admin_client.instance_path project: "my-project",
+                                      instance: "my-instance"
 
-instance.delete
+instance_admin_client.delete_instance name: instance_path
 ```
 
 ## Additional information

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

@@ -0,0 +1,321 @@
+# Copyright 2021 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"
+require "google/cloud/config"
+
+module Google
+  module Cloud
+    module Spanner
+      module Admin
+        module Database
+          ##
+          # Create a new client object for a DatabaseAdmin.
+          #
+          # This returns an instance of
+          # [Google::Cloud::Spanner::Admin::Database::V1::DatabaseAdmin::Client](https://googleapis.dev/ruby/google-cloud-spanner-admin-database-v1/latest/Google/Cloud/Spanner/Admin/Database/V1/DatabaseAdmin/Client.html)
+          # for version V1 of the API.
+          #
+          # ## About DatabaseAdmin
+          #
+          # Google Cloud Spanner Database Admin Service
+          #
+          # The Cloud Spanner Database Admin API can be used to create, drop, and
+          # list databases. It also enables updating the schema of pre-existing
+          # databases. It can be also used to create, delete and list backups for a
+          # database and to restore from an existing backup.
+          #
+          # For more information on connecting to Google Cloud see the
+          # {file:AUTHENTICATION.md Authentication Guide}.
+          #
+          # @param [String] project_id Project identifier for the Spanner service
+          #   you are connecting to. If not present, the default project for the
+          #   credentials is used.
+          # @param [String, Hash, Google::Auth::Credentials] 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})
+          #   If `emulator_host` is present, this becomes optional and the value is
+          #   internally overriden with `:this_channel_is_insecure`.
+          # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+          #   the set of resources and operations that the connection can access.
+          #   See [Using OAuth 2.0 to Access Google
+          #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+          #
+          #   The default scopes are:
+          #
+          #   * `https://www.googleapis.com/auth/spanner`
+          #   * `https://www.googleapis.com/auth/spanner.data`
+          # @param [Integer] timeout Default timeout to use in requests. Optional.
+          # @param [String] endpoint Override of the endpoint host name. Optional.
+          #   If the param is nil, uses `emulator_host` or the default endpoint.
+          # @param [String] project Alias for the `project_id` argument. Deprecated.
+          # @param [String] keyfile Alias for the `credentials` argument.
+          #   Deprecated.
+          # @param [String] emulator_host Spanner emulator host. Optional.
+          #   If the param is nil, uses the value of the `emulator_host` config.
+          # @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
+          #   `spanner-activerecord/0.0.1 gccl/1.13.1`. Here,
+          #   `spanner-activerecord/0.0.1` is provided custom library name and
+          #   version and `gccl/1.13.1` represents the Cloud Spanner Ruby library
+          #   with version.
+          # @param [String] lib_version Library version. This will be added as a
+          #   prefix to the API call tracking header `x-goog-api-client` with
+          #   provided lib name for telemetry. Optional. For example prefix look like
+          #   `spanner-activerecord/0.0.1 gccl/1.13.1`. Here,
+          #   `spanner-activerecord/0.0.1` is provided custom library name and
+          #   version and `gccl/1.13.1` represents the Cloud Spanner Ruby library
+          #   with version.
+          #
+          # @return [Admin::Database::V1::DatabaseAdmin::Client] A client object of version V1.
+          #
+          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+          def self.database_admin project_id: nil,
+                                  credentials: nil,
+                                  scope: nil,
+                                  timeout: 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
+            emulator_host ||= configure.emulator_host
+            endpoint      ||= emulator_host || configure.endpoint
+            credentials   ||= keyfile
+            lib_name      ||= configure.lib_name
+            lib_version   ||= configure.lib_version
+
+            if emulator_host
+              credentials = :this_channel_is_insecure
+            else
+              credentials ||= default_credentials scope: scope
+              unless credentials.is_a? Google::Auth::Credentials
+                credentials = Spanner::Credentials.new credentials, scope: scope
+              end
+
+              if credentials.respond_to? :project_id
+                project_id ||= credentials.project_id
+              end
+            end
+
+            project_id = project_id.to_s # Always cast to a string
+            raise ArgumentError, "project_id is missing" if project_id.empty?
+
+            Admin::Database::V1::DatabaseAdmin::Client.new do |config|
+              config.credentials = channel endpoint, credentials
+              config.timeout = timeout if timeout
+              config.endpoint = endpoint if endpoint
+              config.lib_name = lib_name_with_prefix lib_name, lib_version
+              config.lib_version = Google::Cloud::Spanner::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{project_id}" }
+            end
+          end
+          # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+
+          ##
+          # Configure the Google Cloud Spanner Database Admin library. This configuration can be
+          # applied globally to all clients.
+          #
+          # @example
+          #
+          # Modify the global config, setting the timeout to 10 seconds for all admin databases.
+          #
+          # require "google/cloud/spanner/admin/database"
+          #
+          # ::Google::Cloud::Spanner::Admin::Database.configure do |config|
+          #   config.timeout = 10.0
+          # end
+          #
+          # The following configuration parameters are supported:
+          #
+          # * `credentials` (*type:* `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.
+          # * `lib_name` (*type:* `String`) -
+          #   The library name as recorded in instrumentation and logging.
+          # * `lib_version` (*type:* `String`) -
+          #   The library version as recorded in instrumentation and logging.
+          # * `interceptors` (*type:* `Array<GRPC::ClientInterceptor>`) -
+          #   An array of interceptors that are run before calls are executed.
+          # * `timeout` (*type:* `Numeric`) -
+          #   Default timeout in seconds.
+          # * `emulator_host` - (String) Host name of the emulator. Defaults to
+          #   `ENV["SPANNER_EMULATOR_HOST"]`.
+          # * `metadata` (*type:* `Hash{Symbol=>String}`) -
+          #   Additional gRPC headers to be sent with the call.
+          # * `retry_policy` (*type:* `Hash`) -
+          #   The retry policy. The value is a hash with the following keys:
+          #     * `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+          #     * `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+          #     * `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+          #     * `:retry_codes` (*type:* `Array<String>`) -
+          #       The error codes that should trigger a retry.
+          #
+          # @return [::Google::Cloud::Config] The default configuration used by this library
+          #
+          def self.configure
+            @configure ||= begin
+              namespace = ["Google", "Cloud", "Spanner"]
+              parent_config = while namespace.any?
+                                parent_name = namespace.join "::"
+                                parent_const = const_get parent_name
+                                break parent_const.configure if parent_const.respond_to? :configure
+                                namespace.pop
+                              end
+
+              default_config = Database::Configuration.new parent_config
+              default_config
+            end
+            yield @configure if block_given?
+            @configure
+          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
+
+          ##
+          # @private gRPC channel.
+          def self.channel host, credentials
+            require "grpc"
+            GRPC::Core::Channel.new host, chan_args, chan_creds(credentials)
+          end
+
+          ##
+          # @private gRPC channel args.
+          def self.chan_args
+            { "grpc.service_config_disable_resolution" => 1 }
+          end
+
+          ##
+          # @private gRPC channel credentials
+          def self.chan_creds credentials
+            return credentials if credentials == :this_channel_is_insecure
+            require "grpc"
+            GRPC::Core::ChannelCredentials.new.compose \
+              GRPC::Core::CallCredentials.new credentials.client.updater_proc
+          end
+
+          ##
+          # @private Spanner client library version with the prefix.
+          def self.lib_name_with_prefix lib_name, lib_version
+            return "gccl" if [nil, "gccl"].include? lib_name
+
+            value = lib_name.dup
+            value << "/#{lib_version}" if lib_version
+            value << " gccl"
+          end
+
+          ##
+          # Configuration class for the Spanner Admin Database.
+          #
+          # This class provides control over timeouts, retry behavior,
+          # query options, and other low-level controls.
+          #
+          # @!attribute [rw] endpoint
+          #   The hostname or hostname:port of the service endpoint.
+          #   Defaults to `"spanner.googleapis.com"`.
+          #   @return [::String]
+          # @!attribute [rw] credentials
+          #   Credentials to send with calls. You may provide any of the following types:
+          #    *  (`String`) The path to a service account key file in JSON format
+          #    *  (`Hash`) A service account key as a Hash
+          #    *  (`Google::Auth::Credentials`) A googleauth credentials object
+          #       (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
+          #    *  (`Signet::OAuth2::Client`) A signet oauth2 client object
+          #       (see the [signet docs](https://googleapis.dev/ruby/signet/latest/Signet/OAuth2/Client.html))
+          #    *  (`GRPC::Core::Channel`) a gRPC channel with included credentials
+          #    *  (`GRPC::Core::ChannelCredentials`) a gRPC credentails object
+          #    *  (`nil`) indicating no credentials
+          #   @return [::Object]
+          # @!attribute [rw] scope
+          #   The OAuth scopes
+          #   @return [::Array<::String>]
+          # @!attribute [rw] lib_name
+          #   The library name as recorded in instrumentation and logging
+          #   @return [::String]
+          # @!attribute [rw] lib_version
+          #   The library version as recorded in instrumentation and logging
+          #   @return [::String]
+          # @!attribute [rw] interceptors
+          #   An array of interceptors that are run before calls are executed.
+          #   @return [::Array<::GRPC::ClientInterceptor>]
+          # @!attribute [rw] timeout
+          #   The call timeout in seconds.
+          #   @return [::Numeric]
+          # @!attribute [rw] metadata
+          #   Additional gRPC headers to be sent with the call.
+          #   @return [::Hash{::Symbol=>::String}]
+          # @!attribute [rw] retry_policy
+          #   The retry policy. The value is a hash with the following keys:
+          #    *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+          #    *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+          #    *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+          #    *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+          #       trigger a retry.
+          #   @return [::Hash]
+          # @!attribute [rw] quota_project
+          #   A separate project against which to charge quota.
+          #   @return [::String]
+          #
+          class Configuration
+            extend ::Gapic::Config
+
+            config_attr :endpoint,      "spanner.googleapis.com", ::String
+            config_attr :credentials,   nil do |value|
+              allowed = [::String, ::Hash, ::Google::Auth::Credentials, ::Signet::OAuth2::Client, nil]
+              allowed += [::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] if defined? ::GRPC
+              allowed.any? { |klass| klass === value }
+            end
+            config_attr :project_id,    nil, ::String, nil
+            config_attr :scope,         nil, ::String, ::Array, nil
+            config_attr :lib_name,      nil, ::String,  nil
+            config_attr :lib_version,   nil, ::String,  nil
+            config_attr :interceptors,  nil, ::Array,   nil
+            config_attr :timeout,       nil, ::Numeric, nil
+            config_attr :quota_project, nil, ::String,  nil
+            config_attr :emulator_host, nil, ::String,  nil
+            config_attr :query_options, nil, ::Hash,    nil
+            config_attr :metadata,      nil, ::Hash,    nil
+            config_attr :retry_policy,  nil, ::Hash,    nil
+
+            # @private
+            def initialize parent_config = nil
+              @parent_config = parent_config unless parent_config.nil?
+
+              yield self if block_given?
+            end
+          end
+        end
+      end
+    end
+  end
+end