google-cloud-spanner 1.0.0 → 1.1.0

data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/policy.rb

@@ -45,7 +45,7 @@ module Google
       #     }
       #
       # For a description of IAM and its features, see the
-      # {IAM developer's guide}[https://cloud.google.com/iam].
+      # [IAM developer's guide](https://cloud.google.com/iam).
       # @!attribute [rw] version
       #   @return [Integer]
       #     Version of the +Policy+. The default version is 0.
@@ -80,23 +80,23 @@ module Google
       #     +members+ can have the following values:
       #
       #     * +allUsers+: A special identifier that represents anyone who is
-      #        on the internet; with or without a Google account.
+      #       on the internet; with or without a Google account.
       #
       #     * +allAuthenticatedUsers+: A special identifier that represents anyone
-      #        who is authenticated with a Google account or a service account.
+      #       who is authenticated with a Google account or a service account.
       #
       #     * +user:{emailid}+: An email address that represents a specific Google
-      #        account. For example, +alice@gmail.com+ or +joe@example.com+.
+      #       account. For example, +alice@gmail.com+ or +joe@example.com+.
       #
       #
       #     * +serviceAccount:{emailid}+: An email address that represents a service
-      #        account. For example, +my-other-app@appspot.gserviceaccount.com+.
+      #       account. For example, +my-other-app@appspot.gserviceaccount.com+.
       #
       #     * +group:{emailid}+: An email address that represents a Google group.
-      #        For example, +admins@example.com+.
+      #       For example, +admins@example.com+.
       #
       #     * +domain:{domain}+: A Google Apps domain name that represents all the
-      #        users of that domain. For example, +google.com+ or +example.com+.
+      #       users of that domain. For example, +google.com+ or +example.com+.
       class Binding; end
 
       # The difference delta between two policies.
@@ -136,4 +136,4 @@ module Google
       end
     end
   end
-end
+end

data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/any.rb

@@ -49,6 +49,16 @@ module Google
     #       any.Unpack(foo)
     #       ...
     #
+    #  Example 4: Pack and unpack a message in Go
+    #
+    #      foo := &pb.Foo{...}
+    #      any, err := ptypes.MarshalAny(foo)
+    #      ...
+    #      foo := &pb.Foo{}
+    #      if err := ptypes.UnmarshalAny(any, foo); err != nil {
+    #        ...
+    #      }
+    #
     # The pack methods provided by protobuf library will by default use
     # 'type.googleapis.com/full.type.name' as the type URL and the unpack
     # methods only use the fully qualified type name after the last '/'
@@ -77,7 +87,7 @@ module Google
     # If the embedded message type is well-known and has a custom JSON
     # representation, that representation will be embedded adding a field
     # +value+ which holds the custom JSON in addition to the +@type+
-    # field. Example (for message Google::Protobuf::Duration):
+    # field. Example (for message {Google::Protobuf::Duration}):
     #
     #     {
     #       "@type": "type.googleapis.com/google.protobuf.Duration",
@@ -96,7 +106,7 @@ module Google
     #       qualified name of the type (as in +path/google.protobuf.Duration+).
     #       The name should be in a canonical form (e.g., leading "." is
     #       not accepted).
-    #     * An HTTP GET on the URL must yield a Google::Protobuf::Type
+    #     * An HTTP GET on the URL must yield a {Google::Protobuf::Type}
     #       value in binary format, or produce an error.
     #     * Applications are allowed to cache lookup results based on the
     #       URL, or have them precompiled into a binary to avoid any

data/lib/google/cloud/spanner/admin/database/v1/doc/google/rpc/status.rb

@@ -16,22 +16,22 @@ module Google
   module Rpc
     # The +Status+ type defines a logical error model that is suitable for different
     # programming environments, including REST APIs and RPC APIs. It is used by
-    # {gRPC}[https://github.com/grpc]. The error model is designed to be:
+    # [gRPC](https://github.com/grpc). The error model is designed to be:
     #
