tarantool-model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb88c7317a6b38d448f89c6ca24ad43f2e7c4b3da9a936795fae74a966b4873e
+  data.tar.gz: c098a1157a2539596e6789d9717c883ed1d135f260d49b44d2018e1b42f53243
+SHA512:
+  metadata.gz: 16b134ac4b0b0efe415455fcd09b4e314bc5ac91ed5e0408cac646298ce49a78d59ce86d74afe981edc9b0c4aacf2bb1ce395206912151e67c637555537d6303
+  data.tar.gz: f9bf98de1e3c83bae3ccf399965e877887556683b8575fc54aa8ac75af2adf53412ee0af175d24dc4e589b01bf564652240cf00c0eab2ebabcbe574f6e515f06

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- `Tarantool::Model` mixin on ActiveModel: attributes, validations, callbacks, dirty tracking, JSON.
+- `Types::UUID`, `Types::Interval`, `Types::Binary`.
+- `Storage::Box` over `Tarantool::Client` and `Pool` with read/write options.
+- Persistence: create, save, update, destroy, reload, increment!, decrement!.
+- Index queries with keyset pagination: find, find_by, where, limit, after, find_each.
+- `Model.transaction` over `Storage::Box`, `TransactionMismatchError` for writes through another storage.
+- `Storage::Crud` over `Tarantool::Crud::Client`; raises `Tarantool::Model::Error` when tarantool-crud is not loaded.
+- Depends on `tarantool-client ~> 0.1.0`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starlexxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,271 @@
+# tarantool-model
+
+ActiveModel-based models for Tarantool 2.11+ and 3.x spaces. Provides attributes, validations, callbacks,
+dirty tracking, JSON serialization, and index-based queries with keyset pagination. This is not ActiveRecord:
+there is no schema migration, no associations, and no query builder. Storage is `Storage::Box` over
+`tarantool-client` or `Storage::Crud` over `tarantool/crud`.
+
+## Installation
+
+Requirements: Ruby >= 3.2, Tarantool 2.11+ or 3.x.
+
+```ruby
+gem 'tarantool-model'
+```
+
+```ruby
+require 'tarantool/model'
+```
+
+## Declaring a 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
+
+class User
+  include ApplicationModel
+
+  attribute :id,    :integer
+  attribute :email, :string
+  attribute :age,   :integer, default: 0
+
+  validates :email, presence: true
+end
+```
+
+`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:,
+write:)` and use crud's own options (strings: `mode: 'read'`).
+
+Attribute names must match the space format field names exactly. `space_name` defaults to the plural model
+name; set it explicitly with `User.space_name = :members`. The primary key defaults to `:id`; set a composite
+key with `User.primary_key = %i[tenant_id id]`.
+
+On the first operation the storage checks that every declared attribute exists in the space format and that
+the primary key matches index 0. A mismatch raises `SchemaMismatchError`.
+
+## Types
+
+| Attribute type | Ruby class |
+|---|---|
+| `:integer` | `Integer` |
+| `:string` | `String` |
+| `:decimal` | `BigDecimal` |
+| `:datetime` | `Time` |
+| `:boolean` | `true` / `false` |
+| `Types::UUID.new` | `Tarantool::Client::UUID` |
+| `Types::Interval.new` | `Tarantool::Client::Interval` |
+| `Types::Binary.new` | `String` with `Encoding::BINARY` |
+
+Custom types are passed as objects, not registered globally in `ActiveModel::Type`. A malformed UUID string
+casts to `nil`. In-place mutation of a Hash or Array value is not tracked as a change — reassign to mark dirty.
+
+```ruby
+attribute :token,      Tarantool::Model::Types::UUID.new
+attribute :period,     Tarantool::Model::Types::Interval.new
+attribute :avatar,     Tarantool::Model::Types::Binary.new
+```
+
+## Persistence
+
+```ruby
+user = User.new(id: 1, email: 'a@b.c', age: 20)
+user.save       # => true / false (runs validations)
+user.save!      # raises RecordInvalid / RecordNotSaved
+
+user = User.create(id: 2, email: 'b@c.d')
+User.create!(id: 3, email: 'c@d.e')
+
+user.update(age: 21)    # assign + save
+user.update!(age: 21)
+user.reload             # re-reads from storage, discards unsaved changes
+user.destroy            # returns self (frozen) or false when a before_destroy callback aborts
+```
+
+Only changed attributes are sent on update. Attributes are refreshed from the row the storage returns after
+every write, so server-side sequences and defaults appear immediately. The primary key cannot change on a
+persisted record.
+
+When the row is gone before an update or reload, `RecordNotFound` is raised. When a `before_*` callback
+throws `:abort`, `save` returns `false` and `save!` raises `RecordNotSaved`.
+
+Callbacks: `before_validation`, `after_validation`, `before_save`, `around_save`, `after_save`,
+`before_create`, `around_create`, `after_create`, `before_update`, `around_update`, `after_update`,
+`before_destroy`, `around_destroy`, `after_destroy`.
+
+### Counters
+
+```ruby
+user.increment!(:age)       # adds 1 on the server
+user.increment!(:age, 5)
+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.
+
+## Querying
+
+```ruby
+User.find(1)                                         # by primary key, raises RecordNotFound
+User.find([tenant_id, id])                           # composite key as Array
+User.find_by(index: :email, key: 'a@b.c')            # first match or nil
+
+User.all                                             # Relation over the primary index
+User.where(index: :age, key: 20, iterator: :ge)      # one index condition
+     .limit(50)
+     .after(last_record)                             # keyset pagination, continues after a tuple
+     .to_a                                           # Array of model instances
+User.where(index: :age, key: 20).first               # limit(1).to_a.first
+
+User.find_each(batch_size: 200) { |user| ... }       # walks in pages, returns Enumerator without block
+```
+
+A `Relation` is `Enumerable` and re-runs the query on every enumeration. `limit` and `after` return new
+immutable relations. Only one `where` per relation is allowed.
+
+Index order is ascending by default. `:lt` and `:le` iterators give descending order, with ties broken by
+primary key descending.
+
+**A relation without `limit` selects every matching row in one request.** Use `find_each` for large result
+sets, or set an explicit `limit`.
+
+`count` without a block or argument delegates to the storage. `Storage::Box` raises `NotSupportedError`
+because IPROTO has no count request and calling `index:count()` in Lua requires execute grants on universe
+that an application user typically lacks. Pass a block or argument to enumerate instead:
+
+```ruby
+User.all.count                               # NotSupportedError on Storage::Box
+User.all.count { |user| user.age > 18 }      # enumerates, returns Integer
+User.all.count(some_user)                    # enumerates, counts elements equal to some_user
+```
+
+## Transactions
+
+`Storage::Box` supports interactive transactions via the Tarantool MVCC engine.
+
+```ruby
+User.transaction(isolation: :read_committed, timeout: 5) do
+  user = User.create!(id: 1, email: 'a@b.c')
+  user.update!(age: 21)
+end
+```
+
+All models in one transaction must share the same storage instance. A write through a different storage
+instance raises `TransactionMismatchError` before sending anything to Tarantool; reads through another
+storage are allowed. If the block raises, the transaction rolls back and the error propagates. In-memory
+record state (attribute values, `persisted?`) is not reverted on rollback. A nested `transaction` call
+raises `Tarantool::TransactionError`. `Storage::Crud` does not support transactions and raises
+`NotSupportedError`.
+
+## Storage::Crud
+
+`Storage::Crud` maps the storage contract onto a `Tarantool::Crud::Client`. Require the `tarantool-crud`
+gem yourself before using it.
+
+```ruby
+require 'tarantool/crud'
+
+crud = Tarantool::Crud::Client.new(Tarantool::Client.new('tcp://app:secret@router:3301'))
+
+class Customer
+  include Tarantool::Model
+
+  self.space_name = :users
+  attribute :id,    :integer
+  attribute :email, :string
+  attribute :age,   :integer, default: 0
+end
+
+Customer.storage = Tarantool::Model::Storage::Crud.new(crud, primary_index: :primary)
+```
+
+Do not declare `bucket_id` as a model attribute; the sharding key is managed by crud and does not need to
+appear in your model. Primary key values must be supplied by the caller; crud cannot route a nil sharding key.
+
+Supported iterators: `eq`, `ge`, `gt`, `le`, `lt`, `all`. Any other iterator raises `ArgumentError`. `count`
+on a relation works. Schema is not verified on the first operation.
+
+**A wrong `primary_index:` name is treated by crud as a field name and silently returns nothing.** This affects
+queries that walk the primary index: `all`, `where`/`find_by` without an index name, and `find_each`. `find` reads
+by key with crud `get` and does not use it. Make sure the index name matches the space definition.
+
+Keyset pagination with `after` requires a tuple, which `select` returns but single-row operations (`find`,
+`find_by`) do not. Calling `after` on a record loaded with `find` raises `ArgumentError`.
+
+## Rails
+
+`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:
+
+```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 })
+```
+
+## Errors
+
+`Tarantool::Model::Error` descends from `Tarantool::Error`, so one `rescue Tarantool::Error` also catches
+client and crud errors.
+
+```
+Tarantool::Model::Error
+├── RecordNotFound            # #model, #key
+├── RecordInvalid             # #record
+├── RecordNotSaved            # #record; a before callback aborted
+├── RecordNotUnique           # duplicate primary or unique secondary key
+├── 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
+```
+
+## Development
+
+```sh
+podman compose -f tarantool-model/docker-compose.yml up -d --wait box-2.11 box-3
+# or: docker compose -f tarantool-model/docker-compose.yml up -d --wait box-2.11 box-3
+
+cd tarantool-model
+bundle exec rspec                                                        # unit specs
+INTEGRATION=1 TARANTOOL_MODEL_URI=tcp://app:secret@localhost:3321 bundle exec rspec  # 2.11
+INTEGRATION=1 TARANTOOL_MODEL_URI=tcp://app:secret@localhost:3322 bundle exec rspec  # 3.x
+```
+
+The `app` user needs `read,write` on universe. Specs truncate spaces through `client.eval`, which requires
+`execute` on universe as well; grant `read,write,execute` if truncation is denied.
+
+For `Storage::Crud` specs, start the crud services (requires the `tarantool-crud` docker image):
+
+```sh
+podman compose -f tarantool-model/docker-compose.yml up -d --wait --build crud-2.11 crud-3
+
+TARANTOOL_MODEL_CRUD_URI=tcp://app:secret@localhost:3331 bundle exec rspec --tag crud  # 2.11
+TARANTOOL_MODEL_CRUD_URI=tcp://app:secret@localhost:3332 bundle exec rspec --tag crud  # 3.x
+```
+
+## Public API
+
+`Tarantool::Model`, `Storage::Box`, `Storage::Crud`, `Types::UUID`, `Types::Interval`, `Types::Binary`,
+`Relation`, and the error classes above.
+
+Everything else, including anything tagged `@api private` in its source comment, is an implementation detail
+and may change in any release.
+
+## License
+
+MIT

data/lib/tarantool/model/counters.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Atomic '+'/'-' on the server, without validations or callbacks. Only the counter is taken from the
+    # response, so other unsaved changes of the record survive.
+    module Counters
+      def increment!(attribute, by = 1)
+        change_counter('+', attribute, by)
+      end
+
+      def decrement!(attribute, by = 1)
+        change_counter('-', attribute, by)
+      end
+
+      private
+
+      def change_counter(operator, attribute, by)
+        row = writing_storage.update(space_name, key_in_database, [[operator, attribute.to_s, by]])
+        raise RecordNotFound.new(self.class, key_in_database) unless row
+
+        @tuple = row.tuple
+        public_send("#{attribute}=", row.attributes.fetch(attribute.to_sym))
+        clear_attribute_changes([attribute])
+
+        self
+      end
+    end
+  end
+end

data/lib/tarantool/model/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    class Error < Tarantool::Error; end
+
+    # No row in the storage for this model's primary key.
+    class RecordNotFound < Error
+      attr_reader :model, :key
+
+      def initialize(model, key)
+        @model = model
+        @key = key
+        super("#{model.name} with key #{key.inspect} not found")
+      end
+    end
+
+    # save! or create! on a record that fails validation.
+    class RecordInvalid < Error
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super(record.errors.full_messages.join(', '))
+      end
+    end
+
+    # A before callback threw :abort.
+    class RecordNotSaved < Error
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super("#{record.class.name} was not saved: a before callback aborted")
+      end
+    end
+
+    class RecordNotUnique < Error; end
+    class SchemaMismatchError < Error; end
+    class TransactionMismatchError < Error; end
+    class NotSupportedError < Error; end
+  end
+end

data/lib/tarantool/model/key.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Index keys are Arrays; Kernel#Array would split a Time or a Hash.
+    # @api private
+    module Key
+      def self.wrap(value)
+        value.is_a?(Array) ? value : [value]
+      end
+    end
+  end
+end

data/lib/tarantool/model/persistence.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # create, save, update, destroy and reload with validations and callbacks. Every write refreshes the
+    # attributes from the row the storage returns, so server-side defaults and sequences show up.
+    module Persistence
+      extend ActiveSupport::Concern
+
+      included do
+        extend ActiveModel::Callbacks
+
+        define_model_callbacks :save, :create, :update, :destroy
+      end
+
+      class_methods do
+        def create(attributes = {})
+          new(attributes).tap(&:save)
+        end
+
+        def create!(attributes = {})
+          new(attributes).tap(&:save!)
+        end
+      end
+
+      def save
+        valid? && persist
+      end
+
+      def save!
+        raise RecordInvalid, self unless valid?
+
+        persist || raise(RecordNotSaved, self)
+      end
+
+      def update(attributes)
+        assign_attributes(attributes)
+
+        save
+      end
+
+      def update!(attributes)
+        assign_attributes(attributes)
+
+        save!
+      end
+
+      # A row that is already gone still counts as destroyed.
+      def destroy
+        return false unless run_callbacks(:destroy) { delete_row }
+
+        freeze
+      end
+
+      def reload
+        row = space_storage.get(space_name, key_in_database)
+        raise RecordNotFound.new(self.class, key_in_database) unless row
+
+        assign_row(row)
+        clear_changes_information
+
+        self
+      end
+
+      private
+
+      def persist
+        run_callbacks(:save) { new_record? ? create_row : update_row }
+      end
+
+      def create_row
+        run_callbacks(:create) do
+          written(writing_storage.insert(space_name, attributes.transform_keys(&:to_sym)))
+
+          @persisted = true
+        end
+      end
+
+      def update_row
+        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?
+
+          true
+        end
+      end
+
+      def updated_row
+        operations = changes.map { |name, (_was, value)| ['=', name, value] }
+
+        writing_storage.update(space_name, key_in_database, operations) ||
+          raise(RecordNotFound.new(self.class, key_in_database))
+      end
+
+      def delete_row
+        writing_storage.delete(space_name, key_in_database) if persisted?
+
+        @destroyed = true
+      end
+
+      def primary_key_changed?
+        self.class.primary_key_names.any? { |name| attribute_changed?(name.to_s) }
+      end
+    end
+  end
+end

data/lib/tarantool/model/querying.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Class-level reads; everything but find goes through a Relation.
+    module Querying
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def all = Relation.new(self)
+
+        def where(...) = all.where(...)
+
+        def find_each(...) = all.find_each(...)
+
+        def count = all.count
+
+        def find_by(index:, key:) = where(index:, key:).first
+
+        def find(key)
+          key = Key.wrap(key)
+          row = verified_storage.get(space_name, key)
+          raise RecordNotFound.new(self, key) unless row
+
+          instantiate(row)
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/relation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # An immutable query over one index condition. The query runs on every enumeration; results are not cached.
+    # Order is the index order (descending for :le/:lt); pagination is keyset only, with #after.
+    class Relation
+      include Enumerable
+
+      DEFAULTS = { index: nil, key: [], iterator: :all, limit: nil, after: nil, filtered: false }.freeze
+      QUERY = %i[index key iterator].freeze
+
+      def initialize(model, **options)
+        @model = model
+        @options = DEFAULTS.merge(options).freeze
+        freeze
+      end
+
+      def where(index: nil, key: [], iterator: :eq)
+        raise ArgumentError, 'a relation takes one index condition, where was already called' if @options[:filtered]
+
+        spawn(index:, key: Key.wrap(key), iterator:, filtered: true)
+      end
+
+      def limit(count)
+        spawn(limit: count)
+      end
+
+      def after(record)
+        raise ArgumentError, "#{record.class.name} has no tuple to continue after" unless record.tuple
+
+        spawn(after: record.tuple)
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        rows.each { |row| yield @model.instantiate(row) }
+      end
+
+      def first(count = nil)
+        count ? limit(count).to_a : limit(1).to_a.first
+      end
+
+      # Every match of the index condition: limit and after are ignored.
+      # With a block or argument, delegates to Enumerable#count (enumerates).
+      def count(*args, &block)
+        return @model.verified_storage.count(@model.space_name, **@options.slice(*QUERY)) if args.empty? && !block
+
+        super
+      end
+
+      def find_each(batch_size: 1000, &block)
+        return enum_for(:find_each, batch_size:) unless block
+
+        relation = limit(batch_size)
+
+        loop do
+          batch = relation.to_a
+          batch.each(&block)
+          break if batch.size < batch_size
+
+          relation = relation.after(batch.last)
+        end
+      end
+
+      private
+
+      def rows
+        @model.verified_storage.select(@model.space_name, **@options.slice(*QUERY, :limit, :after))
+      end
+
+      def spawn(**changes)
+        self.class.new(@model, **@options, **changes)
+      end
+    end
+  end
+end

data/lib/tarantool/model/row.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # What a storage returns for one row: attributes by Symbol name, and the raw tuple as the server returned it,
+    # or nil when the storage has none.
+    # @api private
+    Row = Data.define(:attributes, :tuple)
+  end
+end

data/lib/tarantool/model/settings.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Storage, space name and primary key of a model class, inherited by subclasses.
+    module Settings
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :storage, instance_accessor: false
+        class_attribute :primary_key, instance_accessor: false, default: :id
+        # @api private
+        class_attribute :_space_name, instance_accessor: false
+      end
+
+      class_methods do
+        def space_name
+          _space_name || model_name.plural
+        end
+
+        def space_name=(name)
+          self._space_name = name
+        end
+
+        def primary_key_names
+          Array(primary_key)
+        end
+
+        # The schema check runs once per class and storage, before the first operation.
+        # @api private
+        def verified_storage
+          current = storage
+          raise Error, "#{name}.storage is not set" unless current
+          return current if @verified_storage.equal?(current)
+
+          current.verify(space_name, attributes: attribute_names.map(&:to_sym), primary_key: primary_key_names)
+
+          @verified_storage = current
+        end
+
+        # @api private
+        def writing_storage
+          verified_storage.tap { |s| Transactions.check_write!(s) }
+        end
+      end
+
+      def to_key
+        self.class.primary_key_names.map { |name| public_send(name) } if persisted?
+      end
+    end
+  end
+end

data/lib/tarantool/model/state.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Persistence state and the raw tuple a record was loaded from or last written with; Relation#after
+    # continues past that tuple.
+    module State
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # @api private
+        def instantiate(row)
+          new.tap { |record| record.send(:init_with_row, row) }
+        end
+      end
+
+      attr_reader :tuple
+
+      def new_record? = !@persisted
+
+      def persisted? = @persisted == true && !destroyed?
+
+      def destroyed? = @destroyed == true
+
+      # Assigning to a destroyed record must fail; freezing self alone leaves the attribute set writable.
+      def freeze
+        @attributes = @attributes.clone.freeze
+
+        super
+      end
+
+      private
+
+      def init_with_row(row)
+        assign_row(row)
+        clear_changes_information
+
+        @persisted = true
+      end
+
+      def assign_row(row)
+        @tuple = row.tuple
+
+        assign_attributes(row.attributes.slice(*self.class.attribute_names.map(&:to_sym)))
+      end
+
+      def written(row)
+        assign_row(row)
+
+        changes_applied
+      end
+
+      def key_in_database
+        self.class.primary_key_names.map { |name| attribute_was(name.to_s) }
+      end
+
+      def space_storage = self.class.verified_storage
+
+      def writing_storage = self.class.writing_storage
+
+      def space_name = self.class.space_name
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Storage
+      class Box
+        # Field order of a space: converts attribute Hashes to tuples and back, and checks a model against the
+        # format. Fields the model does not declare go out as nil and are ignored on read.
+        # @api private
+        class Layout
+          def initialize(space_info)
+            @space_info = space_info
+            @names = space_info.fields.map { |field| field.name.to_sym }
+          end
+
+          def to_tuple(attributes)
+            @names.map { |name| attributes[name] }
+          end
+
+          def to_row(tuple)
+            Row.new(attributes: @names.zip(tuple).to_h, tuple:)
+          end
+
+          def verify!(attributes:, primary_key:)
+            missing = attributes - @names
+            raise SchemaMismatchError, "space #{@space_info.name} has no field #{missing.join(', ')}" if missing.any?
+            raise SchemaMismatchError, "space #{@space_info.name} has no primary index" unless @space_info.primary_index
+
+            return if primary_key == primary_parts
+
+            raise SchemaMismatchError,
+                  "primary key #{primary_key.inspect} does not match the parts of index 0: #{primary_parts.inspect}"
+          end
+
+          private
+
+          def primary_parts
+            @space_info.primary_index&.parts&.map { |part| part.name&.to_sym }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Storage
+      # Storage over a Tarantool::Client or Client::Pool. `read` options go to get and select, `write` options
+      # to insert, update and delete, verbatim. The format comes from the client's schema on every call, so
+      # alter and reconnect are picked up without a cache here. Inside Model.transaction operations, including
+      # space_info, go through the open stream.
+      class Box
+        ER_TUPLE_FOUND = 3
+        private_constant :ER_TUPLE_FOUND
+
+        def initialize(caller, read: {}, write: {})
+          if [read, write].any? { |options| options.key?(:mode) } && !caller.is_a?(Tarantool::Client::Pool)
+            raise ArgumentError, 'mode: needs a Tarantool::Client::Pool'
+          end
+
+          @caller = caller
+          @read_options = read
+          @write_options = write
+        end
+
+        def verify(space, attributes:, primary_key:)
+          layout(space, read).verify!(attributes:, primary_key:)
+        end
+
+        def get(space, key)
+          layout = layout(space, read)
+          tuple = client.select(space, key, limit: 1, **read).first
+
+          tuple && layout.to_row(tuple)
+        end
+
+        def insert(space, attributes)
+          layout = layout(space, write)
+          tuple = unique { client.insert(space, layout.to_tuple(attributes), **write) }
+
+          layout.to_row(tuple)
+        end
+
+        def update(space, key, operations)
+          layout = layout(space, write)
+          tuple = unique { client.update(space, key, operations, **write) }
+
+          tuple && layout.to_row(tuple)
+        end
+
+        def delete(space, key)
+          layout = layout(space, write)
+          tuple = client.delete(space, key, **write)
+
+          tuple && layout.to_row(tuple)
+        end
+
+        def select(space, index:, key:, iterator:, limit:, after:)
+          layout = layout(space, read)
+          options = { index: index || 0, iterator:, after:, **read }
+          options[:limit] = limit if limit
+
+          client.select(space, key, **options).map { |tuple| layout.to_row(tuple) }
+        end
+
+        # IPROTO has no count request, and calling box.space.X.index.Y:count needs execute grants
+        # (lua_call on 3.x, universe on 2.11) that an application user usually lacks.
+        def count(_space, **)
+          raise NotSupportedError, 'Storage::Box does not count'
+        end
+
+        def transaction(**options, &block)
+          @caller.transaction(**options) do |stream|
+            Transactions.open(self, stream, &block)
+          end
+        end
+
+        private
+
+        def client
+          Transactions.handle(self) || @caller
+        end
+
+        def read
+          scoped(@read_options)
+        end
+
+        def write
+          scoped(@write_options)
+        end
+
+        def scoped(options)
+          Transactions.handle(self) ? options.except(:mode) : options
+        end
+
+        def layout(space, options)
+          Layout.new(client.space_info(space, **options.slice(:mode, :timeout)))
+        end
+
+        def unique
+          yield
+        rescue Tarantool::ServerError => e
+          raise RecordNotUnique, e.message if e.code == ER_TUPLE_FOUND
+
+          raise
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Storage
+      # Storage over a Tarantool::Crud::Client; read/write defaults live in that client. crud has no schema
+      # lookup, so the format is not checked and `index: nil` means the index named `primary_index:`. crud
+      # reads an unknown index name as a field name and returns nothing, so that name must be right.
+      # Single-row operations return no tuple; only select rows can be continued after.
+      class Crud
+        OPERATORS = { eq: '==', ge: '>=', gt: '>', le: '<=', lt: '<' }.freeze
+        DUPLICATE_KEY = /Duplicate key exists/
+
+        # tarantool-model doesn't depend on tarantool-crud, yet rescues its errors.
+        def initialize(crud, primary_index: :primary)
+          raise Error, "tarantool-crud is not loaded; require 'tarantool/crud'" unless defined?(Tarantool::Crud)
+
+          @crud = crud
+          @primary_index = primary_index
+        end
+
+        def verify(*, **) = nil
+
+        def get(space, key)
+          row(@crud.space(space).get(key))
+        end
+
+        def insert(space, attributes)
+          row(unique { @crud.space(space).insert(attributes) })
+        end
+
+        def update(space, key, operations)
+          row(unique { @crud.space(space).update(key, operations) })
+        end
+
+        def delete(space, key)
+          row(@crud.space(space).delete(key))
+        end
+
+        def select(space, index:, key:, iterator:, limit:, after:)
+          options = { first: limit, after: }.compact
+          result = @crud.space(space).select(conditions(index, key, iterator), **options)
+
+          result.zip(result.tuples).map { |attributes, tuple| Row.new(attributes:, tuple:) }
+        end
+
+        def count(space, index:, key:, iterator:)
+          @crud.space(space).count(conditions(index, key, iterator))
+        end
+
+        def transaction(**)
+          raise NotSupportedError, 'crud has no interactive transactions'
+        end
+
+        private
+
+        def row(attributes)
+          attributes && Row.new(attributes:, tuple: nil)
+        end
+
+        def conditions(index, key, iterator)
+          return if iterator == :all
+
+          operator = OPERATORS.fetch(iterator) { raise ArgumentError, "crud has no condition for #{iterator.inspect}" }
+          return if key.empty?
+
+          [[operator, (index || @primary_index).to_s, key]]
+        end
+
+        def unique
+          yield
+        rescue Tarantool::Crud::InsertError, Tarantool::Crud::UpdateError => e
+          raise RecordNotUnique, e.message if e.message.match?(DUPLICATE_KEY)
+
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/transactional.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Model.transaction delegates to the storage; every model sharing that storage instance writes through the
+    # open transaction. In-memory record state is not reverted on rollback.
+    module Transactional
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def transaction(**, &)
+          verified_storage.transaction(**, &)
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/transactions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    # Open transactions of the current fiber, keyed by storage instance (Thread#[] is fiber-local). A model
+    # whose storage has no open transaction would write outside the one that is open, and commit on its own.
+    # @api private
+    module Transactions
+      KEY = :tarantool_model_transactions
+      MISMATCH = 'a write through another storage inside a transaction would commit outside it; ' \
+                 'models in one transaction must share one storage instance'
+
+      module_function
+
+      def open(storage, handle)
+        registry = current
+        registry[storage] = handle
+
+        yield
+      ensure
+        registry&.delete(storage)
+      end
+
+      def handle(storage)
+        current[storage]
+      end
+
+      def check_write!(storage)
+        registry = current
+        return if registry.empty? || registry.key?(storage)
+
+        raise TransactionMismatchError, MISMATCH
+      end
+
+      def current
+        Thread.current[KEY] ||= {}.compare_by_identity
+      end
+    end
+  end
+end

data/lib/tarantool/model/types/binary.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Types
+      # varbinary: msgpack sends an ASCII-8BIT String as bin and a UTF-8 one as str.
+      class Binary < ActiveModel::Type::Value
+        def type = :binary
+
+        private
+
+        def cast_value(value)
+          value.is_a?(String) ? value.b : value
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/types/interval.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Types
+      # MP_EXT interval; a Hash of units (e.g. from params) builds one.
+      class Interval < ActiveModel::Type::Value
+        def type = :interval
+
+        private
+
+        def cast_value(value)
+          value.is_a?(Hash) ? Tarantool::Client::Interval.new(**value.transform_keys(&:to_sym)) : value
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/types/uuid.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Types
+      # MP_EXT uuid. A malformed String casts to nil, as Rails' uuid types do.
+      class UUID < ActiveModel::Type::Value
+        def type = :uuid
+
+        private
+
+        def cast_value(value)
+          return value if value.is_a?(Tarantool::Client::UUID)
+          return unless value.is_a?(String) && value.match?(Tarantool::Client::UUID::FORMAT)
+
+          Tarantool::Client::UUID.new(value:)
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    VERSION = '0.1.0'
+  end
+end

data/lib/tarantool/model.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'tarantool/client'
+
+require_relative 'model/version'
+require_relative 'model/errors'
+require_relative 'model/row'
+require_relative 'model/key'
+require_relative 'model/transactions'
+require_relative 'model/transactional'
+require_relative 'model/types/uuid'
+require_relative 'model/types/interval'
+require_relative 'model/types/binary'
+require_relative 'model/settings'
+require_relative 'model/state'
+require_relative 'model/persistence'
+require_relative 'model/counters'
+require_relative 'model/relation'
+require_relative 'model/querying'
+require_relative 'model/storage/box/layout'
+require_relative 'model/storage/box'
+require_relative 'model/storage/crud'
+
+module Tarantool
+  # ActiveModel-based model over a Tarantool space. Attribute names are the space format field names.
+  module Model
+    extend ActiveSupport::Concern
+
+    include ActiveModel::API
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
+    include ActiveModel::Validations::Callbacks
+    include ActiveModel::Serializers::JSON
+    include Settings
+    include State
+    include Persistence
+    include Counters
+    include Transactional
+    include Querying
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: tarantool-model
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Starlexxx
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: tarantool-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Attributes, validations, callbacks, dirty tracking and index-based queries
+  with keyset pagination over Tarantool 2.11+ and 3.x spaces, through tarantool-client
+  or tarantool-crud.
+email:
+- apavlovskiy088@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/tarantool/model.rb
+- lib/tarantool/model/counters.rb
+- lib/tarantool/model/errors.rb
+- lib/tarantool/model/key.rb
+- lib/tarantool/model/persistence.rb
+- lib/tarantool/model/querying.rb
+- lib/tarantool/model/relation.rb
+- lib/tarantool/model/row.rb
+- lib/tarantool/model/settings.rb
+- lib/tarantool/model/state.rb
+- lib/tarantool/model/storage/box.rb
+- lib/tarantool/model/storage/box/layout.rb
+- lib/tarantool/model/storage/crud.rb
+- lib/tarantool/model/transactional.rb
+- lib/tarantool/model/transactions.rb
+- lib/tarantool/model/types/binary.rb
+- lib/tarantool/model/types/interval.rb
+- lib/tarantool/model/types/uuid.rb
+- lib/tarantool/model/version.rb
+homepage: https://github.com/Starlexxx/tarantool-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Starlexxx/tarantool-ruby/tree/master/tarantool-model
+  changelog_uri: https://github.com/Starlexxx/tarantool-ruby/blob/master/tarantool-model/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Starlexxx/tarantool-ruby/issues
+  homepage_uri: https://github.com/Starlexxx/tarantool-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: ActiveModel-based models for Tarantool spaces
+test_files: []