tarantool-model 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b70f00434a73dd90e2c7fcd3b6fa9e73e3e9f2a4809da099d22301d6e64f024
-  data.tar.gz: cdd55a36929dd8d4a3cb8c10ff4e39e90c1aa304b2ccea431db3354caf80830b
+  metadata.gz: dfebd43ac5f258976a8257dae17d23a26a607534c97c83303dc020f8fc7d3e82
+  data.tar.gz: 8aee6cf2bfc9c2e16dee2440ebfb4292f6458eeacb355ebe4a40bebdb5d8a43b
 SHA512:
-  metadata.gz: 0f63d44c5c2cf9d9ac311efcfe0ee7a46d7819ce4c5681c9200eaaa0116aad14b810b36acdc39480c28cc2fbc9679cedace62acb02cb41da3ee55965d5928ea2
-  data.tar.gz: 912d7c7254e2c5e9aa4d8e045da95b04c18570eff8b0dd3ee4b8b088ce9837917e11776bfb350e86c648467f7bfba1d7af8627f0bc7dd63701e2ad8d573f1c99
+  metadata.gz: 8a4161e4bbf0f5593ef3d0a0b2cc8b2a2b49c5456466e4e1252e8ffccb8ec497a10c455fb2389da59f5dd0b30e4c0a5baaec3bd400a1d91174f7158c2520e9d3
+  data.tar.gz: 953f19659c46174dd935642bb8f99a4d846cc7dc892f9c7bbc992ee5e1272851a7d1526edfbec71ce1ec6581778a273ec86f5cd94cbee0b73086e6f253c0ef40

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0 (2026-10-17)
+
+- `Tarantool::Model.default_storage`: a storage, or a Proc called once on first use, for models without one of
+  their own.
+- Optimistic locking on the `locking_column` attribute (`lock_version` by default): update and destroy compare
+  the stored version with the record's and bump it, in a transaction on `Storage::Box`; `StaleObjectError`.
+- Storages answer `supports_transactions?`.
+
 ## 0.2.0 (2026-10-17)
 
 - `Storage::Box` converts rows with tarantool-client (`as: :row`), by the format of the schema each request ran against, and no longer looks up `space_info` before every operation.

data/README.md

@@ -22,19 +22,14 @@ require 'tarantool/model'
 ```ruby
 pool = Tarantool::Client::Pool.new(['tcp://app:secret@db1:3301', 'tcp://app:secret@db2:3301'])
 
-module ApplicationModel
-  def self.included(base)
-    base.include Tarantool::Model
-    base.storage = Tarantool::Model::Storage::Box.new(
-      pool,
-      read:  { mode: :prefer_ro },
-      write: { mode: :rw }
-    )
-  end
-end
+Tarantool::Model.default_storage = Tarantool::Model::Storage::Box.new(
+  pool,
+  read:  { mode: :prefer_ro },
+  write: { mode: :rw }
+)
 
 class User
-  include ApplicationModel
+  include Tarantool::Model
 
   attribute :id,    :integer
   attribute :email, :string
@@ -44,6 +39,10 @@ class User
 end
 ```
 
+`Tarantool::Model.default_storage` serves every model that sets no `storage` of its own; `User.storage = ...`
+overrides it per model. A Proc assigned to it (`Tarantool::Model.default_storage = -> { build_storage }`) is
+called once, on first use, so the connection is opened only when a model needs it.
+
 `Storage::Box` passes its `read:`/`write:` options verbatim to the client's read and write requests. The `Pool`
 routing `mode:` (symbols like `:prefer_ro`, `:rw`; requires a `Pool` as transport) is one example; `timeout:` works
 too. `Storage::Crud` takes no `read:`/`write:`: crud defaults are set on `Tarantool::Crud::Client.new(..., read:,
@@ -119,6 +118,33 @@ user.decrement!(:age)
 Counters skip validations and callbacks. Only the counter attribute and the raw tuple are refreshed from the
 response; other unsaved changes on the record survive. Raises `RecordNotFound` if the row is gone.
 
+### Optimistic locking
+
+```ruby
+class Account
+  include Tarantool::Model
+
+  attribute :id,           :integer
+  attribute :balance,      :decimal
+  attribute :lock_version, :integer, default: 0
+end
+
+Account.locking_column            # => :lock_version
+Account.locking_column = :version # another attribute, or nil to disable
+```
+
+Locking is on when `locking_column` names a declared attribute; the space needs that field. A nil version is
+stored as 0 on create. On update, the row is read again and its version compared with the record's (a value
+assigned by hand, for example from a form field, counts); a different version raises `StaleObjectError`, and so
+does a row changed underneath on destroy. The update sends the changed attributes plus the version incremented
+by one, and the record picks the new version up. Only the version changed sends nothing.
+
+On `Storage::Box` the check and the update run in one transaction (MVCC must be on, as for `transaction`), so a
+concurrent commit on the same row between them surfaces as `StaleObjectError` too. Inside `Model.transaction` no
+second transaction is opened; the check joins the open one. `Storage::Crud` has no transactions: the check runs
+unguarded, and a write between the read and the update goes unnoticed. Counters (`increment!`, `decrement!`)
+bypass locking and leave the version alone.
+
 ## Querying
 
 ```ruby