-    # - Simple to use and understand for most users
-    # - Flexible enough to meet unexpected needs
+    # * Simple to use and understand for most users
+    # * Flexible enough to meet unexpected needs
     #
     # = Overview
     #
     # The +Status+ message contains three pieces of data: error code, error message,
     # and error details. The error code should be an enum value of
-    # Google::Rpc::Code, but it may accept additional error codes if needed.  The
+    # {Google::Rpc::Code}, but it may accept additional error codes if needed.  The
     # error message should be a developer-facing English message that helps
     # developers *understand* and *resolve* the error. If a localized user-facing
     # error message is needed, put the localized message in the error details or
     # localize it in the client. The optional error details may contain arbitrary
     # information about the error. There is a predefined set of error detail types
-    # in the package +google.rpc+ which can be used for common error conditions.
+    # in the package +google.rpc+ that can be used for common error conditions.
     #
     # = Language mapping
     #
@@ -49,35 +49,35 @@ module Google
     #
     # Example uses of this error model include:
     #
-    # - Partial errors. If a service needs to return partial errors to the client,
-    #     it may embed the +Status+ in the normal response to indicate the partial
-    #     errors.
+    # * Partial errors. If a service needs to return partial errors to the client,
+    #   it may embed the +Status+ in the normal response to indicate the partial
+    #   errors.
     #
-    # - Workflow errors. A typical workflow has multiple steps. Each step may
-    #     have a +Status+ message for error reporting purpose.
+    # * Workflow errors. A typical workflow has multiple steps. Each step may
+    #   have a +Status+ message for error reporting.
     #
-    # - Batch operations. If a client uses batch request and batch response, the
-    #     +Status+ message should be used directly inside batch response, one for
-    #     each error sub-response.
+    # * Batch operations. If a client uses batch request and batch response, the
+    #   +Status+ message should be used directly inside batch response, one for
+    #   each error sub-response.
     #
-    # - Asynchronous operations. If an API call embeds asynchronous operation
-    #     results in its response, the status of those operations should be
-    #     represented directly using the +Status+ message.
+    # * Asynchronous operations. If an API call embeds asynchronous operation
+    #   results in its response, the status of those operations should be
+    #   represented directly using the +Status+ message.
     #
-    # - Logging. If some API errors are stored in logs, the message +Status+ could
-    #     be used directly after any stripping needed for security/privacy reasons.
+    # * Logging. If some API errors are stored in logs, the message +Status+ could
+    #   be used directly after any stripping needed for security/privacy reasons.
     # @!attribute [rw] code
     #   @return [Integer]
-    #     The status code, which should be an enum value of Google::Rpc::Code.
+    #     The status code, which should be an enum value of {Google::Rpc::Code}.
     # @!attribute [rw] message
     #   @return [String]
     #     A developer-facing error message, which should be in English. Any
     #     user-facing error message should be localized and sent in the
-    #     Google::Rpc::Status#details field, or localized by the client.
+    #     {Google::Rpc::Status#details} field, or localized by the client.
     # @!attribute [rw] details
     #   @return [Array<Google::Protobuf::Any>]
-    #     A list of messages that carry the error details.  There will be a
-    #     common set of message types for APIs to use.
+    #     A list of messages that carry the error details.  There is a common set of
+    #     message types for APIs to use.
     class Status; end
   end
 end

data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/spanner_database_admin.rb

@@ -16,6 +16,17 @@ module Google
   module Spanner
     module Admin
       module Database
+        ##
+        # # Cloud Spanner Database Admin API Contents
+        #
+        # | Class | Description |
+        # | ----- | ----------- |
+        # | [DatabaseAdminClient][] |  |
+        # | [Data Types][] | Data types for Google::Cloud::Spanner::Admin::Database::V1 |
+        #
+        # [DatabaseAdminClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-spanner-admin-database/latest/google/spanner/admin/database/v1/databaseadminclient
+        # [Data Types]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-spanner-admin-database/latest/google/spanner/admin/database/v1/datatypes
+        #
         module V1
           # A Cloud Spanner database.
           # @!attribute [rw] name
