Описание схемы данных

В Tarantool использование схемы данных опционально.

При создании спейса схему можно не задавать и тогда в кортежах могут лежать произвольные данные. Это правило не распространяется на поля, по которым построены индексы. У таких полей данные должны быть одного типа.

Схему можно задать при создании спейса. Читайте подробнее в описании функции box.schema.space.create(). Если вы создали спейс без схемы, ее можно добавить позже с помощью метода space_object:format().

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

Мы рекомендуем использовать подход со схемой, потому что он помогает избежать ошибок.

Схему в Tarantool можно задавать двумя разными способами.

Описание схемы в файле с кодом

Обычно файл с кодом называется init.lua и имеет следующее описание схемы:

box.cfg()

users = box.schema.create_space('users', { if_not_exists = true })
users:format({{ name = 'user_id', type = 'number'}, { name = 'fullname', type = 'string'}})

users:create_index('pk', { parts = { { field = 'user_id', type = 'number'}}})

Этот подход довольно простой. Когда вы запустите tarantool, этот код исполнится и создаст схему. Чтобы запустить файл, используйте следующую команду:

tarantool init.lua

Но это может показаться слишком сложным, если вы не собираетесь глубоко разбираться с языком Lua и его синтаксисом.

Пример возможной сложности: в фрагменте выше есть вызов функций с двоеточием: users:format. Он используется, чтобы передать переменную users в качестве первого аргумента функции format. Это аналог self в объектно-ориентированных языках.

Поэтому вам может быть удобно описать схему через YAML.

Описание через модуль DDL

Модуль DDL позволяет декларативно описывать схему данных в YAML формате.

Схема будет выглядеть примерно вот так:

spaces:
  users:
    engine: memtx
    is_local: false
    temporary: false
    format:
    - {name: user_id, type: uuid, is_nullable: false}
    - {name: fullname, type: string,  is_nullable: false}
    - {name: bucket_id, type: unsigned, is_nullable: false}
    indexes:
    - name: user_id
      unique: true
      parts: [{path: user_id, type: uuid, is_nullable: false}]
      type: HASH
    - name: bucket_id
      unique: false
      parts: [{path: bucket_id, type: unsigned, is_nullable: false}]
      type: TREE
    sharding_key: [user_id]
    sharding_func: test_module.sharding_func

Этот вариант проще для старта: его проще использовать и не нужно вникать в язык Lua.

DDL is a built-in Cartridge module. Cartridge is a cluster solution for Tarantool. In its WebUI, there is a separate tab called «Code». On this tab, in the schema.yml file, you can define the schema, check its correctness, and apply it to the whole cluster.

Если вы не используете Cartridge, то чтобы использовать модуль DDL, нужно вставить нижеприведенный код на Lua в файл, с которым вы запускаете Tarantool. Обычно это init.lua.

local yaml = require('yaml')
local ddl = require('ddl')

box.cfg{}

local fh = io.open('ddl.yml', 'r')
local schema = yaml.decode(fh:read('*all'))
fh:close()
local ok, err = ddl.check_schema(schema)
if not ok then
    print(err)
end
local ok, err = ddl.set_schema(schema)
if not ok then
    print(err)
end

Предупреждение

Менять схему в самом DDL после ее применения нельзя. Для миграций есть несколько подходов — они описаны в разделе Миграции.

Версия:

Описание схемы данных

Описание схемы в файле с кодом

Описание через модуль DDL