Версия:

Вложенный модуль box.schema

Вложенный модуль box.schema

Общие сведения

Вложенный модуль box.schema содержит функции для определения данных для спейсов, пользователей, ролей, кортежей и последовательностей.

Индекс

Ниже приведен перечень всех функций модуля box.schema.

Имя Использование
box.schema.space.create() Создание спейса
box.schema.user.create() Создание пользователя
box.schema.user.drop() Удаление пользователя
box.schema.user.exists() Проверка существования пользователя
box.schema.user.grant() Выдача прав пользователю или роли
box.schema.user.revoke() Отмена прав пользователя или роли
box.schema.user.password() Получение хеша пароля пользователя
box.schema.user.passwd() Ассоциация пароля с пользователем
box.schema.user.info() Получение описания прав пользователя
box.schema.role.create() Создание роли
box.schema.role.drop() Удаление роли
box.schema.role.exists() Проверка наличия роли
box.schema.role.grant() Выдача прав роли
box.schema.role.revoke() Отмена прав роли
box.schema.role.info() Получение описания прав роли
box.schema.func.create() Создание кортежа с функцией
box.schema.func.drop() Удаление кортежа с функцией
box.schema.func.exists() Проверка наличия кортежа с функцией
box.schema.sequence.create() Создание нового генератора последовательностей
sequence_object:next() Генерация и возврат следующего значения
sequence_object:alter() Изменение параметров последовательности
sequence_object:reset() Сброс состояния последовательности
sequence_object:set() Установка нового значения
sequence_object:drop() Удаление последовательности
space_object:create_index() Создание индекса
box.schema.space.create(space-name[, {options}])

Создание спейса.

Параметры:
  • space-name (string) – name of space, which should conform to the rules for object names
  • options (table) – см. таблицу «Параметры для box.schema.space.create» ниже
возвращается:

объект спейса

тип возвращаемого значения:
 

пользовательские данные

Параметры для box.schema.space.create

Имя Эффект Type Значение по умолчанию
engine (движок) „memtx“ или „vinyl“ string (строка) „memtx“
field_count (количество полей) заданное количество полей: например, если field_count=5, нельзя вставить кортеж с количеством полей, большим или меньшим, чем 5 число 0, то есть не задано
format (формат) имена и типы полей: см. наглядные примеры операторов в описании space_object:format() и в box.space._space. Необязательный параметр, обычно значение не указывается. таблица (пустое)
id уникальный идентификатор: пользователи могут ссылаться на спейсы посредством идентификатора вместо имени число идентификатор последнего спейса +1
if_not_exists (если отсутствует) спейс создается, только если спейса с таким же именем нет в базе данных, в противном случае эффект отсутствует, но ошибка не выдается boolean (логический) false (ложь)
is_local space contents are replication-local: changes are stored in the write-ahead log of the local node but there is no replication. boolean (логический) false (ложь)
temporary (временный) содержимое спейса хранится временно: изменения не хранятся в журнале упреждающей записи, и не проводится репликация. Примечание по движку базы данных: vinyl не поддерживает временные спейсы. boolean (логический) false (ложь)
user (пользователь) имя пользователя, который считается владельцем спейса, для целей авторизации string (строка) имя текущего пользователя

Существуют три варианта синтаксиса для ссылок на объекты спейса, например, box.schema.space.drop(id-спейса) удалит спейс. Однако общий подход заключается в использовании функций, прикрепленных к объектам спейса, например space_object:drop().

Пример

tarantool> s = box.schema.space.create('space55')
 ---
 ...
 tarantool> s = box.schema.space.create('space55', {
          >   id = 555,
          >   temporary = false
          > })
 ---
 - error: Space 'space55' already exists
 ...
 tarantool> s = box.schema.space.create('space55', {
          >   if_not_exists = true
          > })
 ---
 ...

Следующим шагом после создания спейса будет создание индекса для него, после чего можно будет выполнять вставку, выборку и другие функции box.space.

box.schema.user.create(user-name[, {options}])

Создание пользователя. Чтобы получить информацию о том, как происходит управление данными пользователя в Tarantool’е, см. раздел Пользователи и справочник по спейсу _user.