@@ -43,7 +54,7 @@ module Google
             end
           end
 
-          # The request for ListDatabases.
+          # The request for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::ListDatabases ListDatabases}.
           # @!attribute [rw] parent
           #   @return [String]
           #     Required. The instance whose databases should be listed.
@@ -55,22 +66,22 @@ module Google
           # @!attribute [rw] page_token
           #   @return [String]
           #     If non-empty, +page_token+ should contain a
-          #     Next_page_token from a
-          #     previous ListDatabasesResponse.
+          #     {Google::Spanner::Admin::Database::V1::ListDatabasesResponse#next_page_token next_page_token} from a
+          #     previous {Google::Spanner::Admin::Database::V1::ListDatabasesResponse ListDatabasesResponse}.
           class ListDatabasesRequest; end
 
-          # The response for ListDatabases.
+          # The response for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::ListDatabases ListDatabases}.
           # @!attribute [rw] databases
           #   @return [Array<Google::Spanner::Admin::Database::V1::Database>]
           #     Databases that matched the request.
           # @!attribute [rw] next_page_token
           #   @return [String]
           #     +next_page_token+ can be sent in a subsequent
-          #     ListDatabases call to fetch more
+          #     {Google::Spanner::Admin::Database::V1::DatabaseAdmin::ListDatabases ListDatabases} call to fetch more
           #     of the matching databases.
           class ListDatabasesResponse; end
 
-          # The request for CreateDatabase.
+          # The request for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::CreateDatabase CreateDatabase}.
           # @!attribute [rw] parent
           #   @return [String]
           #     Required. The name of the instance that will serve the new database.
@@ -80,6 +91,8 @@ module Google
           #     Required. A +CREATE DATABASE+ statement, which specifies the ID of the
           #     new database.  The database ID must conform to the regular expression
           #     +[a-z][a-z0-9_\-]*[a-z0-9]+ and be between 2 and 30 characters in length.
+          #     If the database ID is a reserved word or if it contains a hyphen, the
+          #     database ID must be enclosed in backticks (+ + +).
           # @!attribute [rw] extra_statements
           #   @return [Array<String>]
           #     An optional list of DDL statements to run inside the newly created
@@ -89,13 +102,13 @@ module Google
           class CreateDatabaseRequest; end
 
           # Metadata type for the operation returned by
-          # CreateDatabase.
+          # {Google::Spanner::Admin::Database::V1::DatabaseAdmin::CreateDatabase CreateDatabase}.
           # @!attribute [rw] database
           #   @return [String]
           #     The database being created.
           class CreateDatabaseMetadata; end
 
-          # The request for GetDatabase.
+          # The request for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::GetDatabase GetDatabase}.
           # @!attribute [rw] name
           #   @return [String]
           #     Required. The name of the requested database. Values are of the form
@@ -114,9 +127,9 @@ module Google
           # subsequent statements in the batch are automatically cancelled.
           #
           # Each batch of statements is assigned a name which can be used with
-          # the Operations API to monitor
+          # the {Google::Longrunning::Operations Operations} API to monitor
           # progress. See the
-          # Operation_id field for more
+          # {Google::Spanner::Admin::Database::V1::UpdateDatabaseDdlRequest#operation_id operation_id} field for more
           # details.
           # @!attribute [rw] database
           #   @return [String]
@@ -129,26 +142,26 @@ module Google
           #     If empty, the new update request is assigned an
           #     automatically-generated operation ID. Otherwise, +operation_id+
           #     is used to construct the name of the resulting
-          #     Operation.
+          #     {Google::Longrunning::Operation Operation}.
           #
           #     Specifying an explicit operation ID simplifies determining
           #     whether the statements were executed in the event that the
-          #     UpdateDatabaseDdl call is replayed,
-          #     or the return value is otherwise lost: the Database and
+          #     {Google::Spanner::Admin::Database::V1::DatabaseAdmin::UpdateDatabaseDdl UpdateDatabaseDdl} call is replayed,
+          #     or the return value is otherwise lost: the {Google::Spanner::Admin::Database::V1::UpdateDatabaseDdlRequest#database database} and
           #     +operation_id+ fields can be combined to form the
