tarantool-schema 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f89be3eca7d9896490c3672d0273f45e8111b884ddabcdeb057f9b2f4838761
-  data.tar.gz: a8302d61a037f384ebf985a1105d7c4a7f08ff6f703b57b1dc33e72311a40678
+  metadata.gz: daa090a4546c7ecc8ed5c5e62f1a465b72e828c434e34076411069b6967a1914
+  data.tar.gz: 87f6b699e61c2e935f2dd508413910b89d333a1d302715bad446d9f5c5e90dbe
 SHA512:
-  metadata.gz: 4fb8b7cb681afef414ed5f7b4490f93b3b3ddd15dd4366076c7f0ccaba1f9a9eb0c05e2c7940dd4dec1f5e03514d783d5f4568cbf5411827f570e63678b17687
-  data.tar.gz: 8f7926a4f6eb1a9518534adb95cc2fdf5ed4b155bb508532502efdf442ebacc9d942cfafb5ca37418383e8091c68da3fdea37f19750a58c180c956d800137eb4
+  metadata.gz: c15dc87c94a1f8e24a537d53b63c84807e49436e34e4a24e1991184fed86d6f4c3abd0c40b6f6f5eb430762cc5954def2dea763f872e987fe459ac6635b0cc05
+  data.tar.gz: 85e8b8b6adfad1f6d9e61099991df5ee3001d0aa6c84e436a6c74faa5f1c38834536ff659ade1ef38d279fc1d2f89863f5557cc0ef6a005eb59b564b1ed30928

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0 (2026-10-18)
+
+- `grant user, privileges, on: space` declares the privileges a user or role must have on a space. `plan` and
+  `apply` grant what is missing after the space and its indexes, keep extra privileges, never revoke, and raise
+  `MismatchError` for a grantee that does not exist. `from_live` reads grants, `to_ruby` renders them,
+  `Definition#grants` lists them. The deploy user needs `read,write` on `_priv` and `read` on `_user` for this.
+
 ## 0.2.1 (2026-10-17)
 
 - Depends on `tarantool-client ~> 0.3`.

data/README.md

@@ -1,7 +1,8 @@
 # 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.
+Idempotent schema declaration for Tarantool 2.11+ and 3.x, meant for deploys. You declare spaces, indexes,
+primary key sequences and grants 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 alters
 only what you allow (appending nullable fields) and never drops anything: changing a field type or rebuilding an
 index is a migration and is out of scope. An existing database can be read back into the DSL with `from_live`.
@@ -35,6 +36,8 @@ module MyApp
       ]
 
     ensure_index :codes, :by_expiry, parts: [:expires_at], unique: false
+
+    grant :app, %i[read write], on: :codes
   end
 end
 ```
@@ -51,12 +54,14 @@ The block runs with the definition as `self`, then the definition is frozen: cal
 - `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.
+- `grant(user, privileges, on:)` declares the privileges a user or a role must have on a space, see Grants.
 
 ### 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;
+- a space declared twice, or declared after an `ensure_index` for it; a duplicate field or index name; the same
+  grantee twice on one space;
 - 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`;
@@ -75,7 +80,9 @@ Declaring any of these raises `ArgumentError`, so nobody assumes they were appli
 - 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`.
+- part: `collation`, `sort_order`, `exclude_null`;
+- grant: any privilege but `read write usage create drop alter trigger insert update delete` (`execute` on a
+  space exists on 2.11 only).
 
 Options that are set on a live space but that you did not declare are ignored when comparing.
 
