google-cloud-datastore 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7452a328fd9cb6018d65778f74c89de342ad6c54990da49b9978d7a8b53e271e
-  data.tar.gz: 14f3ab5913d8923dfef6f0c37eeba948859fe851536a0f65807846a0cc91c884
+  metadata.gz: ee669c1788eabbeab4c54a4e3c70ef523eaf29ea39d67fff4b8907c128c06a86
+  data.tar.gz: e3ed585c57076f65a53901f1a02027ddeda91e54ec7a0526e85c1e74f15c63aa
 SHA512:
-  metadata.gz: f391045ca39e4899d30254bb7c441344da56a01840ce6fb979025442ebad5cae2f646a37ab7fd7da994966f29f6d961e6f8921c1553b4df6149398fe0793983a
-  data.tar.gz: '012294aba883d1292fd1948ff38f1d50ac872046f6083ddc6b120ae3991b5e6fb973062b8b5c99a4c0864a22e5c3ac1444878a21987537c6a3f1ad6a8f29ab6f'
+  metadata.gz: 4cb9965dda5f5255a7cafa68516a3a9dbbdd03c0ea00ce2a64d22acfcbfd2bca476adf03871c56508ace442d7fb0c58013ad35b2f3d02895f071cdc5fe9be030
+  data.tar.gz: ce4faf4d6a03e3cd9f952689a78b7a440076ec82fdbb1d1cb09278f8c2039fb5b56bbf92e9785e08599abaf1790c994700d52555808a9579c44447bd797c7276

data/LICENSE

@@ -1,6 +1,6 @@
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -192,7 +192,7 @@
    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
+       https://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,

data/lib/google-cloud-datastore.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,
@@ -369,6 +369,30 @@ module Google
     # end
     # ```
     #
+    # A read-only transaction cannot modify entities; in return they do not
+    # contend with other read-write or read-only transactions. Using a read-only
+    # transaction for transactions that only read data will potentially improve
+    # throughput.
+    #
+    # ```ruby
+    # require "google/cloud/datastore"
+    #
+    # datastore = Google::Cloud::Datastore.new
+    #
+    # task_list_key = datastore.key "TaskList", "default"
+    # query = datastore.query("Task").
+    #   ancestor(task_list_key)
+    #
+    # tasks = nil
+    #
+    # datastore.transaction read_only: true do |tx|
+    #   task_list = tx.find task_list_key
+    #   if task_list
+    #     tasks = tx.run query
+    #   end
+    # end
+    # ```
+    #
     # See {Google::Cloud::Datastore::Transaction} and
     # {Google::Cloud::Datastore::Dataset#transaction}
     #
@@ -537,8 +561,6 @@ module Google
     # ```
     #
     module Datastore
-      # rubocop:disable MethodLength
-
       ##
       # Creates a new object for connecting to the Datastore service.
       # Each call creates a new connection.
@@ -614,8 +636,6 @@ module Google
             project_id, credentials,
             timeout: timeout, client_config: client_config))
       end
-
-      # rubocop:enable MethodLength
     end
   end
 end

data/lib/google/cloud/datastore/commit.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/convert.rb

@@ -1,10 +1,10 @@
-# Copyright 2017 Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

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

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/cursor.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/dataset.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,
@@ -25,6 +25,8 @@ require "google/cloud/datastore/gql_query"
 require "google/cloud/datastore/cursor"
 require "google/cloud/datastore/dataset/lookup_results"
 require "google/cloud/datastore/dataset/query_results"
+require "google/cloud/datastore/transaction"
+require "google/cloud/datastore/read_only_transaction"
 
 module Google
   module Cloud
@@ -466,6 +468,30 @@ module Google
         ##
         # Creates a Datastore Transaction.
         #
+        # Transactions using the block syntax are committed upon block
+        # completion and are automatically retried when known errors are raised
+        # during commit. All other errors will be passed on.
+        #
+        # All changes are accumulated in memory until the block completes.
+        # Transactions will be automatically retried when possible, until
+        # `deadline` is reached. This operation makes separate API requests to
+        # begin and commit the transaction.
+        #
+        # @see https://cloud.google.com/datastore/docs/concepts/transactions
+        #   Transactions
+        #
+        # @param [Numeric] deadline The total amount of time in seconds the
+        #   transaction has to succeed. The default is `60`.
+        # @param [String] previous_transaction The transaction identifier of a
+        #   transaction that is being retried. Read-write transactions may fail
+        #   due to contention. A read-write transaction can be retried by
+        #   specifying `previous_transaction` when creating the new transaction.
+        #
+        #   Specifying `previous_transaction` provides information that can be
+        #   used to improve throughput. In particular, if transactional
+        #   operations A and B conflict, specifying the `previous_transaction`
+        #   can help to prevent livelock. (See {Transaction#id})
+        #
         # @yield [tx] a block yielding a new transaction
         # @yieldparam [Transaction] tx the transaction object
         #
