tarantool-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 824fd7e958e18a4576a55a510ae6713557bb7d0e6a36ce202f18d72785eb18ef
+  data.tar.gz: e33adb1ed56190a0d11f32c1994a71f2e247c2548e30bb594344b581794f03ba
+SHA512:
+  metadata.gz: cd86cbe614985b58a745dfa2807df813e8b1eb95f7ea0a044f26f0a539577c15dac3cbeffa33bcec5774c31583a9a324a7706fbbb72ba16392a4c7e46088bd2f
+  data.tar.gz: 5afa1af094609b0ed6f6637b7a1aa08dbe6afcf8b9ae3cda57031ad0f4a3565bb23ff204e37c5e9f779366cc916fdcb83025f8dec3de43501eda8b9ae5f90451

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-10-17)
+
+First release.
+
+- `config/tarantool.yml` per environment through `config_for`; `Tarantool::Rails.config`, `pool` (one per
+  process), `storage`, `schema`, `admin_client`, `disconnect!`.
+- Models use the configured storage through `Tarantool::Model.default_storage`, built on first use.
+- `Tarantool::Rails::LogSubscriber`: ActiveRecord-style request and lifecycle lines; `ControllerRuntime` adds
+  `Tarantool: 1.2ms` to "Completed" lines.
+- Rake tasks `tarantool:schema:plan`, `apply` and `check`.
+- Generators `tarantool:install` and `tarantool:model`.
+- Depends on `railties >= 7.1, < 9`, `tarantool-client ~> 0.2`, `tarantool-model ~> 0.3`, `tarantool-schema ~> 0.1`.

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,217 @@
+# tarantool-rails
+
+Rails integration for [tarantool-client](../tarantool-client), [tarantool-model](../tarantool-model) and
+[tarantool-schema](../tarantool-schema). One gem gives an application `config/tarantool.yml` per environment,
+one connection pool per process, models on that pool without an initializer, ActiveRecord-style request lines
+in the Rails log with a `Tarantool: 1.2ms` share in "Completed" lines, `tarantool:schema:*` rake tasks and
+generators for the configuration and for models.
+
+## Installation
+
+Requirements: Ruby >= 3.2, Rails 7.1+, Tarantool 2.11+ or 3.x.
+
+```ruby
+gem 'tarantool-rails'
+gem 'tarantool-crud'   # only for storage: crud
+```
+
+```sh
+rails g tarantool:install   # config/tarantool.yml and config/tarantool_schema.rb
+```
+
+## config/tarantool.yml
+
+Read with `config_for`, so ERB, a `shared` section and the environment sections work as in `database.yml`.
+
+```yaml
+default: &default
+  user: app
+  password: <%= ENV["TARANTOOL_PASSWORD"] %>
+  connect_timeout: 3
+  request_timeout: 10
+
+development:
+  <<: *default
+  addresses: [tcp://localhost:3301]
+  admin_uri: tcp://app:secret@localhost:3301
+
+test:
+  <<: *default
+  addresses: [tcp://localhost:3301]
+
+production:
+  <<: *default
+  addresses:
+    - tcp://db1:3301
+    - tcp://db2:3301
+  read:  { mode: prefer_ro }
+  write: { mode: rw }
+  admin_uri: <%= ENV["TARANTOOL_ADMIN_URI"] %>
+```
+
+| Key | |
+|---|---|
+| `addresses` | required, Array of URIs; `address` with a single String is accepted too |
+| `user`, `password`, `connect_timeout`, `request_timeout`, `reconnect`, `reconnect_attempts`, `reconnect_delay`, `reconnect_max_delay`, `max_frame_size` | passed to `Tarantool::Client::Pool.new` as they are |
+| `read`, `write` | options for `Storage::Box`: `mode` (`prefer_ro`, `rw`, ...) and `timeout` |
+| `storage` | `box` (default) or `crud` |
+| `crud` | for `storage: crud`: `primary_index` (default `primary`), `read`, `write` and `timeout_margin` for `Tarantool::Crud::Client.new` |
+| `admin_uri` | connection for the schema rake tasks, a user that may create spaces |
+
+Any other key raises `ArgumentError` at boot. A missing file is not an error at boot, so the install generator
+can run; the first model operation then raises `Tarantool::Rails::Error`.
+
+## What the Railtie does
+
+- `Tarantool::Rails.config` holds the environment section as a `Configuration` (its `inspect` hides the
+  password).
+- `Tarantool::Rails.pool` is one `Tarantool::Client::Pool` per process, built on first use with
+  `instrumenter: ActiveSupport::Notifications`. After `fork` the pool reopens its connections on its own.
+- `Tarantool::Rails.storage` is a `Storage::Box` (or `Storage::Crud`) over the pool, and
+  `Tarantool::Model.default_storage` is set so every model without a storage of its own uses it. Nothing
+  connects until a model is used.
+- `Tarantool::Rails::LogSubscriber` writes a line per request and `ControllerRuntime` adds the Tarantool time
+  to "Completed" lines; turn both off with `config.tarantool.log = false`.
+- `Tarantool::Rails.schema` is the `Tarantool::Schema::Definition` from `config/tarantool_schema.rb`
+  (`config.tarantool.schema_path` changes the file).
+- `Tarantool::Rails.disconnect!` closes the pool; the next use builds a new one.
+
+```ruby
+class User
+  include Tarantool::Model
+
+  attribute :id,    :integer
+  attribute :email, :string
+end
+
+User.create!(email: 'a@b.c')   # through Tarantool::Rails.storage
+```
+
+## Log
+
+```
+Tarantool insert users (0.31ms) db1:3301
+Tarantool select users by email (0.18ms) db2:3301
+Tarantool call user.touch (0.42ms) db1:3301
+Tarantool execute (0.57ms) SELECT COUNT(*) FROM "users" db1:3301
+Tarantool update users (0.26ms) db1:3301 Tarantool::ServerError(3)
+Completed 200 OK in 4ms (Views: 1.9ms | Tarantool: 0.5ms)
+```
+
+Request lines are debug, colored like ActiveRecord's when `colorize_logging` is on. Keys, tuples and
+arguments never appear: the client does not put them in the event payload. A failed request shows the error
+class and code, not the message. Lifecycle events are logged too: `disconnect` at warn, `reconnect_failed` at
+error, `reconnect`, `fork` and `role_change` at info.
+
+## Schema
+
+`config/tarantool_schema.rb` assigns the definition:
+
+```ruby
+Tarantool::Rails.schema = Tarantool::Schema::Definition.new do
+  ensure_space :users,
+               format: [{ name: :id, type: :unsigned }, { name: :email, type: :string }],
+               indexes: [{ name: :primary, parts: [:id], sequence: true }, { name: :email, parts: [:email] }]
+end
+```
+
+| Task | |
+|---|---|
+| `rails tarantool:schema:plan` | prints what `apply` would create; drift raises `MismatchError` with the diff |
+| `rails tarantool:schema:apply` | creates the missing spaces and indexes and prints them; never alters or drops |
+| `rails tarantool:schema:check` | for CI: exits 1 and prints `pending: ...` when anything would be created, 0 when live equals declared |
+
+The tasks connect with `admin_uri`; see the tarantool-schema README for the privileges that user needs.
+
+## Generators
+
+```sh
+rails g tarantool:model User email:string age:unsigned? token:uuid
+```
+
+writes `app/models/user.rb`
+
+```ruby
+class User
+  include Tarantool::Model
+
+  attribute :id, :integer
+  attribute :email, :string
+  attribute :age, :integer
+  attribute :token, Tarantool::Model::Types::UUID.new
+end
+```
+
+and adds the space to `config/tarantool_schema.rb` (skip with `--skip-schema`):
+
+```ruby
+  ensure_space :users,
+               format: [
+                 { name: :id, type: :unsigned },
+                 { name: :email, type: :string },
+                 { name: :age, type: :unsigned, is_nullable: true },
+                 { name: :token, type: :uuid }
+               ],
+               indexes: [
+                 { name: :primary, parts: [:id], sequence: true }
+               ]
+```
+
+`id` is added first as `unsigned` with a sequence unless you list it yourself. A `?` suffix makes the field
+nullable. Types: `integer`, `unsigned`, `string`, `boolean`, `decimal`, `datetime`, `uuid`, `interval`,
+`binary`. `Admin::User` gets the space `admin_users`, the plural tarantool-model uses.
+
+## Testing
+
+Point the default storage at tarantool-model's in-memory storage, built from the same declaration the deploy
+applies. No connection is made in the test environment unless something reads `Tarantool::Rails.pool`.
+
+```ruby
+# spec/rails_helper.rb
+require 'tarantool/model/testing'
+
+RSpec.configure do |config|
+  config.before do
+    Tarantool::Model.default_storage = Tarantool::Model::Testing::MemoryStorage.from_definition(Tarantool::Rails.schema)
+  end
+end
+```
+
+## storage: crud
+
+```yaml
+production:
+  addresses: [tcp://router1:3301, tcp://router2:3301]
+  storage: crud
+  crud:
+    primary_index: primary
+    read:  { mode: read, prefer_replica: true }
+```
+
+Models then go through `Tarantool::Model::Storage::Crud` over `Tarantool::Crud::Client`; the `tarantool-crud`
+gem must be in the Gemfile.
+
+## Public API
+
+`Tarantool::Rails` (`config`, `pool`, `storage`, `schema`, `admin_client`, `disconnect!`),
+`Tarantool::Rails::Configuration`, `Tarantool::Rails::LogSubscriber`, `Tarantool::Rails::Error`
+(descends from `Tarantool::Error`), the rake tasks and the generators.
+
+Everything else, including anything tagged `@api private` in its source comment, is an implementation detail
+and may change in any release.
+
+## Development
+
+```sh
+podman compose -f tarantool-client/docker-compose.yml up -d --wait tarantool-2.11 tarantool-3
+# or: docker compose -f tarantool-client/docker-compose.yml up -d --wait tarantool-2.11 tarantool-3
+
+cd tarantool-rails
+bundle exec rspec                                                                 # unit
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3301 bundle exec rspec    # 2.11
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3302 bundle exec rspec    # 3.x
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

data/lib/generators/tarantool/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Tarantool
+  module Generators
+    # rails g tarantool:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_configuration
+        copy_file 'tarantool.yml', 'config/tarantool.yml'
+      end
+
+      def create_schema
+        copy_file 'tarantool_schema.rb', 'config/tarantool_schema.rb'
+      end
+    end
+  end
+end

data/lib/generators/tarantool/install/templates/tarantool.yml

@@ -0,0 +1,24 @@
+# Every key is documented in the tarantool-rails README. The file goes through ERB like database.yml.
+default: &default
+  user: app
+  password: <%= ENV["TARANTOOL_PASSWORD"] %>
+  connect_timeout: 3
+  request_timeout: 10
+
+development:
+  <<: *default
+  addresses: [tcp://localhost:3301]
+  admin_uri: <%= ENV.fetch("TARANTOOL_ADMIN_URI", "tcp://app:secret@localhost:3301") %>
+
+test:
+  <<: *default
+  addresses: [tcp://localhost:3301]
+
+production:
+  <<: *default
+  addresses:
+    - tcp://db1:3301
+    - tcp://db2:3301
+  read:  { mode: prefer_ro }
+  write: { mode: rw }
+  admin_uri: <%= ENV["TARANTOOL_ADMIN_URI"] %>

data/lib/generators/tarantool/install/templates/tarantool_schema.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Applied by `rails tarantool:schema:apply`; `rails g tarantool:model` adds spaces here.
+Tarantool::Rails.schema = Tarantool::Schema::Definition.new do
+  # ensure_space :users,
+  #              format: [{ name: :id, type: :unsigned }, { name: :email, type: :string }],
+  #              indexes: [{ name: :primary, parts: [:id], sequence: true }, { name: :email, parts: [:email] }]
+end

data/lib/generators/tarantool/model/model_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+module Tarantool
+  module Generators
+    # rails g tarantool:model User email:string age:unsigned?
+    class ModelGenerator < ::Rails::Generators::NamedBase
+      Field = Data.define(:name, :attribute_type, :field_type, :nullable) do
+        def declaration
+          "{ name: :#{name}, type: :#{field_type}#{', is_nullable: true' if nullable} }"
+        end
+      end
+
+      TYPES = {
+        'integer' => [':integer', 'integer'], 'unsigned' => [':integer', 'unsigned'], 'string' => [':string', 'string'],
+        'boolean' => [':boolean', 'boolean'], 'decimal' => [':decimal', 'decimal'],
+        'datetime' => [':datetime', 'datetime'], 'uuid' => ['Tarantool::Model::Types::UUID.new', 'uuid'],
+        'interval' => ['Tarantool::Model::Types::Interval.new', 'interval'],
+        'binary' => ['Tarantool::Model::Types::Binary.new', 'varbinary']
+      }.freeze
+      ID = Field.new(name: 'id', attribute_type: ':integer', field_type: 'unsigned', nullable: false)
+      SCHEMA_PATH = 'config/tarantool_schema.rb'
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :fields, type: :array, default: [], banner: 'name:type name:type?'
+      class_option :skip_schema, type: :boolean, default: false, desc: "Do not add the space to #{SCHEMA_PATH}"
+
+      # Runs before any file is written so an unknown type leaves nothing behind.
+      def parse_fields
+        model_fields
+      end
+
+      def create_model_file
+        template 'model.rb.tt', File.join('app/models', class_path, "#{file_name}.rb")
+      end
+
+      def add_space_to_schema
+        return if options[:skip_schema] || !File.exist?(File.join(destination_root, SCHEMA_PATH))
+
+        inject_into_file SCHEMA_PATH, space_declaration, before: /^end\s*\z/
+      end
+
+      private
+
+      def model_fields
+        @model_fields ||= begin
+          declared = fields.map { |field| parse(field) }
+          declared.any? { |field| field.name == 'id' } ? declared : [ID, *declared]
+        end
+      end
+
+      def parse(field)
+        name, type = field.split(':', 2)
+        raise Thor::Error, "#{field}: expected name:type" if type.nil? || type.empty?
+
+        nullable = type.end_with?('?')
+        attribute_type, field_type = TYPES[type.delete_suffix('?')]
+        raise Thor::Error, "unknown type #{type} for #{name}; use one of #{TYPES.keys.join(', ')}" unless attribute_type
+
+        Field.new(name:, attribute_type:, field_type:, nullable:)
+      end
+
+      def space_declaration
+        sequence = model_fields.first.equal?(ID) ? ', sequence: true' : ''
+        lines = ["ensure_space :#{plural_table_name},", '             format: [',
+                 model_fields.map { |field| "               #{field.declaration}" }.join(",\n"),
+                 '             ],', '             indexes: [',
+                 "               { name: :primary, parts: [:#{model_fields.first.name}]#{sequence} }", '             ]']
+
+        "\n#{lines.join("\n").gsub(/^/, '  ')}\n"
+      end
+    end
+  end
+end

data/lib/generators/tarantool/model/templates/model.rb.tt

@@ -0,0 +1,9 @@
+<% module_namespacing do -%>
+class <%= class_name %>
+  include Tarantool::Model
+
+<% model_fields.each do |field| -%>
+  attribute :<%= field.name %>, <%= field.attribute_type %>
+<% end -%>
+end
+<% end -%>

data/lib/tarantool/rails/configuration.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Rails
+    # One environment section of config/tarantool.yml, validated and split by consumer: addresses and client
+    # options go to the Pool, read/write to Storage::Box, crud to the crud client, admin_uri to the rake tasks.
+    Configuration = Data.define(:addresses, :client_options, :storage, :read, :write, :crud, :admin_uri) do
+      def inspect
+        fields = to_h.map { |key, value| "#{key}=#{filtered(key, value).inspect}" }.join(', ')
+
+        "#<data #{self.class.name} #{fields}>"
+      end
+      alias_method :to_s, :inspect
+
+      private
+
+      def filtered(key, value)
+        case key
+        when :client_options then value.key?(:password) ? value.merge(password: '[FILTERED]') : value
+        when :admin_uri then value&.sub(%r{:[^:@/]*@}, ':[FILTERED]@')
+        else value
+        end
+      end
+    end
+
+    # Builds a Configuration from the Hash config_for returns.
+    class Configuration
+      CLIENT_KEYS = %i[user password connect_timeout request_timeout reconnect reconnect_attempts reconnect_delay
+                       reconnect_max_delay max_frame_size].freeze
+      KEYS = (CLIENT_KEYS + %i[addresses address read write storage crud admin_uri]).freeze
+      CRUD_KEYS = %i[primary_index read write timeout_margin].freeze
+      STORAGES = %i[box crud].freeze
+
+      class << self
+        def from_hash(hash)
+          hash = checked(hash.to_h.transform_keys(&:to_sym))
+
+          new(addresses: addresses(hash), client_options: hash.slice(*CLIENT_KEYS), storage: storage(hash[:storage]),
+              read: options(hash[:read]), write: options(hash[:write]), crud: crud(hash[:crud]),
+              admin_uri: hash[:admin_uri])
+        end
+
+        private
+
+        def checked(hash)
+          unknown = hash.keys - KEYS
+          raise ArgumentError, "unknown key #{unknown.first} in config/tarantool.yml" if unknown.any?
+
+          hash
+        end
+
+        def addresses(hash)
+          addresses = Array(hash[:addresses] || hash[:address])
+          raise ArgumentError, 'addresses is required in config/tarantool.yml' if addresses.empty?
+
+          addresses
+        end
+
+        def storage(value)
+          storage = (value || :box).to_sym
+          raise ArgumentError, "storage must be box or crud, got #{value.inspect}" unless STORAGES.include?(storage)
+
+          storage
+        end
+
+        def options(hash)
+          options = (hash || {}).to_h.transform_keys(&:to_sym)
+          options[:mode] = options[:mode].to_sym if options.key?(:mode)
+
+          options
+        end
+
+        def crud(hash)
+          crud = { primary_index: :primary }.merge((hash || {}).to_h.transform_keys(&:to_sym))
+          unknown = crud.keys - CRUD_KEYS
+          raise ArgumentError, "unknown key #{unknown.first} in crud" if unknown.any?
+
+          crud.merge(primary_index: crud[:primary_index].to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/rails/controller_runtime.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/attr_internal'
+
+module Tarantool
+  module Rails
+    # Adds the time spent in Tarantool requests to the "Completed" line of a controller action and takes it out
+    # of the Views share, as ActiveRecord does with db_runtime.
+    module ControllerRuntime
+      extend ActiveSupport::Concern
+
+      # @api private
+      module ClassMethods
+        def log_process_action(payload)
+          messages = super
+          runtime = payload[:tarantool_runtime]
+          messages << format('Tarantool: %.1fms', runtime.to_f) if runtime
+
+          messages
+        end
+      end
+
+      private
+
+      attr_internal :tarantool_runtime
+
+      def process_action(...)
+        LogSubscriber.reset_runtime
+
+        super
+      end
+
+      def cleanup_view_runtime
+        self.tarantool_runtime = tarantool_runtime.to_f + LogSubscriber.reset_runtime
+        runtime = super
+        during_render = LogSubscriber.reset_runtime
+        self.tarantool_runtime += during_render
+
+        runtime - during_render
+      end
+
+      def append_info_to_payload(payload)
+        super
+        payload[:tarantool_runtime] = tarantool_runtime.to_f + LogSubscriber.reset_runtime
+      end
+    end
+  end
+end

data/lib/tarantool/rails/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Rails
+    class Error < Tarantool::Error; end
+  end
+end

data/lib/tarantool/rails/log_subscriber.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Rails
+    # ActiveRecord-style lines for the client's events, and the time spent in requests per thread so the
+    # controller log can show a Tarantool share next to Views.
+    class LogSubscriber < ActiveSupport::LogSubscriber
+      COLORS = {
+        select: MAGENTA, insert: GREEN, replace: GREEN, upsert: GREEN, update: YELLOW, delete: RED,
+        begin: CYAN, commit: CYAN, rollback: CYAN
+      }.freeze
+      PRIMARY = [0, 'primary', :primary].freeze
+      RUNTIME = :tarantool_rails_runtime
+      private_constant :COLORS, :PRIMARY, :RUNTIME
+
+      class << self
+        def runtime
+          ActiveSupport::IsolatedExecutionState[RUNTIME] ||= 0.0
+        end
+
+        def runtime=(value)
+          ActiveSupport::IsolatedExecutionState[RUNTIME] = value
+        end
+
+        def reset_runtime
+          runtime.tap { self.runtime = 0.0 }
+        end
+      end
+
+      def request(event)
+        self.class.runtime += event.duration
+        return unless logger.debug?
+
+        payload = event.payload
+        name = color(request_name(payload), COLORS.fetch(payload[:request], WHITE), bold: true)
+
+        debug [name, format('(%.2fms)', event.duration), *request_details(payload)].join(' ')
+      end
+
+      def disconnect(event)
+        warn "Tarantool disconnected from #{event.payload[:address]}: #{event.payload[:reason]}"
+      end
+
+      def reconnect(event)
+        info "Tarantool reconnected to #{event.payload[:address]} after #{attempts(event.payload[:attempts])}"
+      end
+
+      def reconnect_failed(event)
+        error "Tarantool gave up reconnecting to #{event.payload[:address]}: #{event.payload[:exception].join(': ')}"
+      end
+
+      def fork(event)
+        info "Tarantool reopened #{event.payload[:address]} after fork"
+      end
+
+      def role_change(event)
+        info "Tarantool #{event.payload[:address]} is now #{event.payload[:read_only] ? 'read-only' : 'writable'}"
+      end
+
+      private
+
+      def request_name(payload)
+        parts = ['Tarantool', payload[:request], payload[:space], payload[:function]]
+        parts << "by #{payload[:index]}" if payload.key?(:index) && !PRIMARY.include?(payload[:index])
+        parts << "##{payload[:statement_id]}" if payload.key?(:statement_id)
+
+        parts.compact.join(' ')
+      end
+
+      def request_details(payload)
+        details = [payload[:sql], payload[:address]]
+        details << request_error(payload) if payload.key?(:exception)
+        details << 'schema_reloaded' if payload[:schema_reloaded]
+
+        details.compact
+      end
+
+      # The message may quote data (a duplicate key repeats the tuple); the line keeps the class and code.
+      def request_error(payload)
+        exception = payload[:exception_object]
+        klass = exception ? exception.class.name : payload[:exception].first
+        code = exception.respond_to?(:code) ? exception.code : nil
+
+        code ? "#{klass}(#{code})" : klass
+      end
+
+      def attempts(count)
+        count == 1 ? '1 attempt' : "#{count} attempts"
+      end
+    end
+  end
+end

data/lib/tarantool/rails/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Rails
+    # Wires configuration, the default model storage, logging and rake tasks into the application.
+    class Railtie < ::Rails::Railtie
+      config.tarantool = ActiveSupport::OrderedOptions.new
+      config.tarantool.log = true
+
+      # A missing config/tarantool.yml is not an error at boot: the install generator has to be able to run.
+      initializer 'tarantool.configuration' do |app|
+        Tarantool::Rails.schema_path = app.config.tarantool.schema_path || app.root.join('config/tarantool_schema.rb')
+        next unless app.root.join('config/tarantool.yml').exist?
+
+        section = app.config_for(:tarantool)
+        raise Error, "config/tarantool.yml has no #{::Rails.env} section" unless section
+
+        Tarantool::Rails.config = Configuration.from_hash(section)
+      end
+
+      initializer 'tarantool.model' do
+        Tarantool::Rails.use_default_storage!
+      end
+
+      initializer 'tarantool.log' do |app|
+        next unless app.config.tarantool.log
+
+        LogSubscriber.attach_to :tarantool
+        ActiveSupport.on_load(:action_controller) { include ControllerRuntime }
+      end
+
+      rake_tasks { load File.expand_path('tasks/schema.rake', __dir__) }
+    end
+  end
+end

data/lib/tarantool/rails/tasks/schema.rake

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+namespace :tarantool do
+  namespace :schema do
+    desc 'Print what tarantool:schema:apply would create; fail on drift'
+    task plan: :environment do
+      Tarantool::Rails.admin_client { |client| puts Tarantool::Rails.schema.plan(client) }
+    end
+
+    desc 'Create missing Tarantool spaces and indexes; fail on drift'
+    task apply: :environment do
+      Tarantool::Rails.admin_client { |client| puts Tarantool::Rails.schema.apply(client) }
+    end
+
+    desc 'Fail unless the live schema equals the declaration, for CI'
+    task check: :environment do
+      pending = Tarantool::Rails.admin_client { |client| Tarantool::Rails.schema.plan(client) }
+      next if pending.empty?
+
+      pending.each { |line| puts "pending: #{line}" }
+      exit 1
+    end
+  end
+end

data/lib/tarantool/rails/version.rb

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

data/lib/tarantool/rails.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require 'tarantool/client'
+require 'tarantool/model'
+require 'tarantool/schema'
+
+require_relative 'rails/version'
+require_relative 'rails/errors'
+require_relative 'rails/configuration'
+require_relative 'rails/log_subscriber'
+require_relative 'rails/controller_runtime'
+require_relative 'rails/railtie' if defined?(Rails::Railtie)
+
+module Tarantool
+  # Rails integration: configuration from config/tarantool.yml, one Pool per process, models on it, log lines,
+  # schema rake tasks and generators.
+  module Rails
+    LOCK = Monitor.new
+    private_constant :LOCK
+
+    class << self
+      attr_accessor :config, :schema_path
+      attr_writer :schema
+
+      def pool
+        LOCK.synchronize { @pool ||= build_pool }
+      end
+
+      def storage
+        LOCK.synchronize { @storage ||= build_storage }
+      end
+
+      def schema
+        LOCK.synchronize { @schema ||= load_schema }
+      end
+
+      def admin_client
+        uri = configured.admin_uri
+        raise Error, 'admin_uri is not set in config/tarantool.yml' unless uri
+
+        client = Tarantool::Client.new(uri)
+
+        yield client
+      ensure
+        client&.close
+      end
+
+      # Models without a storage of their own use the configured one, built on first use.
+      def use_default_storage!
+        @owns_default_storage = true
+        Model.default_storage = -> { storage }
+      end
+
+      def disconnect!
+        LOCK.synchronize do
+          @pool&.close
+          @pool = nil
+          @storage = nil
+          use_default_storage! if @owns_default_storage
+        end
+      end
+
+      private
+
+      def configured
+        config || raise(Error, 'Tarantool::Rails.config is not set: config/tarantool.yml is missing ' \
+                               '(rails g tarantool:install) or the Railtie is not loaded')
+      end
+
+      def build_pool
+        Tarantool::Client::Pool.new(configured.addresses, **configured.client_options,
+                                                          instrumenter: ActiveSupport::Notifications)
+      end
+
+      def build_storage
+        configured.storage == :box ? build_box_storage : build_crud_storage
+      end
+
+      def build_box_storage
+        Model::Storage::Box.new(pool, read: configured.read, write: configured.write)
+      end
+
+      def build_crud_storage
+        require 'tarantool/crud'
+        options = configured.crud
+        crud = Tarantool::Crud::Client.new(pool, **options.slice(:read, :write, :timeout_margin))
+
+        Model::Storage::Crud.new(crud, primary_index: options[:primary_index])
+      rescue LoadError
+        raise Error, 'storage: crud needs the tarantool-crud gem; add it to the Gemfile'
+      end
+
+      def load_schema
+        path = schema_path.to_s
+        load(path)
+
+        @schema || raise(Error, "#{path} must assign Tarantool::Rails.schema")
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: tarantool-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Starlexxx
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  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.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: tarantool-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: tarantool-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: config/tarantool.yml per environment, one connection pool per process,
+  models on it without an initializer, ActiveRecord-style log lines, schema rake tasks
+  and generators.
+email:
+- apavlovskiy088@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/tarantool/install/install_generator.rb
+- lib/generators/tarantool/install/templates/tarantool.yml
+- lib/generators/tarantool/install/templates/tarantool_schema.rb
+- lib/generators/tarantool/model/model_generator.rb
+- lib/generators/tarantool/model/templates/model.rb.tt
+- lib/tarantool/rails.rb
+- lib/tarantool/rails/configuration.rb
+- lib/tarantool/rails/controller_runtime.rb
+- lib/tarantool/rails/errors.rb
+- lib/tarantool/rails/log_subscriber.rb
+- lib/tarantool/rails/railtie.rb
+- lib/tarantool/rails/tasks/schema.rake
+- lib/tarantool/rails/version.rb
+homepage: https://github.com/Starlexxx/tarantool-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Starlexxx/tarantool-ruby/tree/master/tarantool-rails
+  changelog_uri: https://github.com/Starlexxx/tarantool-ruby/blob/master/tarantool-rails/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: Rails integration for tarantool-client, tarantool-model and tarantool-schema
+test_files: []