activemodel-datastore 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c26efa635bdc60b33239d0f6b33cc6e4ac86fb5c752672f25f6969b2c3dda5c
-  data.tar.gz: 9651de6765b071963bbf0ee9da4680dbb46c5d0b820d463e34db0fc0e3d36612
+  metadata.gz: 3126172160a1df49727e648493401c8448f62a1442cba738dcf139d6406dfdce
+  data.tar.gz: 24bc7d6985f16739f16561611255d23ac6862cd72502f50827462a3c0674e6aa
 SHA512:
-  metadata.gz: 4227107ad98274df5bac98ffb38e7de8ebfc8ec3d61edf4f09497ad1498fe936cf2a4a10a4c583ba43f0288f0f011cd8b20dd454f8d2f677380c6967dc3c4c9c
-  data.tar.gz: 38d33728917c185c9beaf6c5ecb64e6adcf5e94ab672651ea33a41d22e9a9b6be503ee043b8878fc19aa81b552b7eae662cc568a50bf073853782bd45e568770
+  metadata.gz: bc4e6401b2932e11c37b509dc1f98561423b6908d0d11f0465363090239a67ae6f7dc02cc5aecedc6fb72e4e8168f44a6ddc9fe38d49665fc6fc95838e0144a8
+  data.tar.gz: 7acf7b5d14306afb3412c7ac667806e05708de0b9a8e8348b172bafa337316f4b11160f68eee3bb1152e27d7fa6ae066d4d28e17f430365b6caf003a3dfdbd1c

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+### 0.9.0 / 2026-08-24
+* identify the Datastore operation, entity kind, and failed-attempt elapsed time in retry logs
+* use a configurable retry logger that defaults to Rails.logger and falls back to standard output
+* update the development environment to Ruby 3.4.10 and the example application to Rails 8.1
+* test CarrierWave integration against CarrierWave 3.1
+
 ### 0.8.0 / 2024-03-05
 * updating GCLOUD_KEYFILE_JSON to work with the latest version of GoogleAuth
 

data/README.md

@@ -1,19 +1,21 @@
 Active Model Datastore
 ===================================
 
