google-cloud-spanner 1.0.0 → 1.1.0

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

@@ -788,8 +788,8 @@ module Google
         #   [TransactionOptions](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#transactionoptions).)
         # @param [Time, DateTime] read_timestamp Same as `timestamp`.
         # @param [Numeric] staleness Executes all reads at a timestamp that is
-        #   +staleness+ old. The timestamp is chosen soon after the read
-        #   is started.
+        #   `staleness` seconds old. For example, the number 10.1 is translated
+        #   to 10 seconds and 100 milliseconds.
         #
         #   Guarantees that all writes that have committed more than the
         #   specified number of seconds ago are visible. Because Cloud Spanner
@@ -798,7 +798,7 @@ module Google
         #   timestamps.
         #
         #   Useful for reading at nearby replicas without the distributed
-        #   timestamp negotiation overhead of single-use +staleness+. (See
+        #   timestamp negotiation overhead of single-use `staleness`. (See
         #   [TransactionOptions](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#transactionoptions).)
         # @param [Numeric] exact_staleness Same as `staleness`.
         #

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

@@ -13,19 +13,45 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
-require "google/cloud/spanner/v1"
+require "googleauth"
 
 module Google
   module Cloud
     module Spanner
       ##
-      # @private Represents the OAuth 2.0 signing logic for Spanner.
-      class Credentials < Google::Cloud::Credentials
-        SCOPE = V1::SpannerClient::ALL_SCOPES
-        PATH_ENV_VARS = %w(SPANNER_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(SPANNER_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # Spanner API.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::Spanner::Credentials.new keyfile
+      #
+      #   spanner = Google::Cloud::Spanner.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   spanner.project_id #=> "my-project"
+      #
+      class Credentials < Google::Auth::Credentials
+        SCOPE = %w(https://www.googleapis.com/auth/cloud-platform
+                   https://www.googleapis.com/auth/spanner.data)
+        PATH_ENV_VARS = %w(SPANNER_CREDENTIALS
+                           SPANNER_KEYFILE
+                           GOOGLE_CLOUD_CREDENTIALS
+                           GOOGLE_CLOUD_KEYFILE
+                           GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(SPANNER_CREDENTIALS_JSON
+                           SPANNER_KEYFILE_JSON
+                           GOOGLE_CLOUD_CREDENTIALS_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = \
+          ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

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

@@ -64,22 +64,19 @@ module Google
         # The unique identifier for the project.
         # @return [String]
         def project_id
-          Admin::Database::V1::DatabaseAdminClient
-            .match_project_from_database_name @grpc.name
+          @grpc.name.split("/")[1]
         end
 
         # The unique identifier for the instance.
         # @return [String]
         def instance_id
-          Admin::Database::V1::DatabaseAdminClient
-            .match_instance_from_database_name @grpc.name
+          @grpc.name.split("/")[3]
         end
 
         # The unique identifier for the database.
         # @return [String]
         def database_id
-          Admin::Database::V1::DatabaseAdminClient
-            .match_database_from_database_name @grpc.name
+          @grpc.name.split("/")[5]
         end
 
         # rubocop:disable LineLength

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

@@ -69,15 +69,13 @@ module Google
         # The unique identifier for the project.
         # @return [String]
         def project_id
-          Admin::Instance::V1::InstanceAdminClient
-            .match_project_from_instance_name @grpc.name
+          @grpc.name.split("/")[1]
         end
 
         # The unique identifier for the instance.
         # @return [String]
         def instance_id
-          Admin::Instance::V1::InstanceAdminClient
-            .match_instance_from_instance_name @grpc.name
+          @grpc.name.split("/")[3]
         end
 
         ##

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

@@ -49,16 +49,14 @@ module Google
           # The unique identifier for the project.
           # @return [String]
           def project_id
-            Admin::Instance::V1::InstanceAdminClient
-              .match_project_from_instance_config_name @grpc.name
+            @grpc.name.split("/")[1]
           end
 
           ##
           # A unique identifier for the instance configuration.
           # @return [String]
           def instance_config_id
-            Admin::Instance::V1::InstanceAdminClient
-              .match_instance_config_from_instance_config_name @grpc.name
+            @grpc.name.split("/")[3]
           end
 
           ##

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

@@ -83,20 +83,20 @@ module Google
         #   require "google/cloud"
         #
         #   spanner = Google::Cloud::Spanner.new(
-        #     project: "my-project-id",
-        #     keyfile: "/path/to/keyfile.json"
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
         #   )
         #
-        #   spanner.project #=> "my-project-id"
+        #   spanner.project_id #=> "my-project"
         #
-        def project
+        def project_id
           service.project
         end
-        alias_method :project_id, :project
+        alias_method :project, :project_id
 
         ##
         # @private Default project.
-        def self.default_project
+        def self.default_project_id
           ENV["SPANNER_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||

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

@@ -28,37 +28,22 @@ module Google
       # @private Represents the gRPC Spanner service, including all the API
       # methods.
       class Service
-        attr_accessor :project, :credentials, :host, :timeout, :client_config
+        attr_accessor :project, :credentials, :timeout, :client_config
 
         ##
         # Creates a new Service instance.
-        def initialize project, credentials, host: nil, timeout: nil,
-                       client_config: nil
+        def initialize project, credentials, timeout: nil, client_config: nil
           @project = project
           @credentials = credentials
-          @host = host || V1::SpannerClient::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
         end
 
-        def channel
-          require "grpc"
-          GRPC::Core::Channel.new host, nil, chan_creds
-        end
-
-        def chan_creds
-          return credentials if insecure?
-          require "grpc"
-          GRPC::Core::ChannelCredentials.new.compose \
-            GRPC::Core::CallCredentials.new credentials.client.updater_proc
-        end
-
         def service
           return mocked_service if mocked_service
           @service ||= \
             V1::SpannerClient.new(
-              service_path: host,
-              channel: channel,
+              credentials: credentials,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -70,8 +55,7 @@ module Google
           return mocked_instances if mocked_instances
           @instances ||= \
             Admin::Instance::V1::InstanceAdminClient.new(
-              service_path: host,
-              channel: channel,
+              credentials: credentials,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -83,8 +67,7 @@ module Google
           return mocked_databases if mocked_databases
           @databases ||= \
             Admin::Database::V1::DatabaseAdminClient.new(
-              service_path: host,
-              channel: channel,
+              credentials: credentials,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -92,10 +75,6 @@ module Google
         end
         attr_accessor :mocked_databases
 
-        def insecure?
-          credentials == :this_channel_is_insecure
-        end
-
         def list_instances token: nil, max: nil
           call_options = nil
           call_options = Google::Gax::CallOptions.new page_token: token if token

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

@@ -57,25 +57,25 @@ module Google
         # The unique identifier for the project.
         # @return [String]
         def project_id
-          V1::SpannerClient.match_project_from_session_name @grpc.name
+          @grpc.name.split("/")[1]
         end
 
         # The unique identifier for the instance.
         # @return [String]
         def instance_id
-          V1::SpannerClient.match_instance_from_session_name @grpc.name
+          @grpc.name.split("/")[3]
         end
 
         # The unique identifier for the database.
         # @return [String]
         def database_id
-          V1::SpannerClient.match_database_from_session_name @grpc.name
+          @grpc.name.split("/")[5]
         end
 
         # The unique identifier for the session.
         # @return [String]
         def session_id
-          V1::SpannerClient.match_session_from_session_name @grpc.name
+          @grpc.name.split("/")[7]
         end
 
         # rubocop:disable LineLength

data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb

@@ -21,6 +21,8 @@ module Google
     # two Timestamp values is a Duration and it can be added or subtracted
     # from a Timestamp. Range is approximately +-10,000 years.
     #
+    # = Examples
+    #
     # Example 1: Compute Duration from two Timestamps in pseudo code.
     #
     #     Timestamp start = ...;
@@ -60,10 +62,21 @@ module Google
     #     td = datetime.timedelta(days=3, minutes=10)
     #     duration = Duration()
     #     duration.FromTimedelta(td)
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Duration type is encoded as a string rather than an
+    # object, where the string ends in the suffix "s" (indicating seconds) and
+    # is preceded by the number of seconds, with nanoseconds expressed as
+    # fractional seconds. For example, 3 seconds with 0 nanoseconds should be
+    # encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
+    # be expressed in JSON format as "3.000000001s", and 3 seconds and 1
+    # microsecond should be expressed in JSON format as "3.000001s".
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Signed seconds of the span of time. Must be from -315,576,000,000
-    #     to +315,576,000,000 inclusive.
+    #     to +315,576,000,000 inclusive. Note: these bounds are computed from:
+    #     60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
     # @!attribute [rw] nanos
     #   @return [Integer]
     #     Signed fractions of a second at nanosecond resolution of the span

data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb

@@ -24,7 +24,9 @@ module Google
     # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
     # By restricting to that range, we ensure that we can convert to
     # and from  RFC 3339 date strings.
-    # See {https://www.ietf.org/rfc/rfc3339.txt}[https://www.ietf.org/rfc/rfc3339.txt].
+    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    #
+    # = Examples
     #
     # Example 1: Compute Timestamp from POSIX +time()+.
     #
@@ -65,6 +67,29 @@ module Google
     #
     #     timestamp = Timestamp()
     #     timestamp.GetCurrentTime()
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Timestamp type is encoded as a string in the
+    # [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+    # format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
+    # where {year} is always expressed using four digits while {month}, {day},
+    # {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
+    # seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+    # are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+    # is required, though only UTC (as indicated by "Z") is presently supported.
+    #
+    # For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+    # 01:30 UTC on January 15, 2017.
+    #
+    # In JavaScript, one can convert a Date object to this format using the
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # method. In Python, a standard +datetime.datetime+ object can be converted
+    # to this format using [+strftime+](https://docs.python.org/2/library/time.html#time.strftime)
+    # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
+    # can use the Joda Time's [+ISODateTimeFormat.dateTime()+](
+    # http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime())
+    # to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Represents seconds of UTC time since Unix epoch

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb

@@ -22,7 +22,7 @@ module Google
       #
       # Keys are represented by lists, where the ith value in the list
       # corresponds to the ith component of the table or index primary key.
-      # Individual values are encoded as described Here.
+      # Individual values are encoded as described {Google::Spanner::V1::TypeCode here}.
       #
       # For example, consider the following table definition:
       #
@@ -132,10 +132,10 @@ module Google
       #     A list of specific keys. Entries in +keys+ should have exactly as
       #     many elements as there are columns in the primary or index key
       #     with which this +KeySet+ is used.  Individual key values are
-      #     encoded as described Here.
+      #     encoded as described {Google::Spanner::V1::TypeCode here}.
       # @!attribute [rw] ranges
       #   @return [Array<Google::Spanner::V1::KeyRange>]
-      #     A list of key ranges. See KeyRange for more information about
+      #     A list of key ranges. See {Google::Spanner::V1::KeyRange KeyRange} for more information about
       #     key range specifications.
       # @!attribute [rw] all
       #   @return [true, false]

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb

@@ -17,7 +17,7 @@ module Google
     module V1
       # A modification to one or more Cloud Spanner rows.  Mutations can be
       # applied to a Cloud Spanner database by sending them in a
-      # Commit call.
+      # {Google::Spanner::V1::Spanner::Commit Commit} call.
       # @!attribute [rw] insert
       #   @return [Google::Spanner::V1::Mutation::Write]
       #     Insert new rows in a table. If any of the rows already exist,
@@ -28,28 +28,28 @@ module Google
       #     already exist, the transaction fails with error +NOT_FOUND+.
       # @!attribute [rw] insert_or_update
       #   @return [Google::Spanner::V1::Mutation::Write]
-      #     Like Insert, except that if the row already exists, then
+      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row already exists, then
       #     its column values are overwritten with the ones provided. Any
       #     column values not explicitly written are preserved.
       # @!attribute [rw] replace
       #   @return [Google::Spanner::V1::Mutation::Write]
-      #     Like Insert, except that if the row already exists, it is
+      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row already exists, it is
       #     deleted, and the column values provided are inserted
-      #     instead. Unlike Insert_or_update, this means any values not
+      #     instead. Unlike {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, this means any values not
       #     explicitly written become +NULL+.
       # @!attribute [rw] delete
       #   @return [Google::Spanner::V1::Mutation::Delete]
       #     Delete rows from a table. Succeeds whether or not the named
       #     rows were present.
       class Mutation
-        # Arguments to Insert, Update, Insert_or_update, and
-        # Replace operations.
+        # Arguments to {Google::Spanner::V1::Mutation#insert insert}, {Google::Spanner::V1::Mutation#update update}, {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, and
+        # {Google::Spanner::V1::Mutation#replace replace} operations.
         # @!attribute [rw] table
         #   @return [String]
         #     Required. The table whose rows will be written.
         # @!attribute [rw] columns
         #   @return [Array<String>]
-        #     The names of the columns in Table to be written.
+        #     The names of the columns in {Google::Spanner::V1::Mutation::Write#table table} to be written.
         #
         #     The list of columns must contain enough columns to allow
         #     Cloud Spanner to derive values for all primary key columns in the
@@ -59,20 +59,20 @@ module Google
         #     The values to be written. +values+ can contain more than one
         #     list of values. If it does, then multiple rows are written, one
         #     for each entry in +values+. Each list in +values+ must have
-        #     exactly as many entries as there are entries in Columns
+        #     exactly as many entries as there are entries in {Google::Spanner::V1::Mutation::Write#columns columns}
         #     above. Sending multiple lists is equivalent to sending multiple
         #     +Mutation+s, each containing one +values+ entry and repeating
-        #     Table and Columns. Individual values in each list are
-        #     encoded as described Here.
+        #     {Google::Spanner::V1::Mutation::Write#table table} and {Google::Spanner::V1::Mutation::Write#columns columns}. Individual values in each list are
+        #     encoded as described {Google::Spanner::V1::TypeCode here}.
         class Write; end
 
-        # Arguments to Delete operations.
+        # Arguments to {Google::Spanner::V1::Mutation#delete delete} operations.
         # @!attribute [rw] table
         #   @return [String]
         #     Required. The table whose rows will be deleted.
         # @!attribute [rw] key_set
         #   @return [Google::Spanner::V1::KeySet]
-        #     Required. The primary keys of the rows within Table to delete.
+        #     Required. The primary keys of the rows within {Google::Spanner::V1::Mutation::Delete#table table} to delete.
         class Delete; end
       end
     end

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb

@@ -15,15 +15,15 @@
 module Google
   module Spanner
     module V1
-      # Node information for nodes appearing in a QueryPlan#plan_nodes.
+      # Node information for nodes appearing in a {Google::Spanner::V1::QueryPlan#plan_nodes QueryPlan#plan_nodes}.
       # @!attribute [rw] index
       #   @return [Integer]
-      #     The +PlanNode+'s index in Node list.
+      #     The +PlanNode+'s index in {Google::Spanner::V1::QueryPlan#plan_nodes node list}.
       # @!attribute [rw] kind
       #   @return [Google::Spanner::V1::PlanNode::Kind]
       #     Used to determine the type of node. May be needed for visualizing
       #     different kinds of nodes differently. For example, If the node is a
-      #     SCALAR node, it will have a condensed representation
+      #     {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} node, it will have a condensed representation
       #     which can be used to directly embed a description of the node in its
       #     parent.
       # @!attribute [rw] display_name
@@ -34,7 +34,7 @@ module Google
       #     List of child node +index+es and their relationship to this parent.
       # @!attribute [rw] short_representation
       #   @return [Google::Spanner::V1::PlanNode::ShortRepresentation]
-      #     Condensed representation for SCALAR nodes.
+      #     Condensed representation for {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} nodes.
       # @!attribute [rw] metadata
       #   @return [Google::Protobuf::Struct]
       #     Attributes relevant to the node contained in a group of key-value pairs.
@@ -53,7 +53,7 @@ module Google
       #     execution etc.
       class PlanNode
         # Metadata associated with a parent-child relationship appearing in a
-        # PlanNode.
+        # {Google::Spanner::V1::PlanNode PlanNode}.
         # @!attribute [rw] child_index
         #   @return [Integer]
         #     The node to which the link points.
@@ -65,7 +65,7 @@ module Google
         #     with the output variable.
         # @!attribute [rw] variable
         #   @return [String]
-        #     Only present if the child node is SCALAR and corresponds
+        #     Only present if the child node is {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} and corresponds
         #     to an output variable of the parent node. The field carries the name of
         #     the output variable.
         #     For example, a +TableScan+ operator that reads rows from a table will
@@ -76,7 +76,7 @@ module Google
         class ChildLink; end
 
         # Condensed representation of a node and its subtree. Only present for
-        # +SCALAR+ PlanNode(s).
+        # +SCALAR+ {Google::Spanner::V1::PlanNode PlanNode(s)}.
         # @!attribute [rw] description
         #   @return [String]
         #     A string representation of the expression subtree rooted at this node.
@@ -89,7 +89,7 @@ module Google
         #     this node.
         class ShortRepresentation; end
 
-        # The kind of PlanNode. Distinguishes between the two different kinds of
+        # The kind of {Google::Spanner::V1::PlanNode PlanNode}. Distinguishes between the two different kinds of
         # nodes that can appear in a query plan.
         module Kind
           # Not specified.
@@ -112,7 +112,7 @@ module Google
       # @!attribute [rw] plan_nodes
       #   @return [Array<Google::Spanner::V1::PlanNode>]
       #     The nodes in the query plan. Plan nodes are returned in pre-order starting
-      #     with the plan root. Each PlanNode's +id+ corresponds to its index in
+      #     with the plan root. Each {Google::Spanner::V1::PlanNode PlanNode}'s +id+ corresponds to its index in
       #     +plan_nodes+.
       class QueryPlan; end
     end