@@ -509,8 +535,80 @@ module Google
         #     tx.rollback
         #   end
         #
-        def transaction
-          tx = Transaction.new service
+        def transaction deadline: nil, previous_transaction: nil
+          deadline = validate_deadline deadline
+          backoff = 1.0
+          start_time = Time.now
+
+          tx = Transaction.new \
+            service, previous_transaction: previous_transaction
+          return tx unless block_given?
+
+          begin
+            yield tx
+            tx.commit
+          rescue Google::Cloud::UnavailableError => err
+            # Re-raise if deadline has passed
+            raise err if Time.now - start_time > deadline
+
+            # Sleep with incremental backoff
+            sleep(backoff *= 1.3)
+
+            # Create new transaction and retry the block
+            tx = Transaction.new service, previous_transaction: tx.id
+            retry
+          rescue
+            begin
+              tx.rollback
+            rescue
+              raise TransactionError,
+                    "Transaction failed to commit and rollback."
+            end
+            raise TransactionError, "Transaction failed to commit."
+          end
+        end
+
+        ##
+        # Creates a read-only transaction that provides a consistent snapshot of
+        # Cloud Datastore. This can be useful when multiple reads are needed to
+        # render a page or export data that must be consistent.
+        #
+        # A read-only transaction cannot modify entities; in return they do not
+        # contend with other read-write or read-only transactions. Using a
+        # read-only transaction for transactions that only read data will
+        # potentially improve throughput.
+        #
+        # Read-only single-group transactions never fail due to concurrent
+        # modifications, so you don't have to implement retries upon failure.
+        # However, multi-entity-group transactions can fail due to concurrent
+        # modifications, so these should have retries.
+        #
+        # @see https://cloud.google.com/datastore/docs/concepts/transactions
+        #   Transactions
+        #
+        # @yield [tx] a block yielding a new transaction
+        # @yieldparam [ReadOnlyTransaction] tx the transaction object
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task_list_key = datastore.key "TaskList", "default"
+        #   query = datastore.query("Task").
+        #     ancestor(task_list_key)
+        #
+        #   tasks = nil
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     task_list = tx.find task_list_key
+        #     if task_list
+        #       tasks = tx.run query
+        #     end
+        #   end
+        #
+        def read_only_transaction
+          tx = ReadOnlyTransaction.new service
           return tx unless block_given?
 
           begin
@@ -526,6 +624,7 @@ module Google
             raise TransactionError, "Transaction failed to commit."
           end
         end
+        alias_method :snapshot, :read_only_transaction
 
         ##
         # Create a new Query instance. This is a convenience method to make the
@@ -789,6 +888,12 @@ module Google
           fail "Must have active connection to service" unless service
         end
 