Возможные параметры:

  • if_not_exists (если отсутствует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если пользователь уже существует,
  • password (пароль) – строка; указать password = password неплохо, поскольку в URI (унифицированный идентификатор ресурса) обычно нельзя включать имя пользователя без пароля.

Примечание

Максимальное количество пользователей – 32.

Параметры:
возвращается:

nil

Примеры:

box.schema.user.create('Lena')
    box.schema.user.create('Lena', {password = 'X'})
    box.schema.user.create('Lena', {if_not_exists = false})
box.schema.user.drop(user-name[, {options}])

Удаление пользователя. Чтобы получить информацию о том, как происходит управление данными пользователя в Tarantool’е, см. раздел Пользователи и справочник по спейсу _user.

Параметры:
  • user-name (string) – имя пользователя
  • options (table) – if_exists (если существует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если такой пользователь не существует,

Примеры:

box.schema.user.drop('Lena')
    box.schema.user.drop('Lena',{if_exists=false})
box.schema.user.exists(user-name)

Возврат true (правда), если пользователь существует; возврат false (ложь), если пользователь отсутствует. Чтобы получить информацию о том, как происходит управление данными пользователя в Tarantool’е, см. раздел Пользователи и справочник по спейсу _user.

Параметры:
  • user-name (string) – имя пользователя
тип возвращаемого значения:
 

логическое значение bool

Пример:

box.schema.user.exists('Lena')
box.schema.user.grant(user-name, privileges, object-type, object-name[, {options}])
box.schema.user.grant(user-name, privileges, 'universe'[, nil, {options}])
box.schema.user.grant(user-name, role-name[, nil, nil, {options}])

Выдача прав пользователю или другой роли.

Параметры:
  • user-name (string) – имя пользователя.
  • privileges (string) – „read“ (чтение) или „write“ (запись), или „execute“ (выполнение), или „create“ (создание), или „alter“ (изменение), или „drop“ (удаление) или их сочетание.
  • object-type (string) – „space“ (спейс) или „function“ (функция), или „sequence“ (последовательность).
  • object-name (string) – имя объекта, на который выдаются права.
  • role-name (string) – имя роли, которая назначается пользователю.
  • options (table) – grantor, if_not_exists.

Если есть 'function','имя-объекта', то должен существовать кортеж в _func с таким именем объекта.

Вариант: вместо object-type, object-name введите „universe“, что означает „все типы объектов и все объекты“. В таком случае имя объекта опускается.

Вариант: вместо privilege, object-type, object-name введите role-name (имя роли) (см. раздел Роли).

Возможные параметры:

  • grantor = grantor_name_or_id – строка или номер для заданного пользователя, выдающего права,
  • if_not_exists (если отсутствует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если у пользователя уже есть права.

Пример:

box.schema.user.grant('Lena', 'read', 'space', 'tester')
    box.schema.user.grant('Lena', 'execute', 'function', 'f')
    box.schema.user.grant('Lena', 'read,write', 'universe')
    box.schema.user.grant('Lena', 'Accountant')
    box.schema.user.grant('Lena', 'read,write,execute', 'universe')
    box.schema.user.grant('X', 'read', 'universe', nil, {if_not_exists=true}))
box.schema.user.revoke(user-name, privilege, object-type, object-name)
box.schema.user.revoke(user-name, role-name)

Отмена прав пользователя или другой роли.

Параметры:
  • user-name (string) – имя пользователя.
  • privilege (string) – „read“ (чтение) или „write“ (запись), или „execute“ (выполнение), или „create“ (создание), или „alter“ (изменение), или „drop“ (удаление) или их сочетание.
  • object-type (string) – „space“ (спейс) или „function“ (функция), или „sequence“ (последовательность).
  • object-name (string) – имя функции, спейса или последовательности.

Должен существовать пользователь, должен существовать объект, но ошибка не выпадет, если у пользователя нет прав.

Вариант: вместо object-type, object-name введите „universe“, что означает „все типы объектов и все объекты“.

Вариант: вместо privilege, object-type, object-name введите role-name (имя роли) (см. раздел Роли).

Пример:

box.schema.user.revoke('Lena', 'read', 'space', 'tester')
    box.schema.user.revoke('Lena', 'execute', 'function', 'f')
    box.schema.user.revoke('Lena', 'read,write', 'universe')
    box.schema.user.revoke('Lena', 'Accountant')
box.schema.user.password(password)

Возврат хеша пароля пользователя. Чтобы получить информацию о том, как происходит управление паролями в Tarantool’е, см. раздел Пароли и справочник по спейсу _user.

Примечание

  • Если у пользователя, который не является пользователем „guest“ нет пароля, невозможно подключиться к Tarantool’у через этого пользователя. Пользователь считается только “внутренним”, его нельзя использовать для удаленного подключения. Такие пользователи могут работать, если они определили какие-либо процедуры с помощью SETUID, на которые есть доступ у пользователей с внешним подключением. Таким образом, внешние пользователи могут не создавать/удалять объекты, а только вызывать процедуры.
  • Для пользователя „guest“ невозможно установить пароль: это бы привело к путанице, поскольку „guest“ является пользователем по умолчанию для любого установленного подключения по бинарному порту, а Tarantool не требует пароль при установке бинарного подключения. Тем не менее, можно сменить текущего пользователя на пользователя ‘guest’, предоставив AUTH-пакет (пакет авторизации) без пароля или с пустым паролем. Данная функция полезна для пулов соединений, которые хотят повторно использовать соединение для другого пользователя без повторного подключения.
Параметры:
  • password (string) – пароль для хеширования
тип возвращаемого значения:
 

string (строка)

Пример:

box.schema.user.password('ЛЕНА')
box.schema.user.passwd([user-name, ]password)

Ассоциация пароля с авторизованным пользователем или с указанным именем пользователя. Такой пользователь должен существовать и не быть пользователем „guest“.

Если пользователь хочет поменять свой пароль, ему следует использовать синтаксис box.schema.user.passwd(password).

Если администратор хочет поменять пароль других пользователей, ему следует использовать синтаксис box.schema.user.passwd(user-name, password).

Параметры:
  • user-name (string) – имя пользователя
  • password (string) – пароль

Пример:

box.schema.user.passwd('ЛЕНА')
    box.schema.user.passwd('Lena', 'ЛЕНА')
box.schema.user.info([user-name])

Возврат описания прав пользователя. Чтобы получить информацию о том, как происходит управление данными пользователя в Tarantool’е, см. раздел Пользователи и справочник по спейсу _user.

Параметры:
  • user-name (string) – имя пользователя. Необязательный параметр; если не указать, информация будет для авторизованного пользователя.

Пример:

box.schema.user.info()
    box.schema.user.info('Lena')
box.schema.role.create(role-name[, {options}])

Создание роли. Чтобы получить информацию о том, как происходит управление данными о ролях в Tarantool’е, см. раздел Роли.

Параметры:
  • role-name (string) – name of role, which should conform to the rules for object names
  • options (table) – if_not_exists (если отсутствует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если роль уже существует,
возвращается:

nil

Пример:

box.schema.role.create('Accountant')
    box.schema.role.create('Accountant', {if_not_exists = false})
box.schema.role.drop(role-name[, {options}])

Удаление роли. Чтобы получить информацию о том, как происходит управление данными о ролях в Tarantool’е, см. раздел Роли.

Параметры:
  • role-name (string) – имя роли
  • options (table) – if_exists (если существует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если такая роль не существует,

Пример:

box.schema.role.drop('Accountant')
box.schema.role.exists(role-name)

Возврат true (правда), если роль существует; возврат false (ложь), если роль отсутствует.

Параметры:
  • role-name (string) – имя роли
тип возвращаемого значения:
 

логическое значение bool

Пример:

box.schema.role.exists('Accountant')
box.schema.role.grant(role-name, privilege, object-type, object-name[, option])
box.schema.role.grant(role-name, privilege, 'universe'[, nil, option])
box.schema.role.grant(role-name, role-name[, nil, nil, option])

Выдача прав роли.

Параметры:
  • role-name (string) – имя роли.
  • privilege (string) – „read“ (чтение) или „write“ (запись), или „execute“ (выполнение), или „create“ (создание), или „alter“ (изменение), или „drop“ (удаление) или их сочетание.
  • object-type (string) – „space“ (спейс) или „function“ (функция), или „sequence“ (последовательность).
  • object-name (string) – имя функции, спейса или последовательности.
  • option (table) – if_not_exists (если отсутствует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если у роли уже есть права.

Должна существовать роль, должен существовать объект.

Вариант: вместо object-type, object-name введите „universe“, что означает „все типы объектов и все объекты“.

Вариант: вместо privilege, object-type, object-name введите role-name, чтобы назначить роль для роли.

Пример:

box.schema.role.grant('Accountant', 'read', 'space', 'tester')
    box.schema.role.grant('Accountant', 'execute', 'function', 'f')
    box.schema.role.grant('Accountant', 'read,write', 'universe')
    box.schema.role.grant('public', 'Accountant')
    box.schema.role.grant('role1', 'role2', nil, nil, {if_not_exists=false})
box.schema.role.revoke(role-name, privilege, object-type, object-name)

Отмена прав роли.

Параметры:
  • role-name (string) – имя роли.
  • privilege (string) – „read“ (чтение) или „write“ (запись), или „execute“ (выполнение), или „create“ (создание), или „alter“ (изменение), или „drop“ (удаление) или их сочетание.
  • object-type (string) – „space“ (спейс) или „function“ (функция), или „sequence“ (последовательность).
  • object-name (string) – имя функции, спейса или последовательности.

Должна существовать роль, должен существовать объект, но ошибка не выпадет, если у роли нет прав.

Вариант: вместо object-type, object-name введите „universe“, что означает „все типы объектов и все объекты“.

Вариант: вместо privilege, object-type, object-name введите ``role-name`.

Пример:

box.schema.role.revoke('Accountant', 'read', 'space', 'tester')
    box.schema.role.revoke('Accountant', 'execute', 'function', 'f')
    box.schema.role.revoke('Accountant', 'read,write', 'universe')
    box.schema.role.revoke('public', 'Accountant')
box.schema.role.info(role-name)

Возврат описания прав роли.

Параметры:
  • role-name (string) – имя роли.

Пример:

box.schema.role.info('Accountant')
box.schema.func.create(func-name[, {options}])

Создание кортежа с функцией. Сама функция не создается – это делается с помощью Lua – но если необходимо выдать права функции, следует сначала выполнить box.schema.func.create. Чтобы получить информацию о том, как происходит управление данными функций в Tarantool’е, см. справочник по спейсу _func.

Возможные параметры:

  • if_not_exists (если отсутствует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если кортеж в _func уже существует.
  • setuid = true|false (по умолчанию, false) – значение true (правда) заставит Tarantool рассматривать пользователя, вызвавшего функцию, в качестве владельца функции с полными правами. Следует помнить, что SETUID работает только по бинарным портам. SETUID не сработает, если вызвать функцию через административную консоль или в Lua-скрипте.
  • language = „LUA“|“C“ (выбор языка из Lua и C; по умолчанию, ‘LUA’).
Параметры:
возвращается:

nil

Пример:

box.schema.func.create('calculate')
    box.schema.func.create('calculate', {if_not_exists = false})
    box.schema.func.create('calculate', {setuid = false})
    box.schema.func.create('calculate', {language = 'LUA'})
box.schema.func.drop(func-name[, {options}])

Удаление кортежа с функцией. Чтобы получить информацию о том, как происходит управление данными функций в Tarantool’е, см. справочник по спейсу _func.

Параметры:
  • func-name (string) – имя функции
  • options (table) – if_exists (если существует) = true|false (правда/ложь, по умолчанию ложь) - логическое значение boolean; true (правда) означает, что ошибка не выпадет, если кортеж в _func не существует.

Пример:

box.schema.func.drop('calculate')
box.schema.func.exists(func-name)

Возврат true (правда), если кортеж с функцией существует; возврат false (ложь), если кортеж с функцией отсутствует.

Параметры:
  • func-name (string) – имя функции
тип возвращаемого значения:
 

логическое значение bool

Пример:

box.schema.func.exists('calculate')
box.schema.func.reload([name])

Перезагрузка модуля на C (со всеми его функциями) без перезапуска сервера.

С точки зрения внутреннего устройства, Tarantool загружает новую копию модуля (библиотека общего пользования *.so) и запускает маршрутизацию всех новых запросов на новую версию. Предыдущая версия остается активной до тех пор, пока не завершатся все начатые вызовы. Все библиотеки общего пользования загружены с RTLD_LOCAL (см. «man 3 dlopen»), таким образом, множество копий могут работать одновременно без каких-либо проблем.

Примечание

Перезагрузка не сработает, если модуль был загружен из Lua-скрипта с ffi.load().

Параметры:
  • name (string) – имя модуля для перезагрузки

Пример:

-- перегрузить целиком всё содержимое модуля
box.schema.func.reload('module')

Последовательности

Вводная информация о последовательностях дается в разделе Последовательности главы «Модель данных». Здесь же приведена подробная информация о каждой функции и каждом параметре.

All functions related to sequences require appropriate privileges.

box.schema.sequence.create(name[, options])

Создание нового генератора последовательностей.

Параметры:
  • name (string) – имя последовательности
  • options (table) – см. краткий обзор в таблице «Параметры для box.schema.sequence.create()» (в разделе Последовательности главы «Модель данных»), а более подробную информацию ниже.
возвращается:

ссылка на новый объект последовательности.

Параметры:

  • start – НАЧАЛЬНОЕ значение. Тип = целое число, по умолчанию = 1.

  • min – МИНИМАЛЬНОЕ значение. Тип = целое число, по умолчанию = 1.

  • max –МАКСИМАЛЬНОЕ значение. Тип = целое число, по умолчанию = 9223372036854775807.

    Есть следующее правило: min <= start <= max. Например, нельзя указать {start=0}, поскольку указанное начальное значение (0) будет меньше, чем минимальное значение, используемое по умолчанию (1).

    Есть следующее правило: min <= следующее-значение <= max. Например, если сгенерированное значение будет 1000, но максимальное значение – 999, это будет считаться переполнением.

  • cycle – значение ЦИКЛА. Тип = bool (логический), по умолчанию = false (ложь).

    Если следующее значение в генераторе последовательности будет переполнением, это вызовет ошибку – не считая случаев, когда задан цикл (cycle == true).

    Если же cycle == true, отсчет начинается заново с МИНИМАЛЬНОГО значения или с МАКСИМАЛЬНОГО значения (не с НАЧАЛЬНОГО значения).

  • cache – значение КЭША. Тип = беззнаковое целое число, по умолчанию = 0.

    В данный момент Tarantool игнорирует это значение, оно зарезервировано для последующего использования.

  • step – значение УВЕЛИЧЕНИЯ. Тип = целое число, по умолчанию = 1.

    Это значение прибавляется к предыдущему.

sequence_object:next()

Генерация и возврат следующего значения.

Простой алгоритм для генерации:

  • В первый раз вернуть НАЧАЛЬНОЕ значение.
  • Если предыдущее значение плюс значение УВЕЛИЧЕНИЯ меньше, чем МИНИМАЛЬНОЕ значение, или больше, чем МАКСИМАЛЬНОЕ значение, будет переполнение, поэтому либо вернуть ошибку (если цикл не задан – cycle = false) или вернуть МАКСИМАЛЬНОЕ значение (если цикл задан – cycle = true – и step < 0), или вернуть МИНИМАЛЬНОЕ значение (если цикл задан – cycle = true – и step > 0).

Если ошибки нет, сохранить результат, который становится «предыдущим значением».

Например, предположим, что для последовательности „S“:

  • min == -6,
  • max == -1,
  • step == -3,
  • start = -2,
  • cycle = true,
  • предыдущее значение = -2.

Тогда box.sequence.S:next() вернет -5, потому что -2 + (-3) == -5.

Затем box.sequence.S:next() снова вернет -1, потому что -5 + (-3) < -6, что будет переполнением, которое вызовет цикл, а max == -1.

Для данной функции необходимы права на запись („write“) на последовательность.

Примечание

Данную функцию не следует использовать в транзакциях между движками (транзакции, в которых используется и движок memtx, и движок vinyl).

Чтобы увидеть предыдущее значение, не изменяя его, сделайте выборку из системного спейса _sequence_data.

sequence_object:alter(options)

Функцию alter() можно использовать для изменения любых параметров последовательности. Требования и ограничения в данном случае такие же, как для box.schema.sequence.create().

sequence_object:reset()

Возврат последовательности в оригинальное состояние. Смысл в том, что последующий вызов next() вернет начальное значение start. Для данной функции необходимы права на запись („write“) на последовательность.

sequence_object:set(new-previous-value)

Установите «предыдущее значение» на new-previous-value (новое предыдущее значение). Для данной функции необходимы права на запись („write“) на последовательность.

sequence_object:drop()

Удаление существующей последовательности.

Пример:

Ниже представлен пример, иллюстрирующий все параметры и операции для последовательностей:

s = box.schema.sequence.create(
                   'S2',
                   {start=100,
                   min=100,
                   max=200,
                   cache=100000,
                   cycle=false,
                   step=100
                   })
    s:alter({step=6})
    s:next()
    s:reset()
    s:set(150)
    s:drop()
space_object:create_index(... [sequence='...' option] ...)

Можно использовать опцию sequence=имя-последовательности (или sequence=id-последовательности, или sequence=true) при создании или изменении первичного индекса. Происходит ассоциация последовательности с индексом, так что следующий вызов insert() поместит следующее сгенерированное число в поле первичного ключа, если в противном случае поле было бы nil.

Например, если „Q“ – это последовательность, а „T“ – это новый спейс, то сработает:

tarantool> box.space.T:create_index('Q',{sequence='Q'})
    ---
    - unique: true
      parts:
      - type: unsigned
        is_nullable: false
        fieldno: 1
      sequence_id: 8
      id: 0
      space_id: 514
      name: Q
      type: TREE
    ...

(Обратите внимание, что теперь в индексе есть поле идентификатора последовательности sequence_id.)

И сработает:

tarantool> box.space.T:insert{nil,0}
    ---
    - [1, 0]
    ...

Примечание

Если вы используете отрицательные числа в параметрах последовательности, убедитесь, что тип ключа индекса будет целое число „integer“. В противном случае, тип ключа может быть либо „integer“, либо „unsigned“ (без знака).

Последовательность нельзя удалить, если она связана с индексом.