-          #     Name of the resulting
-          #     Longrunning::Operation: +<database>/operations/<operation_id>+.
+          #     {Google::Longrunning::Operation#name name} of the resulting
+          #     {Google::Longrunning::Operation longrunning::Operation}: +<database>/operations/<operation_id>+.
           #
           #     +operation_id+ should be unique within the database, and must be
           #     a valid identifier: +[a-z][a-z0-9_]*+. Note that
           #     automatically-generated operation IDs always begin with an
           #     underscore. If the named operation already exists,
-          #     UpdateDatabaseDdl returns
+          #     {Google::Spanner::Admin::Database::V1::DatabaseAdmin::UpdateDatabaseDdl UpdateDatabaseDdl} returns
           #     +ALREADY_EXISTS+.
           class UpdateDatabaseDdlRequest; end
 
           # Metadata type for the operation returned by
-          # UpdateDatabaseDdl.
+          # {Google::Spanner::Admin::Database::V1::DatabaseAdmin::UpdateDatabaseDdl UpdateDatabaseDdl}.
           # @!attribute [rw] database
           #   @return [String]
           #     The database being modified.
@@ -163,19 +176,19 @@ module Google
           #     timestamp for the statement +statements[i]+.
           class UpdateDatabaseDdlMetadata; end
 
-          # The request for DropDatabase.
+          # The request for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::DropDatabase DropDatabase}.
           # @!attribute [rw] database
           #   @return [String]
           #     Required. The database to be dropped.
           class DropDatabaseRequest; end
 
-          # The request for GetDatabaseDdl.
+          # The request for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::GetDatabaseDdl GetDatabaseDdl}.
           # @!attribute [rw] database
           #   @return [String]
           #     Required. The database whose schema we wish to get.
           class GetDatabaseDdlRequest; end
 
-          # The response for GetDatabaseDdl.
+          # The response for {Google::Spanner::Admin::Database::V1::DatabaseAdmin::GetDatabaseDdl GetDatabaseDdl}.
           # @!attribute [rw] statements
           #   @return [Array<String>]
           #     A list of formatted DDL statements defining the schema of the database

data/lib/google/cloud/spanner/admin/database/v1/doc/overview.rb