-Makes the [google-cloud-datastore](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-datastore) gem compliant with [active_model](https://github.com/rails/rails/tree/master/activemodel) conventions and compatible with your Rails 5+ applications. 
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Makes the [google-cloud-datastore](https://cloud.google.com/ruby/docs/reference/google-cloud-datastore/latest)
+gem compliant with [active_model](https://github.com/rails/rails/tree/master/activemodel)
+conventions and compatible with your Rails 5+ applications.
 
-Why would you want to use Google's NoSQL [Cloud Datastore](https://cloud.google.com/datastore) 
-with Rails? 
+Why would you want to use Google's NoSQL
+[Firestore in Datastore mode](https://docs.cloud.google.com/datastore/docs) with Rails?
 
-When you want a Rails app backed by a managed, massively-scalable datastore solution. Cloud Datastore 
-automatically handles sharding and replication. It is a highly available and durable database that 
-automatically scales to handle your applications' load. Cloud Datastore is a schemaless database 
-suited for unstructured or semi-structured application data.
+Use it when you want a Rails app backed by a fully managed, massively scalable NoSQL database,
+without provisioning database servers or manually sharding data. Datastore stores records as
+entities with flexible properties, so your models do not require a fixed database schema. It
+automatically handles scaling and replication, provides highly available and durable storage, and
+supports indexed queries and ACID transactions.
 
 [![Gem Version](https://badge.fury.io/rb/activemodel-datastore.svg)](https://badge.fury.io/rb/activemodel-datastore)
-[![Build Status](https://travis-ci.org/Agrimatics/activemodel-datastore.svg?branch=master)](https://travis-ci.org/Agrimatics/activemodel-datastore)
+[![CI](https://github.com/Agrimatics/activemodel-datastore/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Agrimatics/activemodel-datastore/actions/workflows/ci.yml)
  
 ## Table of contents
  
@@ -21,9 +23,9 @@ suited for unstructured or semi-structured application data.
 - [Model Example](#model)
 - [Controller Example](#controller)
 - [Retrieving Entities](#queries)
-- [Datastore Consistency](#consistency)
+- [Datastore Consistency and Concurrency](#consistency)
 - [Datastore Indexes](#indexes)
-- [Datastore Emulator](#emulator)
+- [Firestore Emulator](#emulator)
 - [Example Rails App](#rails)
 - [CarrierWave File Uploads](#carrierwave)
 - [Track Changes](#track_changes)
@@ -48,12 +50,13 @@ gem 'activemodel-datastore'
   
 Create a Google Cloud account [here](https://cloud.google.com) and create a project.
 
-Google Cloud requires the Project ID and Service Account Credentials to connect to the Datastore API.
- 
-*Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to enable the 
-Google Cloud Datastore API. When running on Google Cloud Platform environments the Service Account 
-credentials will be discovered automatically. When running on other environments (such as AWS or Heroku)
-you need to create a service account with the role of editor and generate json credentials.*
+Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to create a
+Firestore in Datastore mode database for the project.
+
+The Google Cloud client libraries use Application Default Credentials (ADC). On Google Cloud,
+credentials are discovered automatically from the service account attached to the application. Grant
+that service account only the access it needs; `roles/datastore.user` provides read/write access to
+Datastore data.
 
 Set your project id in an `ENV` variable named `GCLOUD_PROJECT`.
 
@@ -63,22 +66,30 @@ To locate your project ID:
 2. From the projects list, select the name of your project.
 3. On the left, click Dashboard. The project name and ID are displayed in the Dashboard.
 
-If you have an external application running on a platform outside of Google Cloud you also need to 
-provide the Service Account credentials. They are specified in two additional `ENV` variables named 
-`SERVICE_ACCOUNT_CLIENT_EMAIL` and `SERVICE_ACCOUNT_PRIVATE_KEY`. The values for these two `ENV` 
-variables will be in the downloaded service account json credentials file.
+For applications outside Google Cloud, configure ADC for the hosting environment. If a service account
+key is required, the Ruby client supports `GOOGLE_APPLICATION_CREDENTIALS` with the path to its JSON
+file. Active Model Datastore also supports the following environment variables for platforms where
+the JSON must be stored directly in environment variables:
 
 ```bash
-SERVICE_ACCOUNT_PRIVATE_KEY = -----BEGIN PRIVATE KEY-----\nMIIFfb3...5dmFtABy\n-----END PRIVATE KEY-----\n
-SERVICE_ACCOUNT_CLIENT_EMAIL = web-app@app-name.iam.gserviceaccount.com
+export SERVICE_ACCOUNT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----\nMIIFfb3...5dmFtABy\n-----END PRIVATE KEY-----\n'
+export SERVICE_ACCOUNT_CLIENT_EMAIL='web-app@app-name.iam.gserviceaccount.com'
 ```
 
-On Heroku the `ENV` variables can be set under 'Settings' -> 'Config Variables'.
+On Heroku the environment variables can be set under **Settings > Config Vars**.
 
 Active Model Datastore will then handle the authentication for you, and the datastore instance can 
 be accessed with `CloudDatastore.dataset`.
 
-There is an example Puma config file [here](https://github.com/Agrimatics/activemodel-datastore/blob/master/test/support/datastore_example_rails_app/config/puma.rb).
+Datastore retries use `Rails.logger` automatically when Rails is available, which preserves tagged
+logging such as request IDs. Other applications fall back to standard output. To use another logger,
+configure it during application initialization:
+
+```ruby
+ActiveModel::Datastore.logger = MyApplication.logger
+```
+
+There is an example Puma config file [here](https://github.com/Agrimatics/activemodel-datastore/blob/main/test/support/datastore_example_rails_app/config/puma.rb).
  
 ## <a name="model"></a>Model Example
  
@@ -96,18 +107,18 @@ class User
 end
 ```
 
-Data objects in Cloud Datastore are known as entities. Entities are of a kind. An entity has one 
+Data objects in Datastore are known as entities. Entities are of a kind. An entity has one
 or more named properties, each of which can have one or more values. Think of them like this:
 * 'Kind' (which is your table and the name of your Rails model)
 * 'Entity' (which is the record from the table)
 * 'Property' (which is the attribute of the record)
 
-The `entity_properties` method defines an Array of properties that belong to the entity in cloud 
-datastore. Define the attributes of your model using `attr_accessor`. With this approach, Rails 
+The `entity_properties` method defines an Array of properties that belong to the entity in
+Datastore. Define the attributes of your model using `attr_accessor`. With this approach, Rails
 deals solely with ActiveModel objects. The objects are converted to/from entities automatically 
 during save/query operations. You can still use virtual attributes on the model (such as the 
 `:state` attribute above) by simply excluding it from `entity_properties`. In this example state 
-is available to the model but won't be persisted with the entity in datastore.
+is available to the model but won't be persisted with the entity in Datastore.
 
 Validations work as you would expect:
 
@@ -225,12 +236,12 @@ end
 
 ## <a name="queries"></a>Retrieving Entities
 
-Each entity in Cloud Datastore has a key that uniquely identifies it. The key consists of the 
+Each entity in Datastore has a key that uniquely identifies it. The key consists of the
 following components:
 
 * the kind of the entity, which is User in these examples
 * an identifier for the individual entity, which can be either a a key name string or an integer numeric ID
-* an optional ancestor path locating the entity within the Cloud Datastore hierarchy
+* an optional ancestor path locating the entity within the Datastore hierarchy
 
 #### [all(options = {})](http://www.rubydoc.info/gems/activemodel-datastore/ActiveModel%2FDatastore%2FClassMethods:all)
 Queries entities using the provided options. When a limit option is provided queries up to the limit 
@@ -279,34 +290,34 @@ user = User.find_by(name: 'Joe')
 user = User.find_by(name: 'Bryce', ancestor: parent_key)
 ```
 
-Cloud Datastore has documentation on how [Datastore Queries](https://cloud.google.com/datastore/docs/concepts/queries#datastore-basic-query-ruby) 
-work, and pay special attention to the the [restrictions](https://cloud.google.com/datastore/docs/concepts/queries#restrictions_on_queries).
-
-## <a name="consistency"></a>Datastore Consistency
+Google documents how [Datastore queries](https://cloud.google.com/datastore/docs/concepts/queries)
+work, including their [restrictions](https://cloud.google.com/datastore/docs/concepts/queries#restrictions_on_queries).
 
-Cloud Datastore is a non-relational databases, or NoSQL database. It distributes data over many 
-machines and uses synchronous replication over a wide geographic area. Because of this architecture 
-it offers a balance of strong and eventual consistency.
+## <a name="consistency"></a>Datastore Consistency and Concurrency
 
-What is eventual consistency?
+Firestore in Datastore mode is strongly consistent by default. Queries and key lookups reflect
+completed writes, including queries that do not use an ancestor. The legacy Cloud Datastore behavior
+where a newly created entity might not immediately appear in a global query does not apply.
 
-It means that an updated entity value may not be immediately visible when executing a query. 
-Eventual consistency is a theoretical guarantee that, provided no new updates to an entity are made, 
-all reads of the entity will eventually return the last updated value.
+Datastore supports three concurrency modes that determine how concurrent transactions interact:
 
-In the context of a Rails app, there are times that eventual consistency is not ideal. For example,
-let's say you create a user entity with a key that looks like this:
+- `PESSIMISTIC` uses reader/writer locks and is the default for new databases.
+- `OPTIMISTIC` allows concurrent transactions, but only the first conflicting transaction to commit
+  succeeds.
+- `OPTIMISTIC_WITH_ENTITY_GROUPS` preserves legacy Cloud Datastore entity-group transaction
+  semantics. Transactions are limited to 25 entity groups, writes to an entity group are limited to
+  one per second, and queries within transactions must be ancestor queries.
 
-`@key=#<Google::Cloud::Datastore::Key @kind="User", @id=1>`
+Use the following command to inspect a database's concurrency mode:
 
-and then immediately redirect to the index view of users. There is a good chance that your new user 
-is not yet visible in the list. If you perform a refresh on the index view a second or two later 
-the user will appear.
+```bash
+gcloud firestore databases describe --project=PROJECT_ID --database=DATABASE_ID
+```
 
-"Wait a minute!" you say. "This is crap!" you say. Fear not! We can make the query of users strongly
-consistent. We just need to use entity groups and ancestor queries. An entity group is a hierarchy 
-formed by a root entity and its children. To create an entity group, you specify an ancestor path 
-for the entity which is a parent key as part of the child key.
+Entity groups are hierarchies formed by a root entity and its children. They are useful for modeling
+related entities and are required by the transactional restrictions of
+`OPTIMISTIC_WITH_ENTITY_GROUPS`. To create an entity group, specify an ancestor path as part of the
+child entity's key.
 
 Before using the `save` method, assign the `parent_key_id` attribute an ID. Let's say that 12345 
 represents the ID of the company that the users belong to. The key of the user entity will now 
@@ -314,14 +325,10 @@ look like this:
 
 `@key=#<Google::Cloud::Datastore::Key @kind="User", @id=1, @parent=#<Google::Cloud::Datastore::Key @kind="ParentUser", @id=12345>>`
 
-All of the User entities will now belong to an entity group named ParentUser and can be queried by the 
+All of the User entities will now belong to an entity group named ParentUser and can be queried by the
 Company ID. When we query for the users we will provide User.parent_key(12345) as the ancestor option.
- 
-*Ancestor queries are always strongly consistent.*
-
-However, there is a small downside. Entities with the same ancestor are limited to 1 write per second.
-Also, the entity group relationship cannot be changed after creating the entity (as you can't modify 
-an entity's key after it has been saved).
+The entity group relationship cannot be changed after creating the entity because an entity's key
+cannot be modified after it has been saved.
 
 The Users controller would now look like this:
 
@@ -384,24 +391,24 @@ class UsersController < ApplicationController
 end
 ```
 
-See here for the Cloud Datastore documentation on [Data Consistency](https://cloud.google.com/datastore/docs/concepts/structuring_for_strong_consistency).
+See the Datastore documentation for details about
+[transactions, isolation, and concurrency modes](https://cloud.google.com/datastore/docs/concepts/transactions#concurrency_modes).
 
 ## <a name="indexes"></a>Datastore Indexes
 
-Every cloud datastore query requires an index. Yes, you read that correctly. Every single one. The 
+Every Datastore query computes its results using one or more indexes. The
 indexes contain entity keys in a sequence specified by the index's properties and, optionally, 
 the entity's ancestors.
 
 There are two types of indexes, *built-in* and *composite*.
 
 #### Built-in
-By default, Cloud Datastore automatically predefines an index for each property of each entity kind. 
-These single property indexes are suitable for simple types of queries. These indexes are free and
-do not count against your index limit.
+By default, Datastore automatically predefines an index for each property of each entity kind.
+These single property indexes are suitable for simple types of queries.
 
 #### Composite
-Composite index multiple property values per indexed entity. Composite indexes support complex 
-queries and are defined in an index.yaml file.
+Composite indexes include multiple property values per indexed entity. Composite indexes support
+complex queries and are defined in an `index.yaml` file.
 
 Composite indexes are required for queries of the following form:
 
@@ -413,65 +420,50 @@ Composite indexes are required for queries of the following form:
 
 *NOTE*: Inequality filters are LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL.
 
-Google has excellent doc regarding datastore indexes [here](https://cloud.google.com/datastore/docs/concepts/indexes).
-
-The datastore emulator generates composite indexes in an index.yaml file automatically. The file
-can be found in /tmp/local_datastore/WEB-INF/index.yaml. If your localhost Rails app exercises every 
-possible query the application will issue, using every combination of filter and sort order, the 
-generated entries will represent your complete set of indexes.
-
-One thing to note is that the datastore emulator caches indexes. As you add and modify application 
-code you might find that the local datastore index.yaml contains indexes that are no longer needed. 
-In this scenario try deleting the index.yaml and restarting the emulator. Navigate through your Rails
-app and the index.yaml will be built from scratch.
-
-## <a name="emulator"></a>Datastore Emulator
-
-Install the Google Cloud SDK.
-
-    $ curl https://sdk.cloud.google.com | bash
-    
-You can check the version of the SDK and the components installed with:
-
-    $ gcloud components list
-    
-Install the Cloud Datastore Emulator, which provides local emulation of the production Cloud 
-Datastore environment and the gRPC API. However, you'll need to do a small amount of configuration 
-before running the application against the emulator, see [here.](https://cloud.google.com/datastore/docs/tools/datastore-emulator)
-    
-    $ gcloud components install cloud-datastore-emulator 
-    
-Add the following line to your ~/.bash_profile:
-        
-    export PATH="~/google-cloud-sdk/platform/cloud-datastore-emulator:$PATH"
-        
-Restart your shell:
-        
-    exec -l $SHELL    
-
-To create the local development datastore execute the following from the root of the project:
-
-    $ cloud_datastore_emulator create tmp/local_datastore
-    
-To create the local test datastore execute the following from the root of the project:
-    
-    $ cloud_datastore_emulator create tmp/test_datastore
-
-To start the local Cloud Datastore emulator:
-
-    $ cloud_datastore_emulator start --port=8180 tmp/local_datastore
-    
+See Google's [Datastore index documentation](https://cloud.google.com/datastore/docs/concepts/indexes)
+for more information.
+
+## <a name="emulator"></a>Firestore Emulator
+
+Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) and the Firestore emulator:
+
+```bash
+gcloud components install cloud-firestore-emulator
+```
+
+The emulator requires Java 21 or later. Add the emulator executable to your shell's `PATH` because
+the test helpers invoke it directly:
+
+```bash
+export PATH="$HOME/google-cloud-sdk/platform/cloud-firestore-emulator:$PATH"
+```
+
+The Firestore emulator runs in memory by default, so there is no datastore directory to create.
+Start it in Datastore mode on the development port with:
+
+```bash
+cloud_firestore_emulator start --database-mode=datastore-mode --port=8180
+```
+
+Set `DATASTORE_EMULATOR_HOST=localhost:8180` so the Ruby client connects to the emulator. The gem sets
+this automatically for Rails development and uses port 8181 for Rails tests.
+
 ## <a name="rails"></a>Example Rails App
 
-There is an example Rails 5 app in the test directory [here](https://github.com/Agrimatics/activemodel-datastore/tree/master/test/support/datastore_example_rails_app).
+There is an example Rails 8.1 app in the test directory [here](https://github.com/Agrimatics/activemodel-datastore/tree/main/test/support/datastore_example_rails_app).
+
+Start the Firestore emulator in Datastore mode in one terminal:
+
+```bash
+cloud_firestore_emulator start --database-mode=datastore-mode --port=8180
+```
+
+Then start the example application in another terminal:
 
- ```bash
- $ bundle
- $ cloud_datastore_emulator create tmp/local_datastore
- $ cloud_datastore_emulator create tmp/test_datastore
- $ ./start-local-datastore.sh
- $ rails s
- ```
+```bash
+bundle install
+rails server
+```
  
  Navigate to http://localhost:3000.
  
@@ -577,13 +569,12 @@ class Recipe
 end
 ```
 
- Alternatively,`:reject_if` also accepts a symbol for using methods:
+Alternatively, `:reject_if` also accepts a symbol naming a method:
 
 ```ruby
 class Recipe
   def ingredients_attributes=(attributes)
-    reject_proc = proc { |attributes| attributes['name'].blank? }
-    assign_nested_attributes(:ingredients, attributes, reject_if: reject_recipes)
+    assign_nested_attributes(:ingredients, attributes, reject_if: :reject_recipes)
   end
 
   def reject_recipes(attributes)
@@ -594,12 +585,12 @@ end
 
 Within the parent model `valid?` will validate the parent and associated children and
 `nested_models` will return the child objects. If the nested form submitted params contained
-a truthy `_destroy` key, the appropriate nested_models will have `marked_for_destruction` set
-to True.
+a truthy `_destroy` key, the appropriate nested models will have `marked_for_destruction` set
+to `true`.
 
 ## <a name="gotchas"></a>Datastore Gotchas
 #### Ordering of query results is undefined when no sort order is specified.
 When a query does not specify a sort order, the results are returned in the order they are retrieved. 
-As Cloud Datastore implementation evolves (or if a project's indexes change), this order may change. 
+As the Datastore implementation evolves (or if a project's indexes change), this order may change.
 Therefore, if your application requires its query results in a particular order, be sure to specify 
 that sort order explicitly in the query.

data/lib/active_model/datastore/carrier_wave_uploader.rb

@@ -44,7 +44,9 @@ module CarrierWaveUploader
           self.class.uploaders.keys.each do |attr_name|
             entity[attr_name] = append_files(entity[attr_name], existing_files[attr_name])
           end
-          self.class.retry_on_exception? { CloudDatastore.dataset.save entity }
+          self.class.retry_on_exception?(operation: 'save') do
+            CloudDatastore.dataset.save entity
+          end
         end
       end
 

data/lib/active_model/datastore/nested_attr.rb

@@ -78,6 +78,8 @@ module ActiveModel::Datastore
     extend ActiveSupport::Concern
     include ActiveModel::Model
 
+    UNASSIGNABLE_KEYS = %w[id _destroy].freeze
+
     included do
       attr_accessor :nested_attributes, :marked_for_destruction, :_destroy
     end
@@ -173,8 +175,6 @@ module ActiveModel::Datastore
 
     private
 
-    UNASSIGNABLE_KEYS = %w[id _destroy].freeze
-
     def validate_attributes(attributes)
       attributes = attributes.to_h if attributes.respond_to?(:permitted?)
       unless attributes.is_a?(Hash)
@@ -248,7 +248,7 @@ module ActiveModel::Datastore
       def validate_each(record, attribute, value)
         return unless Array(value).reject(&:valid?).any?
 
-        record.errors.add(attribute, :invalid, **options.merge(value: value))
+        record.errors.add(attribute, :invalid, **options, value: value)
       end
     end
   end

data/lib/active_model/datastore/track_changes.rb

@@ -71,7 +71,7 @@ module ActiveModel::Datastore
         raise TrackChangesError, 'Object has not been configured for change tracking.'
       end
 
-      changed = marked_for_destruction? ? true : false
+      changed = marked_for_destruction? || false
       tracked_attributes.each do |attr|
         break if changed
 

data/lib/active_model/datastore/version.rb

@@ -1,5 +1,5 @@
 module ActiveModel
   module Datastore
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/lib/active_model/datastore.rb

@@ -119,6 +119,14 @@ module ActiveModel::Datastore
   include ActiveModel::Datastore::PropertyValues
   include ActiveModel::Datastore::TrackChanges
 
+  def self.logger
+    @logger || (Rails.logger if defined?(Rails) == 'constant')
+  end
+
+  def self.logger=(logger)
+    @logger = logger
+  end
+
   included do
     private_class_method :query_options, :query_sort, :query_property_filter, :find_all_entities
     define_model_callbacks :save, :update, :destroy
@@ -183,7 +191,7 @@ module ActiveModel::Datastore
 
     run_callbacks :update do
       entity = build_entity
-      self.class.retry_on_exception? { CloudDatastore.dataset.save entity }
+      self.class.retry_on_exception?(operation: 'save') { CloudDatastore.dataset.save entity }
     end
   end
 
@@ -191,7 +199,7 @@ module ActiveModel::Datastore
     run_callbacks :destroy do
       key = CloudDatastore.dataset.key self.class.name, id
       key.parent = self.class.parent_key(parent_key_id) if parent?
-      self.class.retry_on_exception? { CloudDatastore.dataset.delete key }
+      self.class.retry_on_exception?(operation: 'delete') { CloudDatastore.dataset.delete key }
     end
   end
 
@@ -202,7 +210,9 @@ module ActiveModel::Datastore
 
     run_callbacks :save do
       entity = build_entity(parent)
-      success = self.class.retry_on_exception? { CloudDatastore.dataset.save entity }
+      success = self.class.retry_on_exception?(operation: 'save') do
+        CloudDatastore.dataset.save entity
+      end
       self.id = entity.key.id if success
       self.parent_key_id = entity.key.parent.id if entity.key.parent.present?
       success
@@ -229,7 +239,7 @@ module ActiveModel::Datastore
     def find_entity(id_or_name, parent = nil)
       key = CloudDatastore.dataset.key name, id_or_name
       key.parent = parent if parent.present?
-      retry_on_exception { CloudDatastore.dataset.find key }
+      retry_on_exception(operation: 'find') { CloudDatastore.dataset.find key }
     end
 
     ##
@@ -290,7 +300,9 @@ module ActiveModel::Datastore
     def all(options = {})
       next_cursor = nil
       query = build_query(options)
-      query_results = retry_on_exception { CloudDatastore.dataset.run query }
+      query_results = retry_on_exception(operation: 'run query') do
+        CloudDatastore.dataset.run query
+      end
       if options[:limit]
         next_cursor = query_results.cursor if query_results.size == options[:limit]
         return from_entities(query_results.all), next_cursor
@@ -342,7 +354,9 @@ module ActiveModel::Datastore
       query.ancestor(args[:ancestor]) if args[:ancestor]
       query.limit(1)
       query.where(args.keys[0].to_s, '=', args.values[0])
-      query_results = retry_on_exception { CloudDatastore.dataset.run query }
+      query_results = retry_on_exception(operation: 'run query') do
+        CloudDatastore.dataset.run query
+      end
       from_entity(query_results.first)
     end
 
@@ -400,15 +414,23 @@ module ActiveModel::Datastore
       query_options(query, options)
     end
 
-    def retry_on_exception?(max_retry_count = 5)
+    def retry_on_exception?(max_retry_count = 5, operation: nil, kind: name)
       retries = 0
       sleep_time = 0.25
       begin
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) if operation
         yield
       rescue Google::Cloud::Error => e
         return false if retries >= max_retry_count
 
-        puts "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        if operation
+          elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          message = "\e[33mDatastore #{operation} failed for #{kind} after #{elapsed_ms} ms: " \
+                    "#{e.message.inspect}; retrying in #{sleep_time} s\e[0m"
+        else
+          message = "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        end
+        ActiveModel::Datastore.logger ? ActiveModel::Datastore.logger.warn(message) : puts(message)
         # 0.25, 0.5, 1, 2, and 4 second between retries.
         sleep sleep_time
         retries += 1
@@ -417,15 +439,23 @@ module ActiveModel::Datastore
       end
     end
 
-    def retry_on_exception(max_retry_count = 5)
+    def retry_on_exception(max_retry_count = 5, operation: nil, kind: name)
       retries = 0
       sleep_time = 0.25
       begin
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) if operation
         yield
       rescue Google::Cloud::Error => e
         raise e if retries >= max_retry_count
 
-        puts "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        if operation
+          elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          message = "\e[33mDatastore #{operation} failed for #{kind} after #{elapsed_ms} ms: " \
+                    "#{e.message.inspect}; retrying in #{sleep_time} s\e[0m"
+        else
+          message = "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        end
+        ActiveModel::Datastore.logger ? ActiveModel::Datastore.logger.warn(message) : puts(message)
         # 0.25, 0.5, 1, 2, and 4 second between retries.
         sleep sleep_time
         retries += 1
@@ -491,7 +521,7 @@ module ActiveModel::Datastore
     def find_all_entities(ids_or_names, parent)
       keys = ids_or_names.map { |id| CloudDatastore.dataset.key name, id }
       keys.map { |key| key.parent = parent } if parent.present?
-      retry_on_exception { CloudDatastore.dataset.find_all keys }
+      retry_on_exception(operation: 'find all') { CloudDatastore.dataset.find_all keys }
     end
 
     def build_model(entity)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activemodel-datastore
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Bryce McLean
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -148,14 +147,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.1'
 description: Makes the google-cloud-datastore gem compliant with active_model conventions
   and compatible with your Rails 5+ applications.
 email:
@@ -182,10 +181,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/Agrimatics/activemodel-datastore
-  changelog_uri: https://github.com/Agrimatics/activemodel-datastore/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/Agrimatics/activemodel-datastore/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/Agrimatics/activemodel-datastore/
   bug_tracker_uri: https://github.com/Agrimatics/activemodel-datastore/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -200,8 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Cloud Datastore integration with Active Model
 test_files: []