@@ -108,7 +115,7 @@ 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.
+`num`) count as their canonical names. Grants are compared as described under Grants.
 
 ```
 schema mismatch:
@@ -141,6 +148,26 @@ Everything else stays a mismatch: a field that is not nullable (`field 4 flag: m
 added`), a live format longer than the declared one, a field differing inside the prefix. Nothing is ever
 dropped.
 
+## Grants
+
+Privileges on spaces belong in the schema: in Tarantool 3.x the YAML configuration grants them only to spaces
+that exist when the configuration is applied, so a space created by a later deploy is left without. A grant
+names a user or a role, the privileges and the space:
+
+```ruby
+grant :app, %i[read write], on: :codes
+grant :reporting, :read, on: :codes
+```
+
+`plan` and `apply` treat a grant like an index: after the space and its indexes they grant what is missing,
+only the privileges still lacking (`grant app write on codes` when `read` is already there). Privileges granted
+but not declared are kept, nothing is ever revoked. A grantee that does not exist is a mismatch (`grant app: no
+such user or role`), raised before anything is created; users and roles are not managed here. A grant on a space
+that is neither declared nor live is a mismatch too (`missing`). Privileges: `read write usage create drop alter
+trigger insert update delete`.
+
+The deploy user needs `read,write` on `_priv` and `read` on `_user` for grants, see Privileges.
+
 ## Bootstrapping from a live schema
 
 ```ruby