@@ -0,0 +1,57 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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.
+
+module Google
+  module Cloud
+    module Spanner
+      module Admin
+        # rubocop:disable LineLength
+
+        ##
+        # # Ruby Client for Cloud Spanner Database Admin API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+        #
+        # [Cloud Spanner Database Admin API][Product Documentation]:
+        #
+        # - [Product Documentation][]
+        #
+        # ## Quick Start
+        # In order to use this library, you first need to go through the following
+        # steps:
+        #
+        # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+        # 2. [Enable the Cloud Spanner Database Admin API.](https://console.cloud.google.com/apis/api/spanner-admin-database)
+        # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+        #
+        # ### Installation
+        # ```
+        # $ gem install google-cloud-spanner-admin-database
+        # ```
+        #
+        # ### Next Steps
+        # - Read the [Cloud Spanner Database Admin API Product documentation][Product Documentation]
+        #   to learn more about the product and see How-to Guides.
+        # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+        #   to see the full list of Cloud APIs that we cover.
+        #
+        # [Product Documentation]: https://cloud.google.com/spanner-admin-database
+        #
+        #
+        module Database
+          module V1
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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/gax"
+require "pathname"
+
+module Google
+  module Cloud
+    module Spanner
+      module Admin
+        # rubocop:disable LineLength
+
+        ##
+        # # Ruby Client for Cloud Spanner Instance Admin API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+        #
+        # [Cloud Spanner Instance Admin API][Product Documentation]:
+        #
+        # - [Product Documentation][]
+        #
+        # ## Quick Start
+        # In order to use this library, you first need to go through the following
+        # steps:
+        #
+        # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+        # 2. [Enable the Cloud Spanner Instance Admin API.](https://console.cloud.google.com/apis/api/spanner-admin-instance)
+        # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+        #
+        # ### Next Steps
+        # - Read the [Cloud Spanner Instance Admin API Product documentation][Product Documentation]
+        #   to learn more about the product and see How-to Guides.
+        # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+        #   to see the full list of Cloud APIs that we cover.
+        #
+        # [Product Documentation]: https://cloud.google.com/spanner-admin-instance
+        #
+        #
+        module Instance
+          # rubocop:enable LineLength
+
+          FILE_DIR = File.realdirpath(Pathname.new(__FILE__).join("..").join("instance"))
+
+          AVAILABLE_VERSIONS = Dir["#{FILE_DIR}/*"]
+            .select { |file| File.directory?(file) }
+            .select { |dir| Google::Gax::VERSION_MATCHER.match(File.basename(dir)) }
+            .select { |dir| File.exist?(dir + ".rb") }
+            .map { |dir| File.basename(dir) }
+
+          ##
+          # Cloud Spanner Instance Admin API
+          #
+          # The Cloud Spanner Instance Admin API can be used to create, delete,
+          # modify and list instances. Instances are dedicated Cloud Spanner serving
+          # and storage resources to be used by Cloud Spanner databases.
+          #
+          # Each instance has a "configuration", which dictates where the
+          # serving resources for the Cloud Spanner instance are located (e.g.,
+          # US-central, Europe). Configurations are created by Google based on
+          # resource availability.
+          #
+          # Cloud Spanner billing is based on the instances that exist and their
+          # sizes. After an instance exists, there are no additional
+          # per-database or per-operation charges for use of the instance
+          # (though there may be additional network bandwidth charges).
+          # Instances offer isolation: problems with databases in one instance
+          # will not affect other instances. However, within an instance
+          # databases can affect each other. For example, if one database in an
+          # instance receives a lot of requests and consumes most of the
+          # instance resources, fewer resources are available for other
+          # databases in that instance, and their performance may suffer.
+          #
+          # @param version [Symbol, String]
+          #   The major version of the service to be used. By default :v1
+          #   is used.
+          # @overload new(version:, credentials:, scopes:, client_config:, timeout:)
+          #   @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
+          #     Provides the means for authenticating requests made by the client. This parameter can
+          #     be many types.
+          #     A `Google::Auth::Credentials` uses a the properties of its represented keyfile for
+          #     authenticating requests made by this client.
+          #     A `String` will be treated as the path to the keyfile to be used for the construction of
+          #     credentials for this client.
+          #     A `Hash` will be treated as the contents of a keyfile to be used for the construction of
+          #     credentials for this client.
+          #     A `GRPC::Core::Channel` will be used to make calls through.
+          #     A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials
+          #     should already be composed with a `GRPC::Core::CallCredentials` object.
+          #     A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the
+          #     metadata for requests, generally, to give OAuth credentials.
+          #   @param scopes [Array<String>]
+          #     The OAuth scopes for this service. This parameter is ignored if
+          #     an updater_proc is supplied.
+          #   @param client_config [Hash]
+          #     A Hash for call options for each method. See
+          #     Google::Gax#construct_settings for the structure of
+          #     this data. Falls back to the default config if not specified
+          #     or the specified config is missing data points.
+          #   @param timeout [Numeric]
+          #     The default timeout, in seconds, for calls made through this client.
+          def self.new(*args, version: :v1, **kwargs)
+            unless AVAILABLE_VERSIONS.include?(version.to_s.downcase)
+              raise "The version: #{version} is not available. The available versions " \
+                "are: [#{AVAILABLE_VERSIONS.join(", ")}]"
+            end
+
+            require "#{FILE_DIR}/#{version.to_s.downcase}"
+            version_module = Google::Cloud::Spanner::Admin::Instance
+              .constants
+              .select {|sym| sym.to_s.downcase == version.to_s.downcase}
+              .first
+            Google::Cloud::Spanner::Admin::Instance.const_get(version_module).new(*args, **kwargs)
+          end
+        end
+      end
+    end
+  end
+end