tarantool-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 431a9d499bae2bc10348a4780b10ea5793e4debd8b021357f5f0a9edca753e00
+  data.tar.gz: 899bfb866f10c504ba4198899d2a42f850ae0b4a2fdb4c87a920f7c029097591
+SHA512:
+  metadata.gz: d07771270e5545f01d696e9600de60b09c861f87e134feaad9e566ad42ee679bed2a512a302b28387bd44a219ef32d518c0a87d245af30088e2da1cc5fb2360a
+  data.tar.gz: df474e074921d8678a7c55f976de5e661dd9eba828591a4247cc6a30c2ef95c1d75b245df42fa567fa4e846cd29085487194c6cf8b7af6d1f041213f3b2499de

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-10-17)
+
+First release.
+
+- `Tarantool::Schema::Definition`: `ensure_space` and `ensure_index` with `plan` and `apply` over an admin
+  `Tarantool::Client`. Creates missing spaces, indexes and primary key sequences; raises `MismatchError` with a
+  diff when the live schema differs, before creating anything. Never alters or drops.
+- `Definition#to_h`: the normalized declaration, with defaults filled in and part types inherited; tarantool-model's
+  `Testing::MemoryStorage.from_definition` accepts the definition.
+- Depends on `tarantool-client ~> 0.2.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,228 @@
+# tarantool-schema
+
+Idempotent schema declaration for Tarantool 2.11+ and 3.x, meant for deploys. You declare spaces, indexes and
+primary key sequences in Ruby; `apply` creates whatever is missing and checks everything that already exists.
+If the live schema differs from the declaration, it raises an error with a diff and creates nothing. It never
+alters or drops anything: changing a field type or rebuilding an index is a migration and is out of scope.
+
+## Installation
+
+Requirements: Ruby >= 3.2, Tarantool 2.11+ or 3.x.
+
+```ruby
+gem 'tarantool-schema'
+```
+
+```ruby
+require 'tarantool/schema'
+```
+
+## Declaring a schema
+
+```ruby
+module MyApp
+  SCHEMA = Tarantool::Schema::Definition.new do
+    ensure_space :codes, engine: :memtx,
+      format: [
+        { name: :id, type: :unsigned },
+        { name: :code, type: :string },
+        { name: :expires_at, type: :unsigned, is_nullable: true }
+      ],
+      indexes: [
+        { name: :primary, parts: [:id], sequence: true },
+        { name: :by_code, parts: [:code] }
+      ]
+
+    ensure_index :codes, :by_expiry, parts: [:expires_at], unique: false
+  end
+end
+```
+
+The block runs with the definition as `self`, then the definition is frozen: calling `ensure_*` later raises
+`FrozenError`, and loading the file again builds a new definition instead of growing the old one.
+
+- `ensure_space(name, format:, indexes:, engine: :memtx)`. `format` uses Tarantool's own keys: `name`, `type`
+  (omitted means `any`), `is_nullable` (default false). `indexes` are in declaration order; the first one is the
+  primary key.
+- Index keys: `name`, `parts`, `unique` (default true), `type` (`tree` by default, `hash`, `bitset`, `rtree`),
+  `sequence` (default false). A part is a field name or `{ field:, type:, is_nullable:, path: }`. A part's type
+  and nullability default to the field's; a part with a JSON `path` must declare its type.
+- `ensure_index(space, name, **options)` adds an index to a space declared in the same definition. For a space
+  owned by someone else it only adds the index: the space must already exist, and part types come from its
+  live format.
+
+### Validation
+
+These raise `ArgumentError` while the definition is built, before anything reaches the server:
+
+- a space declared twice, or declared after an `ensure_index` for it; a duplicate field or index name;
+- unknown keys anywhere, including the unsupported options listed below;
+- type aliases or unknown types. Only canonical names are accepted: `any unsigned string integer number double
+  boolean decimal uuid datetime interval varbinary scalar array map`. Use `string`, not `str`;
+- a part that refers to a field missing from the format;
+- vinyl spaces with anything but `tree` indexes;
+- unique `rtree`/`bitset` indexes, and `rtree`/`bitset`, non-unique or nullable primary keys;
+- `sequence: true` anywhere except a primary key with exactly one `unsigned` or `integer` part;
+- `tree` or `hash` index parts of type `any`, `interval`, `array` or `map`; a `hash` index that is not unique, or
+  that has a nullable part (`tree` allows nullable parts).
+
+### Not supported
+
+Declaring any of these raises `ArgumentError`, so nobody assumes they were applied:
+
+- space: `is_sync`, `temporary`, `is_local`, `field_count`, `id`, `user`, `constraint`, `foreign_key`;
+- field: `default`, `default_func`, `constraint`, `foreign_key`, `collation`;
+- index: `id`, `hint`, `func`, `dimension`, `distance`, vinyl tuning (`page_size`, `range_size`,
+  `run_count_per_level`, `run_size_ratio`, `bloom_fpr`);
+- part: `collation`, `sort_order`, `exclude_null`.
+
+Options that are set on a live space but that you did not declare are ignored when comparing.
+
+## Applying
+
+```ruby
+client = Tarantool::Client.new(ENV.fetch('TARANTOOL_ADMIN_URI'))
+
+# codes already exists from an earlier deploy; only by_expiry is new
+MyApp::SCHEMA.plan(client)  # => ["index codes.by_expiry"], writes nothing
+MyApp::SCHEMA.apply(client) # => ["index codes.by_expiry"]
+MyApp::SCHEMA.apply(client) # => []
+```
+
+Connect to the read-write instance. `apply`:
+
+1. reads every declared space (one `eval` per space, with the name passed as an argument);
+2. compares it with the declaration and collects the differences across all spaces;
+3. if there are any, raises `Tarantool::Schema::MismatchError` and creates nothing;
+4. creates the missing spaces and indexes in declaration order, with `if_not_exists` so two deploys racing each
+   other do not fail;
+5. reads everything again and raises `MismatchError` if something is still missing or differs, for example
+   when another deploy created the space differently in the meantime. Racing another deploy can also surface
+   as `Tarantool::ServerError` raised directly from `create_index`, before this re-verification runs.
+
+Each space and index is created with its own `eval`, so if one fails partway through (for example a privilege
+missing for a later index), the ones created before it stay; running `apply` again is idempotent and picks up
+where it left off.
+
+Comparison is strict about what you declared: engine; format (field count, and for each position the name,
+type and nullability); the primary index name; and for each declared index its type, uniqueness, sequence and
+parts. Indexes in the live space that you did not declare are ignored. Type aliases in a live format (`str`,
+`num`) count as their canonical names.
+
+```
+schema mismatch:
+  space codes:
+    engine: declared memtx, actual vinyl
+    field 2 code: type declared string, actual unsigned
+    index by_code: unique declared true, actual false
+```
+
+`MismatchError#mismatches` returns the same lines as an Array, each prefixed with `space <name>: `.
+
+## Rake
+
+```ruby
+namespace :tarantool do
+  namespace :schema do
+    def with_schema_client
+      require 'tarantool/schema'
+      require_relative 'config/tarantool_schema' # defines MyApp::SCHEMA
+      client = Tarantool::Client.new(ENV.fetch('TARANTOOL_ADMIN_URI'))
+      yield client
+    ensure
+      client&.close
+    end
+
+    desc 'Show what tarantool:schema:apply would create; fail on drift'
+    task :check do
+      with_schema_client { |client| puts MyApp::SCHEMA.plan(client) }
+    end
+
+    desc 'Create missing Tarantool spaces and indexes; fail on drift'
+    task :apply do
+      with_schema_client { |client| puts MyApp::SCHEMA.apply(client) }
+    end
+  end
+end
+```
+
+## Privileges
+
+The deploy user needs these privileges (tested on 2.11 and 3.x):
+
+| Privilege | 2.11 | 3.x |
+|---|---|---|
+| eval | `execute` on `universe` | `execute` on `lua_eval` |
+| create spaces | `create` on `space` | same |
+| primary key sequences | `create` on `sequence` | same |
+| system spaces | `read,write` on spaces `_space`, `_index`, `_sequence`, `_space_sequence` | same |
+
+```lua
+box.schema.user.create('deployer', {password = '...'})
+box.schema.user.grant('deployer', 'execute', 'lua_eval')      -- 2.11: 'execute', 'universe'
+box.schema.user.grant('deployer', 'create', 'space')
+box.schema.user.grant('deployer', 'create', 'sequence')
+for _, name in ipairs({'_space', '_index', '_sequence', '_space_sequence'}) do
+  box.schema.user.grant('deployer', 'read,write', 'space', name)
+end
+```
+
+On 2.11, only `admin` can grant privileges on `universe`; a `super` user cannot. Adding an index to a space
+owned by another user also needs `alter` on that space. The simplest setup is a dedicated deploy user that owns
+the application spaces, or one with the `super` role.
+
+## Sharing the declaration with tests
+
+`Definition#to_h` returns the normalized declaration: names as Symbols, types as Strings, every default filled
+in, part types inherited, and `ensure_index` entries merged into their spaces. Use it to build an in-memory
+test double or any other representation of the schema from the same declaration used to deploy it.
+
+Only spaces declared with `ensure_space` are in it: indexes added with `ensure_index` to a space declared
+elsewhere have no spec here and are not included.
+
+```ruby
+MyApp::SCHEMA.to_h
+# => { codes: { engine: 'memtx',
+#               format: [{ name: :id, type: 'unsigned', is_nullable: false }, ...],
+#               indexes: [{ name: :primary, type: 'tree', unique: true, sequence: true,
+#                           parts: [{ field: :id, type: 'unsigned', is_nullable: false, path: nil }] }, ...] } }
+```
+
+tarantool-model's in-memory test storage accepts the definition as is, so tests run against the same declaration
+as the deploy:
+
+```ruby
+require 'tarantool/model/testing'
+
+storage = Tarantool::Model::Testing::MemoryStorage.from_definition(MyApp::SCHEMA)
+```
+
+MemoryStorage raises `ArgumentError` for JSON `path` parts and `rtree` or `bitset` indexes.
+
+## Errors
+
+`Tarantool::Schema::MismatchError < Tarantool::Schema::Error < Tarantool::Error`. Server errors such as access
+denied or a read-only instance are raised unchanged as `Tarantool::ServerError`.
+
+## 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-schema
+bundle exec rspec                                     # unit
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3301 bundle exec rspec
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3302 bundle exec rspec
+```
+
+## Public API
+
+`Tarantool::Schema::Definition` 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, see [LICENSE](LICENSE).

data/lib/tarantool/schema/comparison.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Differences between one space as declared and as it is live. For a space declared elsewhere (only its
+    # indexes are declared here) there is no spec: engine and format are not compared and index parts inherit
+    # from the live format.
+    # @api private
+    class Comparison
+      attr_reader :name, :space, :mismatches, :missing_indexes
+
+      def initialize(name:, indexes:, live:, space: nil)
+        @name = name
+        @space = space
+        @live = live
+        @mismatches = []
+        @missing_indexes = []
+        live ? compare(indexes) : absent(indexes)
+      end
+
+      def missing_space? = @live.nil? && !@space.nil?
+
+      private
+
+      def absent(indexes)
+        if @space
+          @missing_indexes.concat(indexes)
+        else
+          @mismatches << 'missing'
+        end
+      end
+
+      def compare(indexes)
+        compare_space if @space
+        indexes.each { |index| compare_index(index) }
+      end
+
+      def compare_space
+        @mismatches << "engine: declared #{@space.engine}, actual #{@live.engine}" if @space.engine != @live.engine
+        @mismatches.concat(FormatComparison.new(@space.format, @live.format).mismatches)
+        compare_primary
+      end
+
+      def compare_primary
+        declared = @space.indexes.first.name
+        actual = @live.primary&.name
+        @mismatches << "primary index: declared #{declared}, actual #{actual}" if actual && actual != declared
+      end
+
+      def compare_index(index)
+        index = resolve(index) unless @space
+        return unless index
+
+        live = @live.index(index.name)
+        return @missing_indexes << index unless live
+
+        @mismatches.concat(IndexComparison.new(index, live).mismatches)
+      end
+
+      def resolve(index)
+        fields = @live.fields
+        unknown = index.unknown_fields(fields)
+        return index.resolve(fields) if unknown.empty?
+
+        @mismatches << "index #{index.name}: unknown field #{unknown.join(', ')}"
+
+        nil
+      end
+    end
+  end
+end

data/lib/tarantool/schema/creation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # What apply creates. Names and options are eval arguments, never part of the Lua source. if_not_exists keeps
+    # a deploy racing another one from failing; the re-verification after apply catches what the other one made.
+    # @api private
+    module Creation
+      SPACE_LUA = <<~LUA
+        local name, options = ...
+        box.schema.space.create(name, options)
+      LUA
+
+      INDEX_LUA = <<~LUA
+        local space, name, options = ...
+        box.space[space]:create_index(name, options)
+      LUA
+
+      Space = Data.define(:spec) do
+        def apply(client)
+          client.eval(SPACE_LUA, [spec.name.to_s, spec.to_lua.merge('if_not_exists' => true)])
+        end
+
+        def to_s = "space #{spec.name}"
+      end
+
+      Index = Data.define(:space, :spec) do
+        def apply(client)
+          client.eval(INDEX_LUA, [space.to_s, spec.name.to_s, spec.to_lua.merge('if_not_exists' => true)])
+        end
+
+        def to_s = "index #{space}.#{spec.name}"
+      end
+    end
+  end
+end

data/lib/tarantool/schema/definition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Spaces and indexes an application needs. Built once from a block and frozen, so a definition kept in a
+    # constant cannot grow when its file is loaded again. The block runs with the definition as self.
+    class Definition
+      def initialize(&block)
+        @spaces = {}
+        @external = {}
+        instance_exec(&block) if block
+        @spaces.transform_values! { |space| SpaceRules.check(space.resolve) }.freeze
+        @external.each_value(&:freeze).freeze
+        freeze
+      end
+
+      def ensure_space(name, format:, indexes:, engine: :memtx)
+        raise ArgumentError, 'space without name' if name.nil?
+
+        name = name.to_sym
+        raise ArgumentError, "space #{name} is already declared" if @spaces.key?(name)
+        raise ArgumentError, "space #{name}: declare it before its ensure_index" if @external.key?(name)
+
+        @spaces[name] = SpaceSpec.build(name, engine:, format:, indexes:)
+        nil
+      end
+
+      def ensure_index(space, name, **options)
+        raise ArgumentError, 'space without name' if space.nil?
+
+        space = space.to_sym
+        index = IndexSpec.build(name, options)
+        if @spaces.key?(space)
+          @spaces[space] = @spaces[space].add_index(index)
+        else
+          add_external(space, index)
+        end
+        nil
+      end
+
+      def to_h = @spaces.transform_values(&:to_h)
+
+      def plan(client) = build_plan(client).verify.creations.map(&:to_s)
+
+      # The second plan re-reads everything, so a space another deploy created differently in the meantime fails
+      # here instead of being reported as created.
+      def apply(client)
+        creations = build_plan(client).verify.creations
+        creations.each { |creation| creation.apply(client) }
+        build_plan(client).verify(complete: true)
+
+        creations.map(&:to_s)
+      end
+
+      private
+
+      def build_plan(client) = Plan.new(spaces: @spaces, external: @external, client:)
+
+      # A space declared elsewhere already has its primary key, so an index added here never gets a sequence.
+      def add_external(space, index)
+        if index.sequence
+          raise ArgumentError, "index #{index.name}: sequence is only allowed on the primary index, declare it " \
+                               'with ensure_space'
+        end
+        indexes = @external.fetch(space, [])
+        if indexes.any? { |i| i.name == index.name }
+          raise ArgumentError, "space #{space}: duplicate index #{index.name}"
+        end
+
+        @external[space] = [*indexes, index]
+      end
+    end
+  end
+end

data/lib/tarantool/schema/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Base class for errors raised by tarantool-schema.
+    class Error < Tarantool::Error; end
+
+    # The live schema differs from the declaration. apply raises it before creating anything, and again if what
+    # it created does not verify afterwards.
+    class MismatchError < Error
+      attr_reader :mismatches
+
+      def initialize(by_space)
+        @mismatches = by_space.flat_map { |space, lines| lines.map { |line| "space #{space}: #{line}" } }
+        super(describe(by_space))
+      end
+
+      private
+
+      def describe(by_space)
+        sections = by_space.map do |space, lines|
+          ["  space #{space}:", *lines.map { |line| "    #{line}" }].join("\n")
+        end
+
+        "schema mismatch:\n#{sections.join("\n")}"
+      end
+    end
+  end
+end

data/lib/tarantool/schema/field_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # One entry of a space format with Tarantool's defaults filled in. Also used for live format entries.
+    # @api private
+    FieldSpec = Data.define(:name, :type, :is_nullable) do
+      def self.build(raw)
+        raise ArgumentError, "format entry must be a Hash, got #{raw.inspect}" unless raw.is_a?(Hash)
+
+        context = "field #{raw[:name]}"
+        Options.check(raw, %i[name type is_nullable], context)
+        raise ArgumentError, 'format entry without name' if raw[:name].nil?
+
+        new(name: raw[:name].to_sym, type: Types.declared(raw.fetch(:type, 'any'), context),
+            is_nullable: Options.boolean(raw.fetch(:is_nullable, false), "#{context} is_nullable"))
+      end
+
+      def to_lua = { 'name' => name.to_s, 'type' => type, 'is_nullable' => is_nullable }
+    end
+  end
+end

data/lib/tarantool/schema/format_comparison.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Differences between a declared format and the live one, field by field in order.
+    # @api private
+    class FormatComparison
+      ATTRIBUTES = %i[name type is_nullable].freeze
+
+      def initialize(declared, live)
+        @declared = declared
+        @live = live
+      end
+
+      def mismatches
+        fields = @declared.zip(@live).each_with_index.flat_map do |(declared, live), index|
+          live ? field_mismatches(index + 1, declared, live) : []
+        end
+
+        count_mismatch + fields
+      end
+
+      private
+
+      def count_mismatch
+        return [] if @declared.size == @live.size
+
+        ["format: declared #{@declared.size} fields, actual #{@live.size}"]
+      end
+
+      def field_mismatches(number, declared, live)
+        ATTRIBUTES.filter_map do |attribute|
+          expected = declared.public_send(attribute)
+          actual = live.public_send(attribute)
+          "field #{number} #{declared.name}: #{attribute} declared #{expected}, actual #{actual}" if expected != actual
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/schema/index_comparison.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Differences between a declared index, its parts resolved, and the live index of the same name.
+    # @api private
+    class IndexComparison
+      ATTRIBUTES = %i[type unique sequence].freeze
+
+      def initialize(declared, live)
+        @declared = declared
+        @live = live
+      end
+
+      def mismatches
+        ATTRIBUTES.filter_map { |attribute| attribute_mismatch(attribute) } + parts_mismatch
+      end
+
+      private
+
+      def attribute_mismatch(attribute)
+        expected = @declared.public_send(attribute)
+        actual = @live.public_send(attribute)
+
+        "index #{@declared.name}: #{attribute} declared #{expected}, actual #{actual}" if expected != actual
+      end
+
+      def parts_mismatch
+        return [] if @declared.parts == @live.parts
+
+        ["index #{@declared.name}: parts declared #{describe(@declared.parts)}, actual #{describe(@live.parts)}"]
+      end
+
+      def describe(parts)
+        parts.map { |part| [part.field, part.path, part.type, ('nullable' if part.is_nullable)].compact.join(' ') }
+             .join(', ')
+      end
+    end
+  end
+end

data/lib/tarantool/schema/index_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # A declared index with create_index defaults filled in. Rules that depend on the space (primary key,
+    # engine, sequence) live in SpaceRules.
+    # @api private
+    IndexSpec = Data.define(:name, :type, :unique, :parts, :sequence) do
+      def self.build(name, raw)
+        raise ArgumentError, 'index without name' if name.nil?
+
+        context = "index #{name}"
+        Options.check(raw, %i[parts unique type sequence], context)
+        index = new(name: name.to_sym, type: type(raw, context), parts: parts(raw[:parts], context),
+                    unique: Options.boolean(raw.fetch(:unique, true), "#{context} unique"),
+                    sequence: Options.boolean(raw.fetch(:sequence, false), "#{context} sequence"))
+        check_unique(index, context)
+        KeyRules.check(index, nil)
+
+        index
+      end
+
+      def self.type(raw, context)
+        type = raw.fetch(:type, :tree).to_s
+        raise ArgumentError, "#{context}: unknown type #{type.inspect}" unless IndexSpec::TYPES.include?(type)
+
+        -type
+      end
+
+      def self.parts(raw, context)
+        raise ArgumentError, "#{context}: parts must be a non-empty Array" unless raw.is_a?(Array) && raw.any?
+
+        raw.map { |part| PartSpec.build(part) }.freeze
+      end
+
+      def self.check_unique(index, context)
+        return unless index.unique && IndexSpec::NON_UNIQUE.include?(index.type)
+
+        raise ArgumentError, "#{context}: #{index.type} index can not be unique, set unique: false"
+      end
+      private_class_method :type, :parts, :check_unique
+
+      def unknown_fields(fields) = parts.map(&:field).reject { |field| fields.key?(field) }
+
+      def resolve(fields) = with(parts: parts.map { |part| part.inherit(fields.fetch(part.field)) }.freeze)
+
+      def to_h = super.merge(parts: parts.map(&:to_h))
+
+      def to_lua = { 'type' => type, 'unique' => unique, 'parts' => parts.map(&:to_lua), 'sequence' => sequence }
+    end
+
+    IndexSpec::TYPES = %w[tree hash bitset rtree].freeze
+    IndexSpec::NON_UNIQUE = %w[bitset rtree].freeze
+  end
+end

data/lib/tarantool/schema/inspector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Reads one space from box.space. The name travels as an eval argument, never inside the Lua source.
+    # @api private
+    module Inspector
+      LUA = <<~LUA
+        local space = box.space[...]
+        if space == nil then return nil end
+        local indexes = {}
+        for id, index in pairs(space.index) do
+          if type(id) == 'number' then
+            local parts = {}
+            for _, part in ipairs(index.parts) do
+              table.insert(parts, {fieldno = part.fieldno, type = part.type, is_nullable = part.is_nullable,
+                                   path = part.path})
+            end
+            table.insert(indexes, {id = id, name = index.name, type = index.type, unique = index.unique,
+                                   parts = parts, sequence = index.sequence_id ~= nil})
+          end
+        end
+        return {engine = space.engine, format = space:format(), indexes = indexes}
+      LUA
+
+      def self.call(client, name)
+        raw = client.eval(LUA, [name.to_s]).first
+
+        raw && LiveSpace.from_eval(raw)
+      end
+    end
+  end
+end

data/lib/tarantool/schema/key_rules.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Key part rules Tarantool enforces on tree and hash indexes, verified live on 2.11 and 3.x. Checked before
+    # resolution, on what IndexSpec.build already knows, and again after, on a resolved SpaceSpec where parts
+    # have inherited their type and nullability from the format.
+    # @api private
+    module KeyRules
+      UNSUPPORTED_PART_TYPES = %w[any interval array map].freeze
+
+      module_function
+
+      def check(index, context)
+        return unless %w[tree hash].include?(index.type)
+
+        index.parts.each { |part| check_part_type(index, part, context) }
+        check_unique(index, context)
+        index.parts.each { |part| check_nullable(index, part, context) }
+      end
+
+      def check_part_type(index, part, context)
+        return unless part.type && UNSUPPORTED_PART_TYPES.include?(part.type)
+
+        raise error(index, context, "part #{part.field} of type #{part.type} can not be indexed by #{index.type}")
+      end
+
+      def check_unique(index, context)
+        return unless index.type == 'hash' && !index.unique
+
+        raise error(index, context, 'hash index must be unique')
+      end
+
+      def check_nullable(index, part, context)
+        return unless index.type == 'hash' && part.is_nullable
+
+        raise error(index, context, "hash index can not have nullable part #{part.field}")
+      end
+
+      def error(index, context, message)
+        ArgumentError.new("#{"#{context}: " if context}index #{index.name}: #{message}")
+      end
+    end
+  end
+end

data/lib/tarantool/schema/live_space.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # A space as the server has it, normalized to compare with a declaration: type aliases mapped, index types
+    # downcased, missing nullability read as false. An empty Lua table may arrive as a map, hence Array().
+    # @api private
+    LiveSpace = Data.define(:engine, :format, :indexes) do
+      def self.from_eval(raw)
+        format = Array(raw['format']).map do |field|
+          FieldSpec.new(name: field.fetch('name').to_sym, type: Types.live(field.fetch('type', 'any')),
+                        is_nullable: field.fetch('is_nullable', false))
+        end
+        indexes = Array(raw['indexes']).map { |index| LiveSpace::Index.from_eval(index, format) }
+
+        new(engine: raw.fetch('engine'), format:, indexes: indexes.sort_by(&:id))
+      end
+
+      def index(name) = indexes.find { |index| index.name == name }
+
+      def primary = indexes.find { |index| index.id.zero? }
+
+      def fields = format.to_h { |field| [field.name, field] }
+    end
+
+    LiveSpace::Index = Data.define(:id, :name, :type, :unique, :parts, :sequence) do
+      def self.from_eval(raw, format)
+        new(id: raw.fetch('id'), name: raw.fetch('name').to_sym, type: raw.fetch('type').downcase,
+            unique: raw.fetch('unique'), sequence: raw.fetch('sequence'),
+            parts: Array(raw['parts']).map { |part| part_from_eval(part, format) })
+      end
+
+      # fieldno is 1-based; a part beyond the format has no field name.
+      def self.part_from_eval(raw, format)
+        fieldno = raw.fetch('fieldno')
+
+        PartSpec.new(field: format[fieldno - 1]&.name || :"##{fieldno}", type: Types.live(raw.fetch('type')),
+                     is_nullable: raw.fetch('is_nullable', false), path: raw['path'])
+      end
+      private_class_method :part_from_eval
+    end
+  end
+end

data/lib/tarantool/schema/options.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Declaration keys are checked against a closed list, so an unsupported Tarantool option such as is_sync
+    # fails loudly instead of looking applied.
+    # @api private
+    module Options
+      module_function
+
+      def check(given, allowed, context)
+        unknown = given.keys - allowed
+        return if unknown.empty?
+
+        raise ArgumentError, "#{context}: unsupported #{unknown.map(&:inspect).join(', ')}"
+      end
+
+      def boolean(value, context)
+        return value if [true, false].include?(value)
+
+        raise ArgumentError, "#{context}: expected true or false, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/tarantool/schema/part_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # One part of an index key. Type and nullability left out stay nil until #inherit copies them from the
+    # field, as Tarantool does (verified for JSON path parts too). A path points inside the field, so its type
+    # cannot come from the field and must be declared.
+    # @api private
+    PartSpec = Data.define(:field, :type, :is_nullable, :path) do
+      def self.build(raw)
+        raw = { field: raw } unless raw.is_a?(Hash)
+        context = "index part #{raw[:field]}"
+        Options.check(raw, %i[field type is_nullable path], context)
+        raise ArgumentError, "#{context}: a part with path needs a type" if raw[:path] && !raw[:type]
+        raise ArgumentError, 'index part without field' if raw[:field].nil?
+
+        new(**attributes(raw, context))
+      end
+
+      def self.attributes(raw, context)
+        { field: raw[:field].to_sym,
+          type: raw[:type] && Types.declared(raw[:type], context),
+          is_nullable: raw[:is_nullable].nil? ? nil : Options.boolean(raw[:is_nullable], "#{context} is_nullable"),
+          path: raw[:path] && -raw[:path].to_s }
+      end
+
+      private_class_method :attributes
+
+      def inherit(field)
+        with(type: type || field.type, is_nullable: is_nullable.nil? ? field.is_nullable : is_nullable)
+      end
+
+      def to_lua = { 'field' => field.to_s, 'type' => type, 'is_nullable' => is_nullable, 'path' => path }.compact
+    end
+  end
+end

data/lib/tarantool/schema/plan.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # The live state of everything a definition declares, compared with it, and what is left to create.
+    # @api private
+    class Plan
+      def initialize(spaces:, external:, client:)
+        @comparisons = spaces.values.map { |space| compare(client, space.name, space.indexes, space) } +
+                       external.map { |name, indexes| compare(client, name, indexes) }
+      end
+
+      # complete: anything still missing is a mismatch too, used after apply has created it.
+      def verify(complete: false)
+        by_space = @comparisons.to_h do |comparison|
+          [comparison.name, comparison.mismatches + (complete ? still_missing(comparison) : [])]
+        end
+        by_space.reject! { |_, lines| lines.empty? }
+        raise MismatchError, by_space if by_space.any?
+
+        self
+      end
+
+      def creations
+        @comparisons.flat_map do |comparison|
+          space = comparison.missing_space? ? [Creation::Space.new(spec: comparison.space)] : []
+
+          space + comparison.missing_indexes.map { |index| Creation::Index.new(space: comparison.name, spec: index) }
+        end
+      end
+
+      private
+
+      def compare(client, name, indexes, space = nil)
+        Comparison.new(name:, indexes:, live: Inspector.call(client, name), space:)
+      end
+
+      def still_missing(comparison)
+        return ['missing after apply'] if comparison.missing_space?
+
+        comparison.missing_indexes.map { |index| "index #{index.name}: missing after apply" }
+      end
+    end
+  end
+end

data/lib/tarantool/schema/space_rules.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Rules Tarantool enforces on a whole space, checked on a resolved SpaceSpec before anything reaches the
+    # server.
+    # @api private
+    class SpaceRules
+      SEQUENCE_TYPES = %w[unsigned integer].freeze
+
+      def self.check(space) = new(space).check
+
+      def initialize(space)
+        @space = space
+      end
+
+      def check
+        raise error('at least one index is required') if @space.indexes.empty?
+
+        check_primary(@space.indexes.first)
+        check_no_secondary_sequence
+        check_engine
+        @space.indexes.each { |index| KeyRules.check(index, "space #{@space.name}") }
+
+        @space
+      end
+
+      private
+
+      def check_no_secondary_sequence
+        extra = @space.indexes.drop(1).find(&:sequence)
+        return unless extra
+
+        raise error("index #{extra.name}: sequence is only allowed on the primary index")
+      end
+
+      def check_primary(index)
+        check_primary_type(index)
+        check_primary_unique(index)
+        check_primary_nullable(index)
+        check_sequence(index) if index.sequence
+      end
+
+      def check_primary_type(index)
+        return unless IndexSpec::NON_UNIQUE.include?(index.type)
+
+        raise error("primary index #{index.name} can not be #{index.type}")
+      end
+
+      def check_primary_unique(index)
+        raise error("primary index #{index.name} must be unique") unless index.unique
+      end
+
+      def check_primary_nullable(index)
+        nullable = index.parts.find(&:is_nullable)
+        raise error("primary index #{index.name}: part #{nullable.field} can not be nullable") if nullable
+      end
+
+      def check_sequence(index)
+        return if index.parts.size == 1 && SEQUENCE_TYPES.include?(index.parts.first.type)
+
+        raise error("index #{index.name}: sequence needs a single unsigned or integer part")
+      end
+
+      def check_engine
+        return if @space.engine == 'memtx'
+
+        other = @space.indexes.reject { |index| index.type == 'tree' }
+        raise error("vinyl supports only tree indexes, got #{other.map(&:name).join(', ')}") if other.any?
+      end
+
+      def error(message) = ArgumentError.new("space #{@space.name}: #{message}")
+    end
+  end
+end

data/lib/tarantool/schema/space_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # A declared space. Its index parts get the field types and nullability once #resolve runs.
+    # @api private
+    SpaceSpec = Data.define(:name, :engine, :format, :indexes) do
+      def self.build(name, engine:, format:, indexes:)
+        raise ArgumentError, 'space without name' if name.nil?
+
+        context = "space #{name}"
+        space = new(name: name.to_sym, engine: build_engine(engine, context), format: build_format(format, context),
+                    indexes: [].freeze)
+
+        build_indexes(space, indexes, context)
+      end
+
+      def self.build_engine(engine, context)
+        engine = engine.to_s
+        raise ArgumentError, "#{context}: unknown engine #{engine.inspect}" unless SpaceSpec::ENGINES.include?(engine)
+
+        -engine
+      end
+
+      def self.build_indexes(space, indexes, context)
+        raise ArgumentError, "#{context}: indexes must be an Array" unless indexes.is_a?(Array)
+
+        indexes.reduce(space) { |result, raw| result.add_index(IndexSpec.build(*index_arguments(raw, context))) }
+      end
+
+      def self.build_format(raw, context)
+        raise ArgumentError, "#{context}: format must be an Array" unless raw.is_a?(Array)
+
+        fields = raw.map { |field| FieldSpec.build(field) }
+        duplicates = fields.map(&:name).tally.select { |_, count| count > 1 }.keys
+        raise ArgumentError, "#{context}: duplicate field #{duplicates.join(', ')}" if duplicates.any?
+
+        fields.freeze
+      end
+
+      def self.index_arguments(raw, context)
+        raise ArgumentError, "#{context}: index must be a Hash, got #{raw.inspect}" unless raw.is_a?(Hash)
+
+        [raw.fetch(:name) { raise ArgumentError, "#{context}: index without name" }, raw.except(:name)]
+      end
+      private_class_method :build_engine, :build_indexes, :build_format, :index_arguments
+
+      def add_index(index)
+        raise ArgumentError, "space #{name}: duplicate index #{index.name}" if indexes.any? { |i| i.name == index.name }
+
+        with(indexes: [*indexes, index].freeze)
+      end
+
+      def resolve
+        fields = format.to_h { |field| [field.name, field] }
+        unknown = unknown_field_errors(fields)
+        raise ArgumentError, "space #{name}: #{unknown.join('; ')}" if unknown.any?
+
+        with(indexes: indexes.map { |index| index.resolve(fields) }.freeze)
+      end
+
+      def to_h = { engine:, format: format.map(&:to_h), indexes: indexes.map(&:to_h) }
+
+      def to_lua = { 'engine' => engine, 'format' => format.map(&:to_lua) }
+
+      private
+
+      def unknown_field_errors(fields)
+        indexes.flat_map do |index|
+          index.unknown_fields(fields).map { |field| "index #{index.name}: unknown field #{field}" }
+        end
+      end
+    end
+
+    SpaceSpec::ENGINES = %w[memtx vinyl].freeze
+  end
+end

data/lib/tarantool/schema/types.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Field type names. The server keeps a space format type verbatim (str stays str) but normalizes index part
+    # types (str becomes string), so declarations accept only canonical names and live format types are mapped
+    # onto them before comparing.
+    # @api private
+    module Types
+      CANONICAL = %w[
+        any unsigned string integer number double boolean decimal uuid datetime interval varbinary scalar array map
+      ].freeze
+      ALIASES = { 'str' => 'string', 'num' => 'number' }.freeze
+
+      module_function
+
+      def declared(type, context)
+        name = type.to_s
+        return -name if CANONICAL.include?(name)
+
+        hint = canonical(name)
+        raise ArgumentError, "#{context}: unknown type #{name.inspect}#{", use #{hint}" if hint}"
+      end
+
+      def live(type)
+        name = type.to_s
+
+        canonical(name) || name
+      end
+
+      def canonical(name)
+        lower = name.downcase
+
+        ALIASES.fetch(lower) { lower if CANONICAL.include?(lower) }
+      end
+    end
+  end
+end

data/lib/tarantool/schema/version.rb

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

data/lib/tarantool/schema.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'tarantool/client'
+
+require_relative 'schema/version'
+require_relative 'schema/errors'
+require_relative 'schema/options'
+require_relative 'schema/types'
+require_relative 'schema/key_rules'
+require_relative 'schema/field_spec'
+require_relative 'schema/part_spec'
+require_relative 'schema/index_spec'
+require_relative 'schema/space_spec'
+require_relative 'schema/space_rules'
+require_relative 'schema/plan'
+require_relative 'schema/definition'
+require_relative 'schema/live_space'
+require_relative 'schema/inspector'
+require_relative 'schema/format_comparison'
+require_relative 'schema/index_comparison'
+require_relative 'schema/comparison'
+require_relative 'schema/creation'
+
+module Tarantool
+  # Idempotent declaration of spaces, indexes and primary key sequences, applied over an admin connection.
+  module Schema
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: tarantool-schema
+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: tarantool-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: Declare Tarantool 2.11+ and 3.x spaces, indexes and primary key sequences
+  in Ruby; apply creates what is missing and fails with a readable diff when the live
+  schema differs.
+email:
+- apavlovskiy088@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/tarantool/schema.rb
+- lib/tarantool/schema/comparison.rb
+- lib/tarantool/schema/creation.rb
+- lib/tarantool/schema/definition.rb
+- lib/tarantool/schema/errors.rb
+- lib/tarantool/schema/field_spec.rb
+- lib/tarantool/schema/format_comparison.rb
+- lib/tarantool/schema/index_comparison.rb
+- lib/tarantool/schema/index_spec.rb
+- lib/tarantool/schema/inspector.rb
+- lib/tarantool/schema/key_rules.rb
+- lib/tarantool/schema/live_space.rb
+- lib/tarantool/schema/options.rb
+- lib/tarantool/schema/part_spec.rb
+- lib/tarantool/schema/plan.rb
+- lib/tarantool/schema/space_rules.rb
+- lib/tarantool/schema/space_spec.rb
+- lib/tarantool/schema/types.rb
+- lib/tarantool/schema/version.rb
+homepage: https://github.com/Starlexxx/tarantool-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Starlexxx/tarantool-ruby/tree/master/tarantool-schema
+  changelog_uri: https://github.com/Starlexxx/tarantool-ruby/blob/master/tarantool-schema/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: Idempotent Tarantool schema declaration for deploys
+test_files: []