@@ -153,14 +180,16 @@ File.write('config/tarantool_schema.rb', definition.to_ruby)
 `from_live` reads the spaces with ids past the system range whose names do not start with `_` (vshard's
 `_bucket` and crud's `_ddl_*` stay out); `only:` names the spaces to read instead, with or without a leading
 underscore, and raises `ArgumentError` for a name that does not exist. Each space is read as `ensure_space`
-would declare it: engine, format, indexes in id order with their parts. A part that inherits its type and
+would declare it: engine, format, indexes in id order with their parts, then the grants on it (a privilege the
+DSL does not know, `execute` on 2.11, is left out). A part that inherits its type and
 nullability from the field is a bare field name; a JSON path part keeps its type. Index options the DSL does not
 know (`hint`, collations, `exclude_null`, vinyl tuning) are not read, as `plan` ignores them anyway. A
 functional index, or a part pointing past the format, raises `ArgumentError` naming the space and index: the
 DSL cannot express them.
 
 `to_ruby` renders a definition as source for a `Tarantool::Schema::Definition.new do ... end` block, defaults
-left out, one space per `ensure_space`, `ensure_index` entries after them; it evaluates back to the same `to_h`:
+left out, one space per `ensure_space`, `ensure_index` entries after them, then one `grant` per line; it
+evaluates back to the same `to_h` and `grants`:
 
 ```ruby
 Tarantool::Schema::Definition.new do
@@ -175,6 +204,8 @@ Tarantool::Schema::Definition.new do
                  { name: :by_code, parts: [:code] },
                  { name: :by_expiry, parts: [:expires_at], unique: false }
                ]
+
+  grant :app, %i[read write], on: :codes
 end
 ```
 
@@ -215,15 +246,17 @@ The deploy user needs these privileges (tested on 2.11 and 3.x):
 | 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 |
+| grants | `read,write` on space `_priv`, `read` on space `_user` | 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
+for _, name in ipairs({'_space', '_index', '_sequence', '_space_sequence', '_priv'}) do
   box.schema.user.grant('deployer', 'read,write', 'space', name)
 end
+box.schema.user.grant('deployer', 'read', 'space', '_user')
 ```
 
 On 2.11, only `admin` can grant privileges on `universe`; a `super` user cannot. Adding an index to a space
@@ -237,7 +270,8 @@ in, part types inherited, and `ensure_index` entries merged into their spaces. U
 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.
+elsewhere have no spec here and are not included. Grants are not in it either; `Definition#grants` lists them
+as `[{ user: :app, privileges: ['read', 'write'], space: :codes }]`.
 
 ```ruby
 MyApp::SCHEMA.to_h
@@ -277,8 +311,10 @@ INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3302 bundle exec rspec
 
 ## Public API
 
-`Tarantool::Schema::Definition` (`new`, `from_live`, `ensure_space`, `ensure_index`, `plan`, `apply`, `to_h`,
-`to_ruby`) and the error classes above.
+`Tarantool::Schema::Definition` (`new`, `from_live`, `ensure_space`, `ensure_index`, `grant`, `plan`, `apply`,
+`to_h`, `grants`, `to_ruby`) and the error classes above.
+
+RBS signatures for this API ship with the gem in `sig/`.
 
 Everything else, including anything tagged `@api private` in its source comment, is an implementation detail
 and may change in any release.

data/lib/tarantool/schema/comparison.rb

@@ -4,12 +4,12 @@ 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.
+    # from the live format. Grants are compared only when declared, against what GrantInspector read.
     # @api private
     class Comparison
-      attr_reader :name, :space, :mismatches, :missing_indexes, :format_additions
+      attr_reader :name, :space, :mismatches, :missing_indexes, :format_additions, :missing_grants
 
-      def initialize(name:, indexes:, live:, space: nil, alter: [])
+      def initialize(name:, indexes:, live:, space: nil, alter: [], grants: [], live_grants: nil)
         @name = name
         @space = space
         @live = live
@@ -18,6 +18,7 @@ module Tarantool
         @missing_indexes = []
         @format_additions = []
         live ? compare(indexes) : absent(indexes)
+        compare_grants(grants, live_grants)
       end
 
       def missing_space? = @live.nil? && !@space.nil?
@@ -37,6 +38,13 @@ module Tarantool
         indexes.each { |index| compare_index(index) }
       end
 
+      def compare_grants(grants, live_grants)
+        comparison = GrantComparison.new(grants, live_grants)
+        @mismatches.concat(comparison.mismatches)
+
+        @missing_grants = comparison.missing
+      end
+
       def compare_space
         @mismatches << "engine: declared #{@space.engine}, actual #{@live.engine}" if @space.engine != @live.engine
         format = FormatComparison.new(@space.format, @live.format, add_field: @alter.include?(:add_field))

data/lib/tarantool/schema/creation.rb

@@ -21,6 +21,12 @@ module Tarantool
         box.space[name]:format(format)
       LUA
 
+      GRANT_LUA = <<~LUA
+        local grantee, privileges, space = ...
+        local grant = box.schema.user.exists(grantee) and box.schema.user.grant or box.schema.role.grant
+        grant(grantee, privileges, 'space', space, {if_not_exists = true})
+      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)])
@@ -45,6 +51,15 @@ module Tarantool
 
         def to_s = "index #{space}.#{spec.name}"
       end
+
+      # Only the privileges still missing go out; an overlap with what is already granted is not an error.
+      Grant = Data.define(:spec) do
+        def apply(client)
+          client.eval(GRANT_LUA, [spec.user.to_s, spec.privileges.join(','), spec.space.to_s])
+        end
+
+        def to_s = spec.to_s
+      end
     end
   end
 end

data/lib/tarantool/schema/definition.rb

@@ -2,28 +2,39 @@
 
 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.
+    # Spaces, indexes and grants 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 = {}
+        @grants = {}
         instance_exec(&block) if block
         @spaces.transform_values! { |space| SpaceRules.check(space.resolve) }.freeze
         @external.each_value(&:freeze).freeze
+        @grants.each_value(&:freeze).freeze
         freeze
       end
 
-      # Every user space as the server has it, or only the named ones. A space the DSL cannot express raises.
+      # Every user space as the server has it, with the grants on it, or only the named ones. A space the DSL
+      # cannot express raises.
       def self.from_live(client, only: nil)
-        arguments = SpaceLister.call(client, only:).to_h do |name|
-          live = Inspector.call(client, name) || raise(ArgumentError, "space #{name}: not found")
+        arguments = SpaceLister.call(client, only:).to_h { |name| [name, live_arguments(client, name)] }
 
-          [name, LiveDefinition.arguments(name, live)]
+        new do
+          arguments.each do |name, (space, grants)|
+            ensure_space(name, **space)
+            grants.each { |user, privileges| grant(user, privileges, on: name) }
+          end
         end
+      end
+
+      def self.live_arguments(client, name)
+        live = Inspector.call(client, name) || raise(ArgumentError, "space #{name}: not found")
 
-        new { arguments.each { |name, space| ensure_space(name, **space) } }
+        [LiveDefinition.arguments(name, live), LiveDefinition.grants(GrantInspector.call(client, name, []))]
       end
+      private_class_method :live_arguments
 
       def ensure_space(name, format:, indexes:, engine: :memtx)
         raise ArgumentError, 'space without name' if name.nil?
@@ -49,9 +60,23 @@ module Tarantool
         nil
       end
 
+      # user may be a role too. Privileges already granted are kept, nothing is revoked.
+      def grant(user, privileges, on:)
+        spec = GrantSpec.build(user, privileges, on:)
+        grants = @grants[spec.space] ||= []
+        if grants.any? { |declared| declared.user == spec.user }
+          raise ArgumentError, "grant #{spec.user} on #{spec.space} is already declared"
+        end
+
+        grants << spec
+        nil
+      end
+
       def to_h = @spaces.transform_values(&:to_h)
 
-      def to_ruby = Source.render(to_h, @external.transform_values { |indexes| indexes.map(&:to_h) })
+      def grants = @grants.values.flatten.map(&:to_h)
+
+      def to_ruby = Source.render(to_h, @external.transform_values { |indexes| indexes.map(&:to_h) }, grants)
 
       # alter: lists the changes to live spaces that are allowed besides creating what is missing, see Alter.
       def plan(client, alter: []) = build_plan(client, Alter.check(alter)).verify.creations.map(&:to_s)
@@ -69,7 +94,7 @@ module Tarantool
 
       private
 
-      def build_plan(client, alter) = Plan.new(spaces: @spaces, external: @external, client:, alter:)
+      def build_plan(client, alter) = Plan.new(spaces: @spaces, external: @external, grants: @grants, client:, alter:)
 
       # A space declared elsewhere already has its primary key, so an index added here never gets a sequence.
       def add_external(space, index)

data/lib/tarantool/schema/grant_comparison.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Declared grants on one space against the live ones: what is still to grant, and grantees that do not
+    # exist. Privileges granted but not declared are ignored, nothing is ever revoked. For a space that does not
+    # exist yet the live masks are empty, so everything is to grant, and a missing grantee is still a mismatch.
+    # @api private
+    class GrantComparison
+      attr_reader :mismatches, :missing
+
+      def initialize(grants, live)
+        @mismatches = []
+        @missing = []
+        grants.each { |grant| compare(grant, live) }
+      end
+
+      private
+
+      def compare(grant, live)
+        return @mismatches << "grant #{grant.user}: no such user or role" if live.missing.include?(grant.user.to_s)
+
+        lacking = grant.missing(live.masks.fetch(grant.user.to_s, 0))
+
+        @missing << lacking if lacking
+      end
+    end
+  end
+end

data/lib/tarantool/schema/grant_inspector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Privilege masks on one space by grantee name, and which of the declared grantees do not exist. A grantee
+    # may be a user or a role. Reads _priv and _user, so the connection needs read on both.
+    # @api private
+    LiveGrants = Data.define(:masks, :missing)
+
+    # @api private
+    module GrantInspector
+      LUA = <<~LUA
+        local name, grantees = ...
+        local masks = setmetatable({}, {__serialize = 'map'})
+        local space = box.space[name]
+        if space ~= nil then
+          for _, row in box.space._priv.index.object:pairs({'space', space.id}) do
+            local grantee = box.space._user:get(row[2])
+            if grantee ~= nil then masks[grantee.name] = row[5] end
+          end
+        end
+        local missing = setmetatable({}, {__serialize = 'seq'})
+        for _, grantee in ipairs(grantees) do
+          if not (box.schema.user.exists(grantee) or box.schema.role.exists(grantee)) then
+            table.insert(missing, grantee)
+          end
+        end
+        return {masks = masks, missing = missing}
+      LUA
+
+      def self.call(client, space, grantees)
+        raw = client.eval(LUA, [space.to_s, grantees.map(&:to_s)]).first
+
+        LiveGrants.new(masks: raw.fetch('masks'), missing: raw.fetch('missing'))
+      end
+    end
+  end
+end

data/lib/tarantool/schema/grant_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Privileges one user or role must have on one space.
+    # @api private
+    GrantSpec = Data.define(:user, :privileges, :space) do
+      def self.build(user, privileges, on:)
+        raise ArgumentError, 'grant without user' if user.nil?
+        raise ArgumentError, "grant #{user} without space" if on.nil?
+
+        user = user.to_sym
+        space = on.to_sym
+
+        new(user:, privileges: Privileges.check(privileges, "grant #{user} on #{space}").freeze, space:)
+      end
+
+      # The grant that would complete a live mask, or nil when it already covers the declaration.
+      def missing(mask)
+        lacking = privileges - Privileges.names(mask)
+
+        lacking.empty? ? nil : with(privileges: lacking.freeze)
+      end
+
+      def to_s = "grant #{user} #{privileges.join(',')} on #{space}"
+    end
+  end
+end

data/lib/tarantool/schema/live_definition.rb

@@ -15,6 +15,11 @@ module Tarantool
           indexes: live.indexes.map { |index| index_arguments(name, index, fields) } }
       end
 
+      # Grants whose privileges the DSL does not know (execute on 2.11) are left out.
+      def grants(live)
+        live.masks.to_h { |user, mask| [user.to_sym, Privileges.names(mask)] }.reject { |_, names| names.empty? }
+      end
+
       def index_arguments(space, index, fields)
         raise ArgumentError, "space #{space}: index #{index.name} is functional, not supported" if index.func
 

data/lib/tarantool/schema/plan.rb

@@ -5,10 +5,12 @@ module Tarantool
     # 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:, alter: [])
+      def initialize(spaces:, external:, client:, alter: [], grants: {})
         @alter = alter
+        @grants = grants
         @comparisons = spaces.values.map { |space| compare(client, space.name, space.indexes, space) } +
-                       external.map { |name, indexes| compare(client, name, indexes) }
+                       external.map { |name, indexes| compare(client, name, indexes) } +
+                       granted_only(spaces, external).map { |name| compare(client, name, []) }
       end
 
       # complete: anything still missing is a mismatch too, used after apply has created it.
@@ -22,16 +24,20 @@ module Tarantool
         self
       end
 
-      # Per space: the space itself or its format change, then its indexes, so an index on a new field works.
+      # Per space: the space itself or its format change, then its indexes, so an index on a new field works,
+      # then its grants.
       def creations
         @comparisons.flat_map do |comparison|
           space_creation(comparison) +
-            comparison.missing_indexes.map { |index| Creation::Index.new(space: comparison.name, spec: index) }
+            comparison.missing_indexes.map { |index| Creation::Index.new(space: comparison.name, spec: index) } +
+            comparison.missing_grants.map { |grant| Creation::Grant.new(spec: grant) }
         end
       end
 
       private
 
+      def granted_only(spaces, external) = @grants.keys - spaces.keys - external.keys
+
       def space_creation(comparison)
         return [Creation::Space.new(spec: comparison.space)] if comparison.missing_space?
         return [] if comparison.format_additions.empty?
@@ -40,7 +46,11 @@ module Tarantool
       end
 
       def compare(client, name, indexes, space = nil)
-        Comparison.new(name:, indexes:, live: Inspector.call(client, name), space:, alter: @alter)
+        grants = @grants.fetch(name, [])
+        live_grants = GrantInspector.call(client, name, grants.map(&:user)) if grants.any?
+
+        Comparison.new(name:, indexes:, live: Inspector.call(client, name), space:, alter: @alter, grants:,
+                       live_grants:)
       end
 
       def still_missing(comparison)
@@ -48,7 +58,8 @@ module Tarantool
 
         format = comparison.format_additions.empty? ? [] : ['format: fields missing after apply']
 
-        format + comparison.missing_indexes.map { |index| "index #{index.name}: missing after apply" }
+        format + comparison.missing_indexes.map { |index| "index #{index.name}: missing after apply" } +
+          comparison.missing_grants.map { |grant| "grant #{grant.user}: missing after apply" }
       end
     end
   end

data/lib/tarantool/schema/privileges.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Schema
+    # Privileges a grant on a space may name, with their bits in _priv. execute is left out: 3.x rejects it on
+    # a space. Names are kept in bit order, the order box.schema.user.info prints them in.
+    # @api private
+    module Privileges
+      BITS = { 'read' => 1, 'write' => 2, 'usage' => 16, 'create' => 32, 'drop' => 64, 'alter' => 128,
+               'trigger' => 512, 'insert' => 1024, 'update' => 2048, 'delete' => 4096 }.freeze
+
+      module_function
+
+      def check(list, context)
+        names = Array(list).map(&:to_s)
+        raise ArgumentError, "#{context}: no privileges" if names.empty?
+
+        unknown = names.reject { |name| BITS.key?(name) }
+        if unknown.any?
+          raise ArgumentError, "#{context}: unknown privilege #{describe(unknown)}; allowed: #{BITS.keys.join(', ')}"
+        end
+
+        BITS.keys & names
+      end
+
+      def describe(names) = names.map { |name| name.to_sym.inspect }.join(', ')
+
+      def names(mask) = BITS.select { |_, bit| mask.anybits?(bit) }.keys
+    end
+  end
+end

data/lib/tarantool/schema/source.rb

@@ -5,21 +5,31 @@ module Tarantool
     # Ruby source of a definition, from its normalized Hash: a Definition.new block with one ensure_space per
     # space and one ensure_index per index on a space declared elsewhere. Defaults are left out and a part that
     # inherits everything from its field is a bare name, so the result reads like a hand-written declaration.
+    # Grants come last, one line each.
     # @api private
     module Source
       WIDTH = 120
       ARGUMENT_INDENT = ' ' * 15
       ENTRY_INDENT = ' ' * 17
+      NEEDS_ESCAPING = /['\\]/
 
       module_function
 
-      def render(spaces, external)
+      def render(spaces, external, grants = [])
         entries = spaces.map { |name, space| space(name, space) }
         entries += external.map { |name, indexes| indexes(name, indexes) }
+        entries << grants.map { |grant| grant(grant) }.join("\n") if grants.any?
 
         "Tarantool::Schema::Definition.new do\n#{entries.join("\n\n")}#{"\n" if entries.any?}end\n"
       end
 
+      def grant(grant)
+        privileges = grant[:privileges]
+        literal = privileges.one? ? symbol(privileges.first) : "%i[#{privileges.join(' ')}]"
+
+        "  grant #{symbol(grant[:user])}, #{literal}, on: #{symbol(grant[:space])}"
+      end
+
       def space(name, space)
         fields = space[:format].to_h { |field| [field[:name], field] }
         format = list('format', space[:format].map { |field| field(field) })
@@ -102,7 +112,7 @@ module Tarantool
 
       def symbol(name) = name.to_sym.inspect
 
-      def string(value) = value.match?(/['\\]/) ? value.inspect : "'#{value}'"
+      def string(value) = value.match?(NEEDS_ESCAPING) ? value.inspect : "'#{value}'"
     end
   end
 end

data/lib/tarantool/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Tarantool
   module Schema
-    VERSION = '0.2.1'
+    VERSION = '0.3.0'
   end
 end

data/lib/tarantool/schema.rb

@@ -13,6 +13,10 @@ require_relative 'schema/part_spec'
 require_relative 'schema/index_spec'
 require_relative 'schema/space_spec'
 require_relative 'schema/space_rules'
+require_relative 'schema/privileges'
+require_relative 'schema/grant_spec'
+require_relative 'schema/grant_inspector'
+require_relative 'schema/grant_comparison'
 require_relative 'schema/plan'
 require_relative 'schema/definition'
 require_relative 'schema/live_space'
@@ -26,7 +30,7 @@ require_relative 'schema/comparison'
 require_relative 'schema/creation'
 
 module Tarantool
-  # Idempotent declaration of spaces, indexes and primary key sequences, applied over an admin connection.
+  # Idempotent declaration of spaces, indexes, primary key sequences and grants, applied over an admin connection.
   module Schema
   end
 end

data/sig/tarantool/schema.rbs

@@ -0,0 +1,47 @@
+module Tarantool
+  # Idempotent declaration of spaces, indexes and primary key sequences.
+  module Schema
+    VERSION: String
+
+    type name = String | Symbol
+    # A format entry: { name:, type:, is_nullable: }; type omitted means any, is_nullable defaults to false.
+    type field = { name: name, ?type: name, ?is_nullable: bool }
+    # A part is a field name, or a Hash with the keys that differ from the field: type, is_nullable, path.
+    type part = name | { field: name, ?type: name, ?is_nullable: bool, ?path: String }
+    # An index declaration: { name:, parts:, unique: true, type: :tree, sequence: false }.
+    type index = { name: name, parts: Array[part], ?unique: bool, ?type: name, ?sequence: bool }
+    # Changes to live spaces that plan and apply may make: :add_field.
+    type alter = Array[Symbol | String]
+
+    # Tarantool::Client connected to the read-write instance, or anything else that evaluates Lua.
+    interface _Evaluator
+      def eval: (String expression, ?Array[untyped] arguments) -> Array[untyped]
+    end
+
+    class Definition
+      # The block runs with the definition as self; the definition is frozen afterwards.
+      def initialize: () ?{ () [self: Definition] -> void } -> void
+      # Every user space as the server has it (ids past the system range, names without a leading underscore),
+      # or only the named ones.
+      def self.from_live: (_Evaluator client, ?only: Array[name]?) -> Definition
+      def ensure_space: (name name, format: Array[field], indexes: Array[index], ?engine: name) -> nil
+      def ensure_index: (name space, name name, parts: Array[part], ?unique: bool, ?type: name,
+                         ?sequence: bool) -> nil
+      # The normalized declaration: names as Symbols, types as Strings, every default filled in.
+      def to_h: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def to_ruby: () -> String
+      def plan: (_Evaluator client, ?alter: alter) -> Array[String]
+      def apply: (_Evaluator client, ?alter: alter) -> Array[String]
+    end
+
+    class Error < Tarantool::Error
+    end
+
+    # The live schema differs from the declaration; mismatches are the lines, each prefixed with the space.
+    class MismatchError < Error
+      attr_reader mismatches: Array[String]
+
+      def initialize: (Hash[name, Array[String]] by_space) -> void
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tarantool-schema
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Starlexxx
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tarantool-client
@@ -44,6 +44,9 @@ files:
 - lib/tarantool/schema/errors.rb
 - lib/tarantool/schema/field_spec.rb
 - lib/tarantool/schema/format_comparison.rb
+- lib/tarantool/schema/grant_comparison.rb
+- lib/tarantool/schema/grant_inspector.rb
+- lib/tarantool/schema/grant_spec.rb
 - lib/tarantool/schema/index_comparison.rb
 - lib/tarantool/schema/index_spec.rb
 - lib/tarantool/schema/inspector.rb
@@ -53,12 +56,14 @@ files:
 - lib/tarantool/schema/options.rb
 - lib/tarantool/schema/part_spec.rb
 - lib/tarantool/schema/plan.rb
+- lib/tarantool/schema/privileges.rb
 - lib/tarantool/schema/source.rb
 - lib/tarantool/schema/space_lister.rb
 - lib/tarantool/schema/space_rules.rb
 - lib/tarantool/schema/space_spec.rb
 - lib/tarantool/schema/types.rb
 - lib/tarantool/schema/version.rb
+- sig/tarantool/schema.rbs
 homepage: https://github.com/Starlexxx/tarantool-ruby
 licenses:
 - MIT