google-cloud-spanner 0.21.0

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

@@ -0,0 +1,179 @@
+# Copyright 2016 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
+      class Database
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # a database create or update operation. The job can be refreshed to
+        # retrieve the database object once the operation has been completed.
+        #
+        # See {Project#create_database} and {Database#update}.
+        #
+        # @see https://cloud.google.com/spanner/reference/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   job = spanner.create_database "my-instance",
+        #                                 "my-new-database"
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #   database = job.database
+        #
+        class Job
+          ##
+          # @private The Google::Gax::Operation gRPC object.
+          attr_accessor :grpc
+
+          ##
+          # @private The gRPC Service object.
+          attr_accessor :service
+
+          ##
+          # @private Creates a new Database::Job instance.
+          def initialize
+            @grpc = nil
+            @service = nil
+          end
+
+          ##
+          # The database that is the object of the operation.
+          #
+          # @return [Google::Cloud::Spanner::Database, nil] The database, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_database "my-instance",
+          #                                 "my-new-database"
+          #
+          #   job.done? #=> true
+          #   database = job.database
+          #
+          def database
+            return nil unless done?
+            return nil unless @grpc.grpc_op.result == :response
+            Database.from_grpc @grpc.results, service
+          end
+
+          ##
+          # Checks if the processing of the database operation is complete.
+          #
+          # @return [boolean] `true` when complete, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_database "my-instance",
+          #                                 "my-new-database"
+          #
+          #   job.done? #=> false
+          #
+          def done?
+            @grpc.done?
+          end
+
+          ##
+          # Checks if the processing of the database operation has errored.
+          #
+          # @return [boolean] `true` when errored, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_database "my-instance",
+          #                                 "my-new-database"
+          #
+          #   job.error? #=> false
+          #
+          def error?
+            @grpc.error?
+          end
+
+          ##
+          # Reloads the job with current data from the long-running,
+          # asynchronous processing of a database operation.
+          #
+          # @return [Google::Cloud::Spanner::Database::Job] The same job
+          #   instance.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_database "my-instance",
+          #                                 "my-new-database"
+          #
+          #   job.done? #=> false
+          #   job.reload! # API call
+          #   job.done? #=> true
+          #
+          def reload!
+            @grpc.reload!
+            self
+          end
+          alias_method :refresh!, :reload!
+
+          ##
+          # Reloads the job until the operation is complete. The delay between
+          # reloads will incrementally increase.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_database "my-instance",
+          #                                 "my-new-database"
+          #
+          #   job.done? #=> false
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          def wait_until_done!
+            @grpc.wait_until_done!
+          end
+
+          ##
+          # @private New Database::Job from a Google::Gax::Operation object.
+          def self.from_grpc grpc, service
+            new.tap do |job|
+              job.instance_variable_set :@grpc, grpc
+              job.instance_variable_set :@service, service
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# Copyright 2016 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 "delegate"
+
+module Google
+  module Cloud
+    module Spanner
+      class Database
+        ##
+        # Database::List is a special case Array with additional
+        # values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Database::List with an array of
+          # Database instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of databases.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   databases = spanner.databases "my-instance"
+          #   if databases.next?
+          #     next_databases = databases.next
+          #   end
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of databases.
+          #
+          # @return [Database::List]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   databases = spanner.databases "my-instance"
+          #   if databases.next?
+          #     next_databases = databases.next
+          #   end
+          def next
+            return nil unless next?
+            ensure_service!
+            options = { token: token, max: @max }
+            grpc = @service.list_databases @instance_id, options
+            self.class.from_grpc grpc, @service, @max
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all databases. Default is no limit.
+          # @yield [database] The block for accessing each database.
+          # @yieldparam [Database] database The database object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each database by passing a block:
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   databases = spanner.databases "my-instance"
+          #   databases.all do |database|
+          #     puts database.database_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   databases = spanner.databases "my-instance"
+          #   all_database_ids = databases.all.map do |database|
+          #     database.database_id
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   databases = spanner.databases "my-instance"
+          #   databases.all(request_limit: 10) do |database|
+          #     puts database.database_id
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for(:all, request_limit: request_limit)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Database::List from a
+          # Google::Spanner::Admin::Database::V1::ListDatabasesResponse
+          # object.
+          def self.from_grpc grpc, service, instance_id, max = nil
+            databases = List.new(Array(grpc.databases).map do |database|
+              Database.from_grpc database, service
+            end)
+            databases.instance_variable_set :@instance_id, instance_id
+            token = grpc.next_page_token
+            token = nil if token == ""
+            databases.instance_variable_set :@token,   token
+            databases.instance_variable_set :@service, service
+            databases.instance_variable_set :@max,     max
+            databases
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            fail "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# 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/cloud/errors"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Rollback
+      #
+      # Used to rollback a transaction without passing on the exception. See
+      # {Client#transaction}.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   db.transaction do |tx|
+      #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+      #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+      #
+      #     if something_wrong?
+      #       # Rollback the transaction without passing on the error
+      #       # outside of the transaction method.
+      #       raise Google::Cloud::Spanner::Rollback
+      #     end
+      #   end
+      #
+      class Rollback < Google::Cloud::Error
+      end
+
+      ##
+      # # DuplicateNameError
+      #
+      # Data accessed by name (typically by calling
+      # {Google::Cloud::Spanner::Data#[]} with a key or calling
+      # {Google::Cloud::Spanner::Data#to_h}) has more than one occurrence of the
+      # same name. Such data should be accessed by position rather than by name.
+      #
+      class DuplicateNameError < Google::Cloud::Error
+      end
+
+      ##
+      # # SessionLimitError
+      #
+      # More sessions have been allocated than configured for.
+      class SessionLimitError < Google::Cloud::Error
+      end
+
+      ##
+      # # ClientClosedError
+      #
+      # The client is closed and can no longer be used.
+      class ClientClosedError < Google::Cloud::Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,252 @@
+# 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/cloud/spanner/convert"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Fields
+      #
+      # Represents the field names and types of data returned by Cloud Spanner.
+      #
+      # See [Data
+      # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   results = db.execute "SELECT * FROM users"
+      #
+      #   results.fields.pairs.each do |name, type|
+      #     puts "Column #{name} is type {type}"
+      #   end
+      #
+      class Fields
+        ##
+        # @private
+        def initialize types
+          @fields = []
+          if types.is_a? Array
+            types.each do |type|
+              @fields << field(type)
+            end
+          elsif types.is_a? Hash
+            types.each do |type|
+              @fields << field(type)
+            end
+          else
+            fail ArgumentError, "can only accept Array or Hash"
+          end
+        end
+
+        ##
+        # Returns the types of the data.
+        #
+        # See [Data
+        # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @return [Array<Symbol>] An array containing the types of the data.
+        #
+        def types
+          @fields.map(&:type).map do |type|
+            if type.code == :ARRAY
+              if type.array_element_type.code == :STRUCT
+                [Fields.from_grpc(type.array_element_type.struct_type.fields)]
+              else
+                [type.array_element_type.code]
+              end
+            elsif type.code == :STRUCT
+              Fields.from_grpc type.struct_type.fields
+            else
+              type.code
+            end
+          end
+        end
+
+        ##
+        # Returns the names of the data values, or in cases in which values are
+        # unnamed, the zero-based index position of values.
+        #
+        # @return [Array<(String,Integer)>] An array containing the names
+        #   (String) or position (Integer) for the corresponding values of the
+        #   data.
+        #
+        def keys
+          @fields.each_with_index.map do |field, index|
+            if field.name.empty?
+              index
+            else
+              field.name.to_sym
+            end
+          end
+        end
+
+        ##
+        # Detects duplicate names in the keys for the fields.
+        #
+        # @return [Boolean] Returns `true` if there are duplicate names.
+        #
+        def duplicate_names?
+          keys.count != keys.uniq.count
+        end
+
+        ##
+        # Returns the names or positions and their corresponding types as an
+        # array of arrays.
+        #
+        # @return [Array<Array>] An array containing name/position and types
+        #   pairs.
+        #
+        def pairs
+          keys.zip types
+        end
+
+        ##
+        # Returns the type code for the provided name (String) or index
+        # (Integer). Do not pass a name to this method if the data has more than
+        # one member with the same name. (See {#duplicate_names?})
+        #
+        # @param [String, Integer] key The name (String) or zero-based index
+        #   position (Integer) of the value.
+        #
+        # @raise [Google::Cloud::Spanner::DuplicateNameError] if the data
+        #   contains duplicate names.
+        #
+        # @return [Symbol, nil] The type code, or nil if no value is found.
+        #
+        def [] key
+          return types[key] if key.is_a? Integer
+          name_count = @fields.find_all { |f| f.name == String(key) }.count
+          return nil if name_count == 0
+          fail DuplicateNameError if name_count > 1
+          index = @fields.find_index { |f| f.name == String(key) }
+          types[index]
+        end
+
+        ##
+        # Returns the type codes as an array. Do not use this method if the data
+        # has more than one member with the same name. (See {#duplicate_names?})
+        #
+        # @raise [Google::Cloud::Spanner::DuplicateNameError] if the data
+        #   contains duplicate names.
+        #
+        # @return [Array<Symbol>] An array containing the type codes.
+        #
+        def to_a
+          keys.count.times.map { |i| self[i] }.map do |field|
+            if field.is_a? Fields
+              field.to_h
+            elsif field.is_a? Array
+              field.map { |f| f.is_a?(Fields) ? f.to_h : f }
+            else
+              field
+            end
+          end
+        end
+
+        ##
+        # Returns the names or indexes and corresponding type codes as a hash.
+        #
+        # @return [Hash<(String,Integer)=>Symbol>] A hash containing the names
+        #   or indexes and corresponding types.
+        #
+        def to_h
+          fail DuplicateNameError if duplicate_names?
+          hashified_pairs = pairs.map do |key, value|
+            if value.is_a? Fields
+              [key, value.to_h]
+            elsif value.is_a? Array
+              [key, value.map { |v| v.is_a?(Fields) ? v.to_h : v }]
+            else
+              [key, value]
+            end
+          end
+          Hash[hashified_pairs]
+        end
+
+        # @private
+        def data data
+          # TODO: match order of types
+          data = data.values if data.is_a?(Hash)
+          values = data.map { |datum| Convert.raw_to_value datum }
+          Data.from_grpc values, @fields
+        end
+        alias_method :new, :data
+
+        # @private
+        def == other
+          return false unless other.is_a? Fields
+          pairs == other.pairs
+        end
+
+        # @private
+        def to_s
+          named_types = pairs.map do |key, type|
+            if key.is_a? Integer
+              "#{type.inspect}"
+            else
+              "(#{key})#{type.inspect}"
+            end
+          end
+          "(#{named_types.join ', '})"
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name} #{self}>"
+        end
+
+        ##
+        # @private Creates a new Fields instance from a
+        # Google::Spanner::V1::Metadata::Row_type::Fields.
+        def self.from_grpc fields
+          new([]).tap do |f|
+            f.instance_variable_set :@fields, fields
+          end
+        end
+
+        protected
+
+        def field pair
+          if pair.is_a?(Array)
+            unless pair.count == 2
+              fail ArgumentError, "can only accept pairs of name and type"
+            end
+            if pair.first.nil? || pair.first.is_a?(Integer)
+              Google::Spanner::V1::StructType::Field.new(
+                type: Google::Spanner::V1::Type.new(code: pair.last))
+            else
+              Google::Spanner::V1::StructType::Field.new(
+                name: String(pair.first),
+                type: Google::Spanner::V1::Type.new(code: pair.last))
+            end
+          else
+            unless pair.is_a?(Symbol)
+              fail ArgumentError, "type must be a symbol"
+            end
+            Google::Spanner::V1::StructType::Field.new(
+              type: Google::Spanner::V1::Type.new(code: pair))
+          end
+        end
+      end
+    end
+  end
+end