google-cloud-spanner 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3ee5ad839567f029c785341f244eb62658f9091b21c80726d01818e9dc3a101
-  data.tar.gz: 0053e507b34ab229c633a813fdf06cd178b59ede0837cfe80eb5585441b05bac
+  metadata.gz: 554678bfa633745cd0aa9c547791adff72c5bae2ce3d213cecd0282f2ae225a6
+  data.tar.gz: 57db3883a4deea6fb737c268948814a7ce9327c2e0ddf63d93844e29a7cd3303
 SHA512:
-  metadata.gz: dff7a09f65d4365463441c63a743983ea7df392f7d42e7cdaf854890318a6b6b5067a193fbf292ac48e001e6a1eaa9df0d55b99193baa77178b9382479c8f7e4
-  data.tar.gz: da5288b36a9b8dc7c1dc26d6b92d51198f0acdea029ad2c9519f45671cb3f251d04e7b78562f1e87545ba825aa17e940d73a87b7b52fdd77b792630abbe6d17b
+  metadata.gz: 8439f0275421349e0515c64977f97e1ef71666396a7a23cdf00ce039128c2195df3347315ab01415b39e83e80736b77b0c716e6991c3c30fff575072bcadb327
+  data.tar.gz: ac6373f64013c739157cf3cd664a80585d3b3f9c9bafb805619de7bb748a4b205cabc649009d27fa763106710194889547ab46a7b366d7522da318d0c0d3b8e9

data/lib/google-cloud-spanner.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 ##
 # This file is here to be autorequired by bundler, so that the
 # Google::Cloud.spanner and Google::Cloud#spanner methods can be available, but
@@ -29,8 +30,8 @@ module Google
     # Creates a new object for connecting to the Spanner service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
     #
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
@@ -70,8 +71,8 @@ module Google
     # Creates a new object for connecting to the Spanner service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # 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

data/lib/google/cloud/spanner.rb

@@ -31,350 +31,7 @@ module Google
     # For more information about Cloud Spanner, read the [Cloud
     # Spanner Documentation](https://cloud.google.com/spanner/docs/).
     #