@@ -259,6 +285,7 @@ A tarantool-schema definition can be passed as is: `MemoryStorage.from_definitio
 | unknown space | `Tarantool::SchemaError` | `Tarantool::Crud::<Operation>Error` |
 | `count` | `NotSupportedError` | counts |
 | `transaction` | rolls back when the block raises | `NotSupportedError` |
+| `supports_transactions?` | `true` | `false` |
 | single-row results | with a tuple | `tuple` is nil |
 
 `verify` (the schema check `Storage::Box` runs on first use) does nothing in `:crud` mode. A nil primary key gets
@@ -288,12 +315,14 @@ Not modelled:
 `to_param` joins a composite key with `-` (e.g. `"7-1"`) for route helpers. `as_json` works through
 `ActiveModel::Serializers::JSON`. `form_with` works with any persisted model.
 
-There is no Railtie. Configure storage in an initializer:
+`tarantool-rails` configures the storage from `config/tarantool.yml`. Without it, set
+`Tarantool::Model.default_storage` in an initializer:
 
 ```ruby
 # config/initializers/tarantool.rb
 pool = Tarantool::Client::Pool.new(Rails.application.config.tarantool_uris)
-User.storage = Tarantool::Model::Storage::Box.new(pool, read: { mode: :prefer_ro }, write: { mode: :rw })
+Tarantool::Model.default_storage =
+  Tarantool::Model::Storage::Box.new(pool, read: { mode: :prefer_ro }, write: { mode: :rw })
 ```
 
 ## Errors
@@ -307,6 +336,7 @@ Tarantool::Model::Error
 ├── RecordInvalid             # #record
 ├── RecordNotSaved            # #record; a before callback aborted
 ├── RecordNotUnique           # duplicate primary or unique secondary key
+├── StaleObjectError          # #record, #attempted_action; the row's version changed since the record was loaded
 ├── SchemaMismatchError       # attribute or primary key does not match the space format
 ├── NotSupportedError         # operation not available for this storage (e.g. count on Storage::Box)
 └── TransactionMismatchError  # write through a storage that has no open transaction in the current fiber

data/lib/tarantool/model/errors.rb

@@ -35,6 +35,17 @@ module Tarantool
       end
     end
 
+    # The row's locking column changed since the record was loaded.
+    class StaleObjectError < Error
+      attr_reader :record, :attempted_action
+
+      def initialize(record, attempted_action)
+        @record = record
+        @attempted_action = attempted_action
+        super("Attempted to #{attempted_action} a stale #{record.class.name} with key #{record.to_key.inspect}")
+      end
+    end
+
     class RecordNotUnique < Error; end
     class SchemaMismatchError < Error; end
     class TransactionMismatchError < Error; end

data/lib/tarantool/model/locking.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Optimistic locking on the attribute named by locking_column, when the model declares it. An update compares
+    # the stored version with the record's and bumps it, inside a transaction on storages that have them, so a
+    # concurrent commit on the same row surfaces as StaleObjectError instead of being overwritten.
+    module Locking
+      extend ActiveSupport::Concern
+
+      ER_TRANSACTION_CONFLICT = 97
+      private_constant :ER_TRANSACTION_CONFLICT
+
+      included do
+        class_attribute :locking_column, instance_accessor: false, default: :lock_version
+      end
+
+      class_methods do
+        def locking_enabled?
+          !locking_column.nil? && attribute_names.include?(locking_column.to_s)
+        end
+      end
+
+      private
+
+      def create_row
+        public_send("#{locking_column}=", 0) if locking_enabled? && public_send(locking_column).nil?
+
+        super
+      end
+
+      def update_pending?
+        return super unless locking_enabled?
+
+        changes.except(locking_column.to_s).any?
+      end
+
+      def updated_row
+        return super unless locking_enabled?
+
+        atomically(:update) do
+          locked_row(:update) || raise(RecordNotFound.new(self.class, key_in_database))
+
+          write_row(locked_operations)
+        end
+      end
+
+      def delete_row
+        return super unless locking_enabled? && persisted?
+
+        atomically(:destroy) do
+          locked_row(:destroy)
+
+          super()
+        end
+      end
+
+      def locked_operations
+        column = locking_column.to_s
+        operations = update_operations.reject { |(_operator, name, _value)| name == column }
+
+        operations << ['=', column, public_send(locking_column).to_i + 1]
+      end
+
+      # The row, or nil when it is gone; a version other than the record's raises.
+      def locked_row(action)
+        row = space_storage.get(space_name, key_in_database)
+        raise StaleObjectError.new(self, action) if row && row.attributes[locking_column] != public_send(locking_column)
+
+        row
+      end
+
+      # Inside an open Model.transaction the check joins it; without transactions (crud) it runs unguarded.
+      def atomically(action, &)
+        storage = writing_storage
+        return yield if Transactions.handle(storage) || !storage.supports_transactions?
+
+        storage.transaction(&)
+      rescue Tarantool::ServerError => e
+        raise StaleObjectError.new(self, action) if e.code == ER_TRANSACTION_CONFLICT
+
+        raise
+      end
+
+      def locking_column = self.class.locking_column
+
+      def locking_enabled? = self.class.locking_enabled?
+    end
+  end
+end

data/lib/tarantool/model/persistence.rb

@@ -80,15 +80,23 @@ module Tarantool
         raise ArgumentError, "the primary key of a persisted #{self.class.name} cannot change" if primary_key_changed?
 
         run_callbacks(:update) do
-          written(updated_row) if changed?
+          written(updated_row) if update_pending?
 
           true
         end
       end
 
+      def update_pending? = changed?
+
       def updated_row
-        operations = changes.map { |name, (_was, value)| ['=', name, value] }
+        write_row(update_operations)
+      end
+
+      def update_operations
+        changes.map { |name, (_was, value)| ['=', name, value] }
+      end
 
+      def write_row(operations)
         writing_storage.update(space_name, key_in_database, operations) ||
           raise(RecordNotFound.new(self.class, key_in_database))
       end

data/lib/tarantool/model/settings.rb

@@ -7,13 +7,22 @@ module Tarantool
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :storage, instance_accessor: false
         class_attribute :primary_key, instance_accessor: false, default: :id
         # @api private
+        class_attribute :_storage, instance_accessor: false
+        # @api private
         class_attribute :_space_name, instance_accessor: false
       end
 
       class_methods do
+        def storage
+          _storage || Tarantool::Model.default_storage
+        end
+
+        def storage=(storage)
+          self._storage = storage
+        end
+
         def space_name
           _space_name || model_name.plural
         end

data/lib/tarantool/model/storage/box.rb

@@ -54,6 +54,8 @@ module Tarantool
           raise NotSupportedError, 'Storage::Box does not count'
         end
 
+        def supports_transactions? = true
+
         def transaction(**options, &block)
           @caller.transaction(**options) do |stream|
             Transactions.open(self, stream, &block)

data/lib/tarantool/model/storage/crud.rb

@@ -48,6 +48,8 @@ module Tarantool
           @crud.space(space).count(conditions(index, key, iterator))
         end
 
+        def supports_transactions? = false
+
         def transaction(**)
           raise NotSupportedError, 'crud has no interactive transactions'
         end

data/lib/tarantool/model/testing/memory_storage/box_mode.rb

@@ -15,6 +15,8 @@ module Tarantool
 
           def transaction! = nil
 
+          def supports_transactions? = true
+
           def get(space, key)
             space.get(key)
           end

data/lib/tarantool/model/testing/memory_storage/crud_mode.rb

@@ -23,6 +23,8 @@ module Tarantool
 
           def sequences? = false
 
+          def supports_transactions? = false
+
           def get(space, key)
             parts = space.info.primary_index.parts.size
             raise Violation.exact_match(parts, key.size) unless key.size == parts

data/lib/tarantool/model/testing/memory_storage.rb

@@ -57,6 +57,8 @@ module Tarantool
           perform(space, :count) { |table| @mode.scan(table, index:, key:, iterator:, after: nil).size }
         end
 
+        def supports_transactions? = @mode.supports_transactions?
+
         # Writes apply at once; the rows are restored unless the block finishes normally. `isolation:` and
         # `timeout:` are accepted and ignored. Sequences are not restored, as in Tarantool.
         def transaction(**, &)

data/lib/tarantool/model/version.rb

@@ -2,6 +2,6 @@
 
 module Tarantool
   module Model
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/tarantool/model.rb

@@ -15,6 +15,7 @@ require_relative 'model/types/binary'
 require_relative 'model/settings'
 require_relative 'model/state'
 require_relative 'model/persistence'
+require_relative 'model/locking'
 require_relative 'model/counters'
 require_relative 'model/relation'
 require_relative 'model/querying'
@@ -27,6 +28,22 @@ module Tarantool
   module Model
     extend ActiveSupport::Concern
 
+    DEFAULT_STORAGE_LOCK = Mutex.new
+    private_constant :DEFAULT_STORAGE_LOCK
+
+    class << self
+      # Storage for models that set none of their own: a storage, or a Proc called once on first use.
+      attr_writer :default_storage
+
+      def default_storage
+        DEFAULT_STORAGE_LOCK.synchronize do
+          @default_storage = @default_storage.call if @default_storage.is_a?(Proc)
+
+          @default_storage
+        end
+      end
+    end
+
     include ActiveModel::API
     include ActiveModel::Attributes
     include ActiveModel::Dirty
@@ -35,6 +52,7 @@ module Tarantool
     include Settings
     include State
     include Persistence
+    include Locking
     include Counters
     include Transactional
     include Querying

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tarantool-model
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Starlexxx
@@ -60,6 +60,7 @@ files:
 - lib/tarantool/model/counters.rb
 - lib/tarantool/model/errors.rb
 - lib/tarantool/model/key.rb
+- lib/tarantool/model/locking.rb
 - lib/tarantool/model/persistence.rb
 - lib/tarantool/model/querying.rb
 - lib/tarantool/model/relation.rb