+        def validate_deadline deadline
+          return 60 unless deadline.is_a? Numeric
+          return 60 if deadline < 0
+          deadline
+        end
+
         def check_consistency! consistency
           fail(ArgumentError,
                format("Consistency must be :eventual or :strong, not %s.",

data/lib/google/cloud/datastore/dataset/lookup_results.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/dataset/query_results.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/entity.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

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

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/gql_query.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/key.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/properties.rb

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/query.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/read_only_transaction.rb

@@ -0,0 +1,249 @@
+# Copyright 2014 Google LLC
+#
+# 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
+#
+#     https://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/datastore/dataset/lookup_results"
+require "google/cloud/datastore/dataset/query_results"
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # # ReadOnlyTransaction
+      #
+      # Represents a read-only Datastore transaction that only allows reads.
+      #
+      # A read-only transaction cannot modify entities; in return they do not
+      # contend with other read-write or read-only transactions. Using a
+      # read-only transaction for transactions that only read data will
+      # potentially improve throughput.
+      #
+      # See {Google::Cloud::Datastore::Dataset#transaction}
+      #
+      # @see https://cloud.google.com/datastore/docs/concepts/transactions
+      #   Transactions
+      #
+      # @example
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   task_list_key = datastore.key "TaskList", "default"
+      #   query = datastore.query("Task").
+      #     ancestor(task_list_key)
+      #
+      #   tasks = nil
+      #
+      #   datastore.read_only_transaction do |tx|
+      #     task_list = tx.find task_list_key
+      #     if task_list
+      #       tasks = tx.run query
+      #     end
+      #   end
+      #
+      class ReadOnlyTransaction
+        attr_reader :id
+
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new ReadOnlyTransaction instance.
+        # Takes a Service instead of project and Credentials.
+        #
+        def initialize service
+          @service = service
+          reset!
+          start
+        end
+
+        ##
+        # Retrieve an entity by providing key information. The lookup is run
+        # within the transaction.
+        #
+        # @param [Key, String] key_or_kind A Key object or `kind` string value.
+        #
+        # @return [Google::Cloud::Datastore::Entity, nil]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task_list_key = datastore.key "TaskList", "default"
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     task_list = tx.find task_list_key
+        #   end
+        #
+        def find key_or_kind, id_or_name = nil
+          key = key_or_kind
+          unless key.is_a? Google::Cloud::Datastore::Key
+            key = Key.new key_or_kind, id_or_name
+          end
+          find_all(key).first
+        end
+        alias_method :get, :find
+
+        ##
+        # Retrieve the entities for the provided keys. The lookup is run within
+        # the transaction.
+        #
+        # @param [Key] keys One or more Key objects to find records for.
+        #
+        # @return [Google::Cloud::Datastore::Dataset::LookupResults]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task_key1 = datastore.key "Task", 123456
+        #   task_key2 = datastore.key "Task", 987654
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     tasks = tx.find_all task_key1, task_key2
+        #   end
+        #
+        def find_all *keys
+          ensure_service!
+          lookup_res = service.lookup(*Array(keys).flatten.map(&:to_grpc),
+                                      transaction: @id)
+          Dataset::LookupResults.from_grpc lookup_res, service, nil, @id
+        end
+        alias_method :lookup, :find_all
+
+        ##
+        # Retrieve entities specified by a Query. The query is run within the
+        # transaction.
+        #
+        # @param [Query] query The Query object with the search criteria.
+        # @param [String] namespace The namespace the query is to run within.
+        #
+        # @return [Google::Cloud::Datastore::Dataset::QueryResults]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = datastore.query("Task").
+        #     where("done", "=", false)
+        #   datastore.read_only_transaction do |tx|
+        #     tasks = tx.run query
+        #   end
+        #
+        def run query, namespace: nil
+          ensure_service!
+          unless query.is_a?(Query) || query.is_a?(GqlQuery)
+            fail ArgumentError, "Cannot run a #{query.class} object."
+          end
+          query_res = service.run_query query.to_grpc, namespace,
+                                        transaction: @id
+          Dataset::QueryResults.from_grpc query_res, service, namespace,
+                                          query.to_grpc.dup
+        end
+        alias_method :run_query, :run
+
+        ##
+        # Begins a transaction.
+        # This method is run when a new ReadOnlyTransaction is created.
+        #
+        def start
+          fail TransactionError, "Transaction already opened." unless @id.nil?
+
+          ensure_service!
+          tx_res = service.begin_transaction read_only: true
+          @id = tx_res.transaction
+        end
+        alias_method :begin_transaction, :start
+
+        ##
+        # Commits the transaction.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task_list_key = datastore.key "TaskList", "default"
+        #   query = datastore.query("Task").
+        #     ancestor(task_list_key)
+        #
+        #   tx = datastore.transaction
+        #   task_list = tx.find task_list_key
+        #   if task_list
+        #     tasks = tx.run query
+        #   end
+        #   tx.commit
+        #
+        def commit
+          fail TransactionError,
+               "Cannot commit when not in a transaction." if @id.nil?
+
+          ensure_service!
+
+          service.commit [], transaction: @id
+          true
+        end
+
+        ##
+        # Rolls back the transaction.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task_list_key = datastore.key "TaskList", "default"
+        #   query = datastore.query("Task").
+        #     ancestor(task_list_key)
+        #
+        #   tx = datastore.transaction
+        #   task_list = tx.find task_list_key
+        #   if task_list
+        #     tasks = tx.run query
+        #   end
+        #   tx.rollback
+        #
+        def rollback
+          if @id.nil?
+            fail TransactionError, "Cannot rollback when not in a transaction."
+          end
+
+          ensure_service!
+          service.rollback @id
+          true
+        end
+
+        ##
+        # Reset the transaction.
+        # {ReadOnlyTransaction#start} must be called afterwards.
+        def reset!
+          @id = nil
+        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

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

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,
@@ -110,8 +110,24 @@ module Google
 
         ##
         # Begin a new transaction.
-        def begin_transaction
-          execute { service.begin_transaction project }
+        def begin_transaction read_only: nil, previous_transaction: nil
+          if read_only
+            transaction_options = Google::Datastore::V1::TransactionOptions.new
+            transaction_options.read_only = \
+              Google::Datastore::V1::TransactionOptions::ReadOnly.new
+          end
+          if previous_transaction
+            transaction_options ||= \
+              Google::Datastore::V1::TransactionOptions.new
+            rw = Google::Datastore::V1::TransactionOptions::ReadWrite.new(
+              previous_transaction: previous_transaction.encode("ASCII-8BIT")
+            )
+            transaction_options.read_write = rw
+          end
+          execute do
+            service.begin_transaction project,
+                                      transaction_options: transaction_options
+          end
         end
 
         ##

data/lib/google/cloud/datastore/transaction.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,
@@ -26,6 +26,8 @@ module Google
       # @see https://cloud.google.com/datastore/docs/concepts/transactions
       #   Transactions
       #
+      # @attr_reader [String] id The identifier of the transaction.
+      #
       # @example Transactional update:
       #   require "google/cloud/datastore"
       #
@@ -41,26 +43,15 @@ module Google
       #     end
       #   end
       #
-      # @example Transactional read:
-      #   require "google/cloud/datastore"
-      #
-      #   datastore = Google::Cloud::Datastore.new
-      #
-      #   task_list_key = datastore.key "TaskList", "default"
-      #   datastore.transaction do |tx|
-      #     task_list = tx.find task_list_key
-      #     query = tx.query("Task").ancestor(task_list)
-      #     tasks_in_list = tx.run query
-      #   end
-      #
       class Transaction < Dataset
         attr_reader :id
 
         ##
         # @private Creates a new Transaction instance.
         # Takes a Service instead of project and Credentials.
-        def initialize service
+        def initialize service, previous_transaction: nil
           @service = service
+          @previous_transaction = previous_transaction
           reset!
           start
         end
@@ -244,9 +235,8 @@ module Google
         #
         #   datastore = Google::Cloud::Datastore.new
         #
-        #   query = datastore.query("Task").
-        #     where("done", "=", false)
         #   datastore.transaction do |tx|
+        #     query = datastore.query("Task")
         #     tasks = tx.run query
         #   end
         #
@@ -280,7 +270,8 @@ module Google
           fail TransactionError, "Transaction already opened." unless @id.nil?
 
           ensure_service!
-          tx_res = service.begin_transaction
+          tx_res = service.begin_transaction \
+            previous_transaction: @previous_transaction
           @id = tx_res.transaction
         end
         alias_method :begin_transaction, :start

data/lib/google/cloud/datastore/v1.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/datastore_client.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/datastore.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/entity.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/query.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/doc/google/protobuf/wrappers.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/v1/doc/overview.rb

@@ -1,10 +1,10 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017 Google LLC
 #
 # 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
+#     https://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,

data/lib/google/cloud/datastore/version.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,
@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Datastore
-      VERSION = "1.2.1"
+      VERSION = "1.3.0"
     end
   end
 end

data/lib/google/datastore/v1/datastore_services_pb.rb

@@ -7,7 +7,7 @@
 # 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
+#     https://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,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-21 00:00:00.000000000 Z
+date: 2017-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.1
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.1
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
@@ -205,6 +205,7 @@ files:
 - lib/google/cloud/datastore/key.rb
 - lib/google/cloud/datastore/properties.rb
 - lib/google/cloud/datastore/query.rb
+- lib/google/cloud/datastore/read_only_transaction.rb
 - lib/google/cloud/datastore/service.rb
 - lib/google/cloud/datastore/transaction.rb
 - lib/google/cloud/datastore/v1.rb
@@ -240,7 +241,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.2
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Datastore