-    # The goal of google-cloud is to provide an API that is comfortable to
-    # 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).
-    #
-    # ## Enabling Logging
-    #
-    # To enable logging for this library, set the logger for the underlying
-    # [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The
-    # logger that you set may be a Ruby stdlib
-    # [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html)
-    # as shown below, or a
-    # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
-    # that will write logs to [Stackdriver
-    # Logging](https://cloud.google.com/logging/). See
-    # [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
-    # and the gRPC
-    # [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
-    # for additional information.
-    #
-    # Configuring a Ruby stdlib logger:
-    #
-    # ```ruby
-    # require "logger"
-    #
-    # module MyLogger
-    #   LOGGER = Logger.new $stderr, level: Logger::WARN
-    #   def logger
-    #     LOGGER
-    #   end
-    # end
-    #
-    # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
-    # module GRPC
-    #   extend MyLogger
-    # end
-    # ```
-    #
-    # ## Creating instances
-    #
-    # When you first use Cloud Spanner, you must create an instance, which is an
-    # allocation of resources that are used by Cloud Spanner databases. When you
-    # create an instance, you choose where your data is stored and how many
-    # nodes are used for your data. (For more information, see [Instance
-    # Configuration](https://cloud.google.com/spanner/docs/instance-configuration)).
-    #
-    # Use {Spanner::Project#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
-    # ```
-    #
-    # ## Creating databases
-    #
-    # 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 {Spanner::Project#create_database} (or
-    # {Spanner::Instance#create_database}) to create a database:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # job = spanner.create_database "my-instance", "my-database"
-    #
-    # job.done? #=> false
-    # job.reload! # API call
-    # job.done? #=> true
-    #
-    # if job.error?
-    #   status = job.error
-    # else
-    #   database = job.database
-    # end
-    # ```
-    #
-    # ## Updating database schemas
-    #
-    # Cloud Spanner supports schema updates to a database while the database
-    # 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 {Spanner::Database#update} 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"
-    #
-    # add_users_table_sql = %q(
-    #   CREATE TABLE users (
-    #     id INT64 NOT NULL,
-    #     username STRING(25) NOT NULL,
-    #     name STRING(45) NOT NULL,
-    #     email STRING(128),
-    #   ) PRIMARY KEY(id)
-    # )
-    #
-    # database.update statements: [add_users_table_sql]
-    # ```
-    #
-    # ## 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 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.
-    #
-    # Use {Spanner::Project#client} to create a client:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # results = db.execute "SELECT 1"
-    #
-    # results.rows.each do |row|
-    #   puts row
-    # end
-    # ```
-    #
-    # ## Writing data
-    #
-    # You write data using your client object. The client object supports
-    # various mutation operations, as well as combinations of inserts, updates,
-    # deletes, etc., that can be applied atomically to different rows and/or
-    # tables in a database.
-    #
-    # Use {Spanner::Client#commit} to execute various mutations atomically at a
-    # single logical point in time. All changes are accumulated in memory until
-    # the block completes. Unlike {Spanner::Client#transaction}, which can also
-    # perform reads, this operation accepts only mutations and makes a single
-    # API request.
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # db.commit do |c|
-    #   c.update "users", [{ id: 1, username: "charlie94", name: "Charlie" }]
-    #   c.insert "users", [{ id: 2, username: "harvey00", name: "Harvey" }]
-    # end
-    # ```
-    #
-    # ## Querying data using SQL
-    #
-    # Cloud Spanner supports a native SQL interface for reading data that is
-    # available through {Spanner::Client#execute}:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # results = db.execute "SELECT * FROM users"
-    #
-    # results.rows.each do |row|
-    #   puts "User #{row[:id]} is #{row[:name]}"
-    # end
-    # ```
-    #
-    # ## Reading data using the read method
-    #
-    # In addition to Cloud Spanner's SQL interface, Cloud Spanner also supports
-    # a read interface. Use the {Spanner::Client#read} method to read rows from
-    # the database, and use its `keys` option to pass unique identifiers as both
-    # lists and ranges:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # results = db.read "users", [:id, :name], keys: 1..5
-    #
-    # results.rows.each do |row|
-    #   puts "User #{row[:id]} is #{row[:name]}"
-    # end
-    # ```
-    #
-    # ## Using read-write transactions
-    #
-    # When an operation might write data depending on values it reads, you
-    # should use a read-write transaction to perform the reads and writes
-    # atomically.
-    #
-    # Suppose that sales of `Albums(1, 1)` are lower than expected and you want
-    # to move $200,000 from the marketing budget of `Albums(2, 2)` to it, but
-    # only if the budget of `Albums(2, 2)` is at least $300,000.
-    #
-    # Use {Spanner::Client#transaction} to execute both reads and writes
-    # atomically at a single logical point in time. All changes are accumulated
-    # in memory until the block completes. Transactions will be automatically
-    # retried when possible. This operation makes separate API requests to begin
-    # and commit the transaction.
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # db.transaction do |tx|
-    #   # Read the second album budget.
-    #   second_album_result = tx.read "Albums", ["marketing_budget"],
-    #                                 keys: [[2, 2]], limit: 1
-    #   second_album_row = second_album_result.rows.first
-    #   second_album_budget = second_album_row.values.first
-    #
-    #   transfer_amount = 200000
-    #
-    #   if second_album_budget < 300000
-    #     # Raising an exception will automatically roll back the transaction.
-    #     raise "The second album doesn't have enough funds to transfer"
-    #   end
-    #
-    #   # Read the first album's budget.
-    #   first_album_result = tx.read "Albums", ["marketing_budget"],
-    #                                 keys: [[1, 1]], limit: 1
-    #   first_album_row = first_album_result.rows.first
-    #   first_album_budget = first_album_row.values.first
-    #
-    #   # Update the budgets.
-    #   second_album_budget -= transfer_amount
-    #   first_album_budget += transfer_amount
-    #   puts "Setting first album's budget to #{first_album_budget} and the " \
-    #        "second album's budget to #{second_album_budget}."
-    #
-    #   # Update the rows.
-    #   rows = [
-    #     {singer_id: 1, album_id: 1, marketing_budget: first_album_budget},
-    #     {singer_id: 2, album_id: 2, marketing_budget: second_album_budget}
-    #   ]
-    #   tx.update "Albums", rows
-    # end
-    # ```
-    #
-    # ## Using read-only transactions
-    #
-    # Suppose you want to execute more than one read at the same timestamp.
-    # Read-only transactions observe a consistent prefix of the transaction
-    # commit history, so your application always gets consistent data. Because
-    # read-only transactions are much faster than locking read-write
-    # transactions, we strongly recommend that you do all of your transaction
-    # reads in read-only transactions if possible.
-    #
-    # Use a {Spanner::Snapshot} object to execute statements in a read-only
-    # transaction. The snapshot object is available via a block provided to
-    # {Spanner::Client#snapshot}:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # db = spanner.client "my-instance", "my-database"
-    #
-    # db.snapshot do |snp|
-    #   results_1 = snp.execute "SELECT * FROM users"
-    #   results_1.rows.each do |row|
-    #     puts "User #{row[:id]} is #{row[:name]}"
-    #   end
-    #
-    #   # Perform another read using the `read` method. Even if the data
-    #   # is updated in-between the reads, the snapshot ensures that both
-    #   # return the same data.
-    #   results_2 = db.read "users", [:id, :name]
-    #   results_2.rows.each do |row|
-    #     puts "User #{row[:id]} is #{row[:name]}"
-    #   end
-    # end
-    # ```
-    #
-    # ## Deleting databases
-    #
-    # Use {Spanner::Database#drop} to delete a database:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # database = spanner.database "my-instance", "my-database"
-    #
-    # database.drop
-    # ```
-    #
-    # ## 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 {Spanner::Instance#delete} to
-    # delete an instance:
-    #
-    # ```ruby
-    # require "google/cloud/spanner"
-    #
-    # spanner = Google::Cloud::Spanner.new
-    #
-    # instance = spanner.instance "my-instance"
-    #
-    # instance.delete
-    # ````
+    # See {file:OVERVIEW.md Spanner Overview}.
     #
     module Spanner
       ##
@@ -382,8 +39,7 @@ module Google
       # Each call creates a new connection.
       #
       # For more information on connecting to Google Cloud see the
-      # [Authentication
-      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+      # {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

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

@@ -1,4 +1,4 @@
-# Copyright 2017 Google LLC
+# 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.
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "google/gax"
 require "pathname"
 
@@ -34,17 +35,47 @@ module Google
         #
         # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
         # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
-        # 3. [Enable the Cloud Spanner Database Admin API.](https://console.cloud.google.com/apis/api/spanner-admin-database)
+        # 3. [Enable the Cloud Spanner Database Admin API.](https://console.cloud.google.com/apis/library/spanner.googleapis.com)
         # 4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
         #
+        # ### Installation
+        # ```
+        # $ gem install google-cloud-spanner
+        # ```
+        #
         # ### 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
+        # [Product Documentation]: https://cloud.google.com/spanner
+        #
+        # ## Enabling Logging
+        #
+        # To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library.
+        # The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below,
+        # or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
+        # that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+        # and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
+        #
+        # Configuring a Ruby stdlib logger:
+        #
+        # ```ruby
+        # require "logger"
+        #
+        # module MyLogger
+        #   LOGGER = Logger.new $stderr, level: Logger::WARN
+        #   def logger
+        #     LOGGER
+        #   end
+        # end
         #
+        # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+        # module GRPC
+        #   extend MyLogger
+        # end
+        # ```
         #
         module Database
           # rubocop:enable LineLength
@@ -92,6 +123,11 @@ module Google
           #     or the specified config is missing data points.
           #   @param timeout [Numeric]
           #     The default timeout, in seconds, for calls made through this client.
+          #   @param metadata [Hash]
+          #     Default metadata to be sent with each request. This can be overridden on a per call basis.
+          #   @param exception_transformer [Proc]
+          #     An optional proc that intercepts any exceptions raised during an API call to inject
+          #     custom error handling.
           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 " \