google-cloud-spanner 0.21.0

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

@@ -0,0 +1,565 @@
+# 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 "google/cloud/spanner/data"
+require "google/cloud/spanner/results"
+require "google/cloud/spanner/commit"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # @private
+      #
+      # # Session
+      #
+      # A session can be used to perform transactions that read and/or modify
+      # data in a Cloud Spanner database. Sessions are meant to be reused for
+      # many consecutive transactions.
+      #
+      # Sessions can only execute one transaction at a time. To execute multiple
+      # concurrent read-write/write-only transactions, create multiple sessions.
+      # Note that standalone reads and queries use a transaction internally, and
+      # count toward the one transaction limit.
+      #
+      # Cloud Spanner limits the number of sessions that can exist at any given
+      # time; thus, it is a good idea to delete idle and/or unneeded sessions.
+      # Aside from explicit deletes, Cloud Spanner can delete sessions for which
+      # no operations are sent for more than an hour.
+      #
+      class Session
+        ##
+        # @private The Google::Spanner::V1::Session object
+        attr_accessor :grpc
+
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        # @private Creates a new Session instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+        end
+
+        # The unique identifier for the project.
+        # @return [String]
+        def project_id
+          V1::SpannerClient.match_project_from_session_name @grpc.name
+        end
+
+        # The unique identifier for the instance.
+        # @return [String]
+        def instance_id
+          V1::SpannerClient.match_instance_from_session_name @grpc.name
+        end
+
+        # The unique identifier for the database.
+        # @return [String]
+        def database_id
+          V1::SpannerClient.match_database_from_session_name @grpc.name
+        end
+
+        # The unique identifier for the session.
+        # @return [String]
+        def session_id
+          V1::SpannerClient.match_session_from_session_name @grpc.name
+        end
+
+        # rubocop:disable LineLength
+
+        ##
+        # The full path for the session resource. Values are of the form
+        # `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @return [String]
+        def path
+          @grpc.name
+        end
+
+        # rubocop:enable LineLength
+
+        ##
+        # Executes a SQL query.
+        #
+        # Arguments can be passed using `params`, Ruby types are mapped to
+        # Spanner types as follows:
+        #
+        # | Spanner     | Ruby           | Notes  |
+        # |-------------|----------------|---|
+        # | `BOOL`      | `true`/`false` | |
+        # | `INT64`     | `Integer`      | |
+        # | `FLOAT64`   | `Float`        | |
+        # | `STRING`    | `String`       | |
+        # | `DATE`      | `Date`         | |
+        # | `TIMESTAMP` | `Time`, `DateTime` | |
+        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        # | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        # See [Data
+        # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @param [String] sql The SQL query string. See [Query
+        #   syntax](https://cloud.google.com/spanner/docs/query-syntax).
+        #
+        #   The SQL query string can contain parameter placeholders. A parameter
+        #   placeholder consists of "@" followed by the parameter name.
+        #   Parameter names consist of any combination of letters, numbers, and
+        #   underscores.
+        # @param [Hash] params SQL parameters for the query string. The
+        #   parameter placeholders, minus the "@", are the the hash keys, and
+        #   the literal values are the hash values. If the query string contains
+        #   something like "WHERE id > @msg_id", then the params must contain
+        #   something like `:msg_id => 1`.
+        # @param [Hash] types Types of the SQL parameters in `params`. It is not
+        #   always possible for Cloud Spanner to infer the right SQL type from a
+        #   value in `params`. In these cases, the `types` hash can be used to
+        #   specify the exact SQL type for some or all of the SQL query
+        #   parameters.
+        #
+        #   The keys of the hash should be query string parameter placeholders,
+        #   minus the "@". The values of the hash should be Cloud Spanner type
+        #   codes from the following list:
+        #
+        #   * `:BOOL`
+        #   * `:BYTES`
+        #   * `:DATE`
+        #   * `:FLOAT64`
+        #   * `:INT64`
+        #   * `:STRING`
+        #   * `:TIMESTAMP`
+        #
+        #   Arrays are specified by providing the type code in an array. For
+        #   example, an array of integers are specified as `[:INT64]`.
+        #
+        #   Structs are not yet supported in query parameters.
+        #
+        #   Types are optional.
+        # @param [Google::Spanner::V1::TransactionSelector] transaction The
+        #   transaction selector value to send. Only used for single-use
+        #   transactions.
+        #
+        # @return [Google::Cloud::Spanner::Results] The results of the query
+        #   execution.
+        #
+        # @example
+        #   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
+        #
+        # @example Query using query parameters:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.execute "SELECT * FROM users WHERE active = @active",
+        #                        params: { active: true }
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def execute sql, params: nil, types: nil, transaction: nil
+          ensure_service!
+          results = Results.execute service, path, sql,
+                                    params: params, types: types,
+                                    transaction: transaction
+          @last_updated_at = Time.now
+          results
+        end
+        alias_method :query, :execute
+
+        ##
+        # Read rows from a database table, as a simple alternative to
+        # {#execute}.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   read.
+        # @param [Array<String, Symbol>] columns The columns of table to be
+        #   returned for each row matching this request.
+        # @param [Object, Array<Object>] keys A single, or list of keys or key
+        #   ranges to match returned data to. Values should have exactly as many
+        #   elements as there are columns in the primary key.
+        # @param [String] index The name of an index to use instead of the
+        #   table's primary key when interpreting `id` and sorting result rows.
+        #   Optional.
+        # @param [Integer] limit If greater than zero, no more than this number
+        #   of rows will be returned. The default is no limit.
+        # @param [Google::Spanner::V1::TransactionSelector] transaction The
+        #   transaction selector value to send. Only used for single-use
+        #   transactions.
+        #
+        # @return [Google::Cloud::Spanner::Results] The results of the read
+        #   operation.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.read "users", [:id, :name]
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def read table, columns, keys: nil, index: nil, limit: nil,
+                 transaction: nil
+          ensure_service!
+          results = Results.read service, path, table, columns,
+                                 keys: keys, index: index, limit: limit,
+                                 transaction: transaction
+          @last_updated_at = Time.now
+          results
+        end
+
+        ##
+        # Creates changes to be applied to rows in the database.
+        #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @yield [commit] The block for mutating the data.
+        # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   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, name: "Charlie", active: false }]
+        #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        def commit transaction_id: nil
+          ensure_service!
+          commit = Commit.new
+          yield commit
+          commit_resp = service.commit path, commit.mutations,
+                                       transaction_id: transaction_id
+          @last_updated_at = Time.now
+          Convert.timestamp_to_time commit_resp.commit_timestamp
+        end
+
+        ##
+        # Inserts or updates rows in a table. If any of the rows already exist,
+        # then its column values are overwritten with the ones provided. Any
+        # column values not explicitly written are preserved.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.upsert "users", [{ id: 1, name: "Charlie", active: false },
+        #                       { id: 2, name: "Harvey",  active: true }]
+        #
+        def upsert table, *rows, transaction_id: nil
+          commit transaction_id: transaction_id do |c|
+            c.upsert table, rows
+          end
+        end
+        alias_method :save, :upsert
+
+        ##
+        # Inserts new rows in a table. If any of the rows already exist, the
+        # write or request fails with error `ALREADY_EXISTS`.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.insert "users", [{ id: 1, name: "Charlie", active: false },
+        #                       { id: 2, name: "Harvey",  active: true }]
+        #
+        def insert table, *rows, transaction_id: nil
+          commit transaction_id: transaction_id do |c|
+            c.insert table, rows
+          end
+        end
+
+        ##
+        # Updates existing rows in a table. If any of the rows does not already
+        # exist, the request fails with error `NOT_FOUND`.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.update "users", [{ id: 1, name: "Charlie", active: false },
+        #                       { id: 2, name: "Harvey",  active: true }]
+        #
+        def update table, *rows, transaction_id: nil
+          commit transaction_id: transaction_id do |c|
+            c.update table, rows
+          end
+        end
+
+        ##
+        # Inserts or replaces rows in a table. If any of the rows already exist,
+        # it is deleted, and the column values provided are inserted instead.
+        # Unlike #upsert, this means any values not explicitly written become
+        # `NULL`.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.replace "users", [{ id: 1, name: "Charlie", active: false },
+        #                        { id: 2, name: "Harvey",  active: true }]
+        #
+        def replace table, *rows, transaction_id: nil
+          commit transaction_id: transaction_id do |c|
+            c.replace table, rows
+          end
+        end
+
+        ##
+        # Deletes rows from a table. Succeeds whether or not the specified rows
+        # were present.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Object, Array<Object>] keys A single, or list of keys or key
+        #   ranges to match returned data to. Values should have exactly as many
+        #   elements as there are columns in the primary key.
+        #
+        # @return [Time] The timestamp at which the operation committed.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.delete "users", [1, 2, 3]
+        #
+        def delete table, keys = [], transaction_id: nil
+          commit transaction_id: transaction_id do |c|
+            c.delete table, keys
+          end
+        end
+
+        ##
+        # Rolls back the transaction, releasing any locks it holds.
+        def rollback transaction_id
+          service.rollback path, transaction_id
+          @last_updated_at = Time.now
+          true
+        end
+
+        ##
+        # @private
+        # Creates a new transaction object every time.
+        def create_transaction
+          tx_grpc = service.begin_transaction path
+          Transaction.from_grpc(tx_grpc, self)
+        end
+
+        ##
+        # Reloads the session resource. Useful for determining if the session is
+        # still valid on the Spanner API.
+        def reload!
+          ensure_service!
+          @grpc = service.get_session path
+          @last_updated_at = Time.now
+          return self
+        rescue Google::Cloud::NotFoundError
+          @grpc = service.create_session \
+            Admin::Database::V1::DatabaseAdminClient.database_path(
+              project_id, instance_id, database_id)
+          @last_updated_at = Time.now
+          return self
+        end
+
+        ##
+        # @private
+        # Keeps the session alive by executing `"SELECT 1"`.
+        def keepalive!
+          ensure_service!
+          execute "SELECT 1"
+          return true
+        rescue Google::Cloud::NotFoundError
+          @grpc = service.create_session \
+            Admin::Database::V1::DatabaseAdminClient.database_path(
+              project_id, instance_id, database_id)
+          return false
+        end
+
+        ##
+        # Permanently deletes the session.
+        def release!
+          ensure_service!
+          service.delete_session path
+        end
+
+        ##
+        # @private
+        # Determines if the session has been idle longer than the given
+        # duration.
+        def idle_since? duration
+          return true if @last_updated_at.nil?
+          Time.now > @last_updated_at + duration
+        end
+
+        ##
+        # @private Creates a new Session instance from a
+        # Google::Spanner::V1::Session.
+        def self.from_grpc grpc, service
+          new grpc, service
+        end
+
+        ##
+        # @private
+        def session
+          self
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          fail "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end