Справочник по настройке

Справочник по настройке

Базовые параметры

sharding

Поле, которое определяет логическую топологию сегментированного кластера Tarantool’а.

Тип: таблица
По умолчанию: false (ложь)
Динамический: да
weights

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

Тип: таблица
По умолчанию: false (ложь)
Динамический: да
shard_index

Название или id TREE-индекса по идентификатору сегмента. Спейсы без этого индекса не задействованы в шардированном кластере Tarantool’а и при необходимости могут быть использованы как обычные спейсы. Необходимо указать первую часть индекса, остальные части являются необязательными.

Тип: непустая строка или неотрицательное целое число
По умолчанию: «bucket_id» (идентификатор сегмента)
Динамический: нет
bucket_count

Общее число сегментов в кластере.

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

Пример:

Если предполагаемое количество узлов равно M, тогда набор данных должен быть разделен на 100M или даже 1000M сегментов, в зависимости от запланированного масштабирования. Это число, безусловно, больше потенциального числа узлов кластера в проектируемой системе.

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

Тип: число
По умолчанию: 3000
Динамический: нет
collect_bucket_garbage_interval

Интервал между действиями сборщика мусора в секундах.

Тип: число
По умолчанию: 0.5
Динамический: да
collect_lua_garbage

Если задано значение true (правда), периодически вызывается Lua-функция collectgarbage().

Тип: логический
По умолчанию: нет
Динамический: да
sync_timeout

Время ожидания синхронизации старого мастера с репликами перед сменой мастера. Используется при переключении мастера или при вызове функции sync() вручную.

Тип: число
По умолчанию: 1
Динамический: да
rebalancer_disbalance_threshold

Максимальный предел дисбаланса сегментов в процентах. Предел вычисляется для каждого набора реплик по следующей формуле:

|эталонное_число_сегментов - фактическое_число_сегментов| / эталонное_число_сегментов * 100
Тип: число
По умолчанию: 1
Динамический: да
rebalancer_max_receiving

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

Пример:

Предположим, rebalancer_max_receiving = 100, число сегментов в bucket_count = 1000. Есть 3 набора реплик с 333, 333 и 334 сегментами соответственно. При добавлении нового набора реплик эталонное_число_сегментов становится равным 250. Вместо того, чтобы сразу получить все 250 сегментов, новый набор реплик получит последовательно 100, 100 и 50 сегментов.

Тип: число
По умолчанию: 100
Динамический: да
rebalancer_max_sending

Степень параллельности для параллельной балансировки.

Используется только для хранилищ, для роутеров игнорируется.

Максимальное значение: 15.

Тип: число
По умолчанию: 1
Динамический: да
discovery_mode

Режим работы файбера обнаружения сегментов: on/off/once. Подробнее.

Тип: строка
По умолчанию: «on»
Динамический: да

Функции набора реплик

uuid

Уникальный идентификатор набора реплик.

Тип:
По умолчанию:
Динамическое:
weight

Вес набора реплик. Для получения подробной информации см. раздел Вес набора реплик.

Тип:
По умолчанию: 1
Динамическое:

Справочник по API

Общедоступные API роутера

vshard.router.bootstrap()

Инициализация кластера и распределение всех сегментов по наборам реплик.

Параметры:
  • timeout – количество секунд ожидания до признания попытки инициализации неуспешной. Пересоздайте кластер в случае блокировки инициализации по истечении времени ожидания.
  • if_not_bootstrapped – По умолчанию false, то есть «вызвать ошибку, если кластер уже был инициализирован». True значит «если кластер уже был инициализирован, то ничего не делать.»

Пример:

vshard.router.bootstrap({timeout = 4, if_not_bootstrapped = true})

Примечание

Чтобы определить, инициализирован ли кластер , vshard ищет по крайней мере один сегмент во всем кластере. Если кластер был инициализирован частично (например, из-за ошибки при первой инициализации),то он все равно будет считаться инициализированным при следующей попытке инициализации с флагом if_not_bootstrapped. Поэтому лучше избегать вызова ``bootstrap()``несколько раз.

vshard.router.cfg(cfg)

Настройка базы данных и начало шардинга указанного роутера. См. образец конфигурации выше.

Параметры:
  • cfg – конфигурационная таблица
vshard.router.new(name, cfg)

Создание нового экземпляра роутера. vshard поддерживает работу нескольких роутеров в отдельном экземпляре Tarantool’а. Каждый роутер может подключаться к любом кластеру vshard, несколько роутеров могут подключаться к одному кластеру.

Роутер, созданный с помощью vshard.router.new(), работает так же, как и статичный роутер, но перед его методами указывается двоеточие (vshard.router:имя_метода(...)), а перед методами статичного роутера – точка (vshard.router.имя_метода(...)).

Статичный роутер можно получить при помощи метода vshard.router.static(), а затем использовать его как роутер, созданный с помощью метода vshard.router.new().

Примечание

box.cfg используется всеми роутерами одного экземпляра.

Параметры:
  • name – имя экземпляра роутера, которое используется в качестве префикса в журналах роутера и должно быть уникальным в пределах экземпляра
  • cfg – конфигурационная таблица. Образец конфигурации описан выше.
Возвращается:

экземпляр роутера, если он создан; в противном случае, nil и ошибка

vshard.router.call(bucket_id, mode, function_name, {argument_list}, {options})

Вызов функции по имени функции (function-name) на шарде, где хранится сегмент с указанным идентификатором (bucket_id). Для получения подробной информации о работе функции см. раздел Обработка запросов.

Параметры:
  • bucket_id – идентификатор сегмента
  • mode – либо строка = „read“|“write“ (чтение|запись), либо ассоциативный массив с параметром mode =“read“|“write“ (чтение|запись) и/или prefer_replica=true|false (правда|ложь), и/или balance=true|false (правда|ложь).
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с указанным идентификатором сегмента bucket_id, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.

У параметра режима mode есть две доступные формы: строка или ассоциативный массив. Примеры строки: 'read' (чтение), 'write' (запись). Примеры ассоциативного массива: {mode='read'}, {mode='write'}, {mode='read', prefer_replica=true}, {mode='read', balance=true}, {mode='read', prefer_replica=true, balance=true}.

Если указать значение 'write' (запись), то целью будет мастер.

Если указать prefer_replica=true, то предпочитаемая цель – одна из реплик; если же доступной реплики нет, то целью будет мастер.

Удобно указать prefer_replica=true для ресурсозатратных функций во избежание замедления работы мастера.

Если задать balance=true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу, предпочтение отдается репликам, если также задано prefer_replica=true.

Возвращается:

Исходное возвращаемое значение выполняемой функции или nil и ошибка. Объект ошибки содержит атрибут типа, который равен ShardingError или одной из стандартных ошибок Tarantool’а(ClientError, OutOfMemory, SocketError и т.д.).

ShardingError возвращается в случае ошибок шардинга: отсутствует мастер, неверный идентификатор сегмента и т.д. Такая ошибка содержит код с одним из значений из Lua-таблицы vshard.error.code.*, необязательный атрибут сообщения с удобным для восприятия описанием ошибки и другие атрибуты, специфичные для данного кода ошибки.

Примеры:

Для вызова функции customer_add из vshard/example выполните команду:

vshard.router.call(100, 'write', 'customer_add', {{customer_id = 2, bucket_id = 100, name = 'name2', accounts = {}}}, {timeout = 100})
-- или то же самое, но с ассоциативным массивом в качестве второго аргумента
vshard.router.call(100, {mode='write'}, 'customer_add', {{customer_id = 2, bucket_id = 100, name = 'name2', accounts = {}}}, {timeout = 100})
vshard.router.callro(bucket_id, function_name, {argument_list}, {options})

Вызов функции по имени функции (function-name) на шарде, где хранится сегмент с указанным идентификатором (bucket_id) в режиме только для чтения (аналогично вызову vshard.router.call в режиме mode=“read“). Для получения подробной информации о работе функции см. раздел Обработка запросов.

Параметры:
  • bucket_id – идентификатор сегмента
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
Возвращается:

Исходное возвращаемое значение выполняемой функции или nil и ошибка. Объект ошибки содержит атрибут типа, который равен ShardingError или одной из стандартных ошибок Tarantool’а(ClientError, OutOfMemory, SocketError и т.д.).

ShardingError возвращается в случае ошибок шардинга: набор реплик недоступен, отсутствует мастер, неверный идентификатор сегмента и т.д. Такая ошибка сб.одержит код с одним из значений из Lua-таблицы vshard.error.code.*, необязательный атрибут сообщения с удобным для восприятия описанием ошибки и другие атрибуты, специфичные для данного кода ошибки.

vshard.router.callrw(bucket_id, function_name, {argument_list}, {options})

Вызов функции по имени функции (function-name) на шарде, где хранится сегмент с указанным идентификатором (bucket_id) в режиме чтения и записи (аналогично вызову vshard.router.call в режиме mode=“write“). Для получения подробной информации о работе функции см. раздел Обработка запросов.

Параметры:
  • bucket_id – идентификатор сегмента
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
Возвращается:

Исходное возвращаемое значение выполняемой функции или nil и ошибка. Объект ошибки содержит атрибут типа, который равен ShardingError или одной из стандартных ошибок Tarantool’а(ClientError, OutOfMemory, SocketError и т.д.).

ShardingError возвращается в случае ошибок шардинга: набор реплик недоступен, отсутствует мастер, неверный идентификатор сегмента и т.д. Такая ошибка сб.одержит код с одним из значений из Lua-таблицы vshard.error.code.*, необязательный атрибут сообщения с удобным для восприятия описанием ошибки и другие атрибуты, специфичные для данного кода ошибки.

vshard.router.callre(bucket_id, function_name, {argument_list}, {options})

Вызов функции по имени функции (function-name) на шарде, где хранится сегмент с указанным идентификатором (bucket_id) в режиме только для чтения (аналогично вызову vshard.router.call в режиме чтения mode='read'), когда предпочтение отдается реплике, а не мастеру (аналогично вызову vshard.router.call с параметром prefer_replica = true). Для получения подробной информации о работе функции см. раздел Обработка запросов.

Параметры:
  • bucket_id – идентификатор сегмента
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
Возвращается:

Исходное возвращаемое значение выполняемой функции или nil и ошибка. Объект ошибки содержит атрибут типа, который равен ShardingError или одной из стандартных ошибок Tarantool’а(ClientError, OutOfMemory, SocketError и т.д.).

ShardingError возвращается в случае ошибок шардинга: набор реплик недоступен, отсутствует мастер, неверный идентификатор сегмента и т.д. Такая ошибка сб.одержит код с одним из значений из Lua-таблицы vshard.error.code.*, необязательный атрибут сообщения с удобным для восприятия описанием ошибки и другие атрибуты, специфичные для данного кода ошибки.

vshard.router.callbro(bucket_id, function_name, {argument_list}, {options})

Эквивалент vshard.router.call() с параметром mode = {mode='read', balance=true}.

vshard.router.callbre(bucket_id, function_name, {argument_list}, {options})

Эквивалент vshard.router.call() с параметром режима mode = {mode='read', balance=true, prefer_replica=true}.

vshard.router.route(bucket_id)

Возврат объекта набора реплик для сегмента с указанным значением идентификатора сегмента (bucket id).

Параметры:
  • bucket_id – идентификатор сегмента
Возвращается:

объект набора реплик

Пример:

replicaset = vshard.router.route(123)
vshard.router.routeall()

Возврат всех доступных объектов наборов реплик.

Возвращается:ассоциативный массив следующего вида: {UUID = replicaset}
Тип возвращаемого значения:
 ассоциативный массив объектов набора реплик

Пример:

replicasets = vshard.router.routeall()
vshard.router.bucket_id(key)

Объявлено устаревшим. Записывает в журнал предупреждение при использовании, так как не согласуется с числами cdata.

В частности, возвращает 3 различных значения для обычных чисел Lua, таких как 123, для unsigned long long cdata (например 123ULL, или ffi.cast('unsigned long long',123)), и для signed long long cdata (например 123LL, или ffi.cast('long long', 123)). И это важно.

vshard.router.bucket_id(123)
vshard.router.bucket_id(123LL)
vshard.router.bucket_id(123ULL)

Для float и double cdata (ffi.cast('float', number), ffi.cast('double', number)) эти функции возвращают разные значения даже для тех же чисел того же типа с плавающей точкой. Это связано с тем, что функция tostring() для числа cdata с плавающей точкой возвращает не число, а указатель на него. Разное при каждом вызове.

vshard.router.bucket_id_strcrc32() имеет такое же поведение, но не записывает предупреждение. Для случаев, когда такое поведение действитльно необходимо.

vshard.router.bucket_id_strcrc32(key)

Вычисление идентификатора сегмента с помощью простой встроенной хеш-функции.

Параметры:
  • key – хеш-ключ. Это может быть любой Lua-объект (число, таблица, строка).
Возвращается:

идентификатор сегмента

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

число

Пример:

bucket_id = vshard.router.bucket_id_strcrc32(18374927634039)

Примечание

Помните, что это небезопасно. См. bucket_id()

vshard.router.bucket_id_mpcrc32(key)

Эта функция безопаснее, чем bucket_id_strc32. Она берет CRC32 из кодированного значения MessagePack. То есть bucket id целых чисел не зависит от их типа Lua. В случае строкового ключа, он не кодирует его в MessagePack, а берет хэш прямо из строки.

Параметры:
  • key – хеш-ключ. Это может быть любой Lua-объект (число, таблица, строка).
Возвращается:

идентификатор сегмента

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

число

Однако он все равно может возвращать разные значения для не одинакового типа с плавающей точкой. То есть, ffi.cast('float', number) может быть отражено в bucket id, не равном ffi.cast('double', number). Это не может быть исправлено, так как значение с плавающей точкой, даже будучи приведенным к double, может иметь мусор в своей дробной части.

Ключи с плавающей точкой обычно не должны использоваться для вычисления идентификатора сегмента.

Будьте очень осторожны, если вы храните типы с плавающей точкой в спейсе. Когда данные возвращаются из спейса, они приводятся к Lua числам. А если это значение имело пустую дробную часть, то оно будет обработано как целое число функцией bucket_id_mpcrc32(). Поэтому в таких случаях необходимо выполнять явное приведение. Приведем пример проблемы:

tarantool> s = box.schema.create_space('test', {format = {{'id', 'double'}}}); _ = s:create_index('pk')
---
...

tarantool> inserted = ffi.cast('double', 1)
---
...

-- Value is stored as double
tarantool> s:replace({inserted})
---
- [1]
...

-- But when returned to Lua, stored as Lua number, not cdata.
tarantool> returned = s:get({inserted}).id
---
...

tarantool> type(returned), returned
---
- number
- 1
...

tarantool> vshard.router.bucket_id_mpcrc32(inserted)
---
- 1411
...
tarantool> vshard.router.bucket_id_mpcrc32(returned)
---
- 1614
...
vshard.router.bucket_count()

Возврат общего количества сегментов, указанных в vshard.router.cfg()`.

Возвращается:общее количество сегментов
Тип возвращаемого значения:
 число
vshard.router.sync(timeout)

Ожидание синхронизации набора данных на репликах.

Параметры:
  • timeout – время ожидания в секундах
возвращает:

true (правда), если выполнена синхронизация набора данных; или же nil и ошибка err с объяснением причины невозможности синхронизации набора данных.

vshard.router.discovery_wakeup()

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

vshard.router.discovery_set(mode)

Запуск/выключение фонового файбера, используемого роутером для обнаружения сегментов.

Параметры:
  • mode – режим работы файбера обнаружения. Существует три режима: on, off и once

В режиме on (по умолчанию) файбер обнаружения работает в течение всего жизненного цикла роутера. Даже после того, как все сегменты были найдены, он продолжает проверять хранилища и загружать сегменты с некоторой большой периодичностью (DISCOVERY_IDLE_INTERVAL). Это полезно, если топология сегментов часто меняется, а их число небольшое. Роутер будет поддерживать свою таблицу маршрутов в актуальном состоянии даже тогда, когда никакие запросы не обрабатываются.

В режиме off обнаружение сегментов не производится.

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

Этот метод подойдет для включения/выключения обнаружения после того, как роутер уже запущен, но по умолчанию обнаружение включено. Возможно, вы захотите никогда не включать его даже на короткое время – тогда задайте значение опции discovery_mode при конфигурации. Она принимает те же значения, что и vshard.router.discovery_set(mode).

Вы можете решить, что лучше отключить обнаружение или осуществить его в режиме once, если у вас много роутеров или очень много сегментов (сотни тысяч и более), и вы видите, что процесс обнаружения потребляет заметное количество ресурса CPU на роутерах и хранилищах. В этом случае, возможно, было бы разумно отключить обнаружение, когда в кластере нет балансировки. И включать его для новых роутеров, а также для всех роутеров, когда начинается балансировка.

vshard.router.info()

Возврат информации по каждому экземпляру.

Возвращается:

Параметры набора реплик:

  • UUID набора реплик
  • параметры мастер-экземпляра
  • параметры реплики

Параметры экземпляра:

  • uri – URI экземпляра
  • uuid – UUID экземпляра
  • status – статус экземпляра: available (доступный), unreachable (недоступный), missing (отсутствующий)
  • network_timeout – время ожидания запроса. Данное значение обновляется автоматически на каждом 10 выполненном запросе и на каждом 2 невыполненном запросе.

Параметры сегмента:

  • available_ro – количество сегментов, известных роутеру и доступных для запросов чтения
  • available_rw – количество сегментов, известных роутеру и доступных для запросов чтения и записи
  • unavailable – количество сегментов, известных роутеру, но недоступных для любых запросов
  • unreachable– количество сегментов, для которых роутер не знает соответствующие наборы реплик

Пример:

tarantool> vshard.router.info()
---
- replicasets:
    ac522f65-aa94-4134-9f64-51ee384f1a54:
      replica: &0
        network_timeout: 0.5
        status: available
        uri: storage@127.0.0.1:3303
        uuid: 1e02ae8a-afc0-4e91-ba34-843a356b8ed7
      uuid: ac522f65-aa94-4134-9f64-51ee384f1a54
      master: *0
    cbf06940-0790-498b-948d-042b62cf3d29:
      replica: &1
        network_timeout: 0.5
        status: available
        uri: storage@127.0.0.1:3301
        uuid: 8a274925-a26d-47fc-9e1b-af88ce939412
      uuid: cbf06940-0790-498b-948d-042b62cf3d29
      master: *1
  bucket:
    unreachable: 0
    available_ro: 0
    unknown: 0
    available_rw: 3000
  status: 0
  alerts: []
...
vshard.router.buckets_info()

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

Параметры:
  • offset – начальное значение выборки сегментов
  • limit – максимальное количество показываемых сегментов
Возвращается:

ассоциативный массив следующего вида: {bucket_id = 'unknown'/replicaset_uuid}

object replicaset_object
replicaset_object:call(function_name, {argument_list}, {options})

Вызов функции с указанными аргументами на ближайшем доступном мастере (расстояние определяется с помощью матрицы replica.zone и cfg.weights).

Примечание

Метод replicaset_object:call аналогичен replicaset_object:callrw.

Параметры:
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
возвращает:
  • результат вызываемой функции при успехе
  • nil, err иначе
replicaset_object:callrw(function_name, {argument_list}, {options})

Вызов функции с указанными аргументами на ближайшем доступном мастере (расстояние определяется с помощью матрицы replica.zone и cfg.weights).

Примечание

Метод replicaset_object:callrw аналогичен replicaset_object:call.

Параметры:
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
возвращает:
  • результат вызываемой функции при успехе
  • nil, err иначе
replicaset_object:callro(function_name, {argument_list}, {options})

Вызов функции с указанными аргументами на ближайшей доступной реплике (расстояние определяется с помощью матрицы replica.zone и cfg.weights). С помощью replicaset_object:callro() рекомендуется вызывать исключительно функции, доступные только для чтения. поскольку такие функции можно выполнять не только на мастере, но и на репликах.

Параметры:
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
возвращает:
  • результат вызываемой функции при успехе
  • nil, err иначе
replicaset:callre(function_name, {argument_list}, {options})

Вызов функции с указанными аргументами на ближайшей доступной реплике (расстояние определяется с помощью матрицы replica.zone и cfg.weights), предпочтение отдается реплике, а не мастеру (аналогично вызову vshard.router.call с параметром prefer_replica = true). С помощью replicaset_object:callre() рекомендуется вызывать исключительно функции, доступные только для чтения, поскольку такие функции можно выполнять не только на мастере, но и на репликах.

Параметры:
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
  • options
    • timeout – время ожидания запроса в секундах. Если роутер не может определить шард с идентификатором сегмента, операция повторяется до истечения времени ожидания.
    • другие net.box опции, такие как is_async, buffer, on_push также поддерживаются.
возвращает:
  • результат вызываемой функции при успехе
  • nil, err иначе

Внутренние API роутера

vshard.router.bucket_discovery(bucket_id)

Поиск сегмента по всему кластеру. Если сегмент не обнаружен, скорее всего, он не существует. Также сегмент также может быть перемещен во время балансировки и в данный момент находится в статусе получения RECEIVING.

Параметры:
  • bucket_id – идентификатор сегмента

Общедоступные API хранилища

vshard.storage.cfg(cfg, name)

Конфигурация базы данных и начало шардинга на указанном экземпляре хранилища.

Параметры:
  • cfg – конфигурация хранилища
  • instance_uuid – UUID экземпляра
vshard.storage.info()

Возврат информации по экземпляру хранилища в следующем формате:

tarantool> vshard.storage.info()
---
- buckets:
    2995:
      status: active
      id: 2995
    2997:
      status: active
      id: 2997
    2999:
      status: active
      id: 2999
  replicasets:
    2dd0a343-624e-4d3a-861d-f45efc571cd3:
      uuid: 2dd0a343-624e-4d3a-861d-f45efc571cd3
      master:
        state: active
        uri: storage:storage@127.0.0.1:3301
        uuid: 2ec29309-17b6-43df-ab07-b528e1243a79
    c7ad642f-2cd8-4a8c-bb4e-4999ac70bba1:
      uuid: c7ad642f-2cd8-4a8c-bb4e-4999ac70bba1
      master:
        state: active
        uri: storage:storage@127.0.0.1:3303
        uuid: 810d85ef-4ce4-4066-9896-3c352fec9e64
...
vshard.storage.call(bucket_id, mode, function_name, {argument_list})

Вызов указанной функции на текущем экземпляре хранилища.

Параметры:
  • bucket_id – идентификатор сегмента
  • mode – тип функции: „read“ или „write“ (чтение или запись)
  • function_name – выполняемая функция
  • argument_list – массив аргументов функции
Возвращается:

Исходное возвращаемое значение выполняемой функции или nil и ошибка.

vshard.storage.sync(timeout)

Ожидание синхронизации набора данных на репликах.

Параметры:
  • timeout – время ожидания в секундах
возвращает:

true (правда), если выполнена синхронизация набора данных; или же nil и ошибка err с объяснением причины невозможности синхронизации набора данных.

vshard.storage.bucket_pin(bucket_id)

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

Параметры:
  • bucket_id – идентификатор сегмента
возвращает:

true (правда), если выполнено закрепление сегмента; или же nil и ошибка err с объяснением причины невозможности закрепления сегмента

vshard.storage.bucket_unpin(bucket_id)

Возврат закрепленного сегмента в активное состояние.

Параметры:
  • bucket_id – идентификатор сегмента
возвращает:

true (правда), если выполнено открепление сегмента; или же nil и ошибка err с объяснением причины невозможности открепления сегмента

vshard.storage.bucket_ref(bucket_id, mode)

Создание ссылки типа RO или RW.

Параметры:
  • bucket_id – идентификатор сегмента
  • mode – „read“ или „write“ (чтение или запись)
возвращает:

true (правда), если выполнено создание ссылки; или же nil и ошибка err с объяснением причины невозможности создания ссылки

vshard.storage.bucket_refro()

Псевдоним для vshard.storage.bucket_ref в режиме только чтения.

vshard.storage.bucket_refrw()

Псевдоним для vshard.storage.bucket_ref в режиме чтения и записи.

vshard.storage.bucket_unref(bucket_id, mode)

Удаление ссылки RO/RW.

Параметры:
  • bucket_id – идентификатор сегмента
  • mode – „read“ или „write“ (чтение или запись)
возвращает:

true (правда), если выполнено удаление ссылки; или же nil и ошибка err с объяснением причины невозможности удаления ссылки

vshard.storage.bucket_unrefro()

Псевдоним для vshard.storage.bucket_unref в режиме только чтения.

vshard.storage.bucket_unrefrw()

Псевдоним для vshard.storage.bucket_unref в режиме чтения и записи.

vshard.storage.find_garbage_bucket(bucket_index, control)

Поиск сегмента, который хранит данные в спейсе, но не указан в спейсе _bucket, или находится в статусе мусора (GARBAGE).

Параметры:
  • bucket_index – индекс спейса с частью идентификатора спейса
  • control – контроллер сборщика мусора. Если увеличивается масштаб создания сегментов, поиск следует прервать.
возвращает:

идентификатор сегмента в статусе мусора, если таковой обнаружен; в противном случае, nil

vshard.storage.buckets_info()

Возврат информации по каждому сегменту, расположенному в хранилище. Например:

vshard.storage.buckets_info(1)
---
- 1:
    status: active
    ref_rw: 1
    ref_ro: 1
    ro_lock: true
    rw_lock: true
    id: 1
vshard.storage.buckets_count()

Возврат количества сегментов, расположенных в хранилище.

vshard.storage.recovery_wakeup()

Немедленный запуск файбера восстановления, если такой есть.

vshard.storage.rebalancing_is_in_progress()

Возврат флага, указывающего на ход процесса балансировки. Результатом будет true (правда), если в данный момент узел применяет маршруты, полученные от узла балансировки в специальном файбере.

vshard.storage.is_locked()

Возврат флага, указывающего на недоступность хранилища для балансировщика.

vshard.storage.rebalancer_disable()

Отключение балансировки. Отключенный балансировщик находится в режиме ожидания до повторного запуска с помощью vshard.storage.rebalancer_enable().

vshard.storage.rebalancer_enable()

Запуск балансировки.

vshard.storage.sharded_spaces()

Отображение спейсов, которые доступны балансировщику и файберам сборщика мусора.

Внутренние API хранилища

vshard.storage.bucket_recv(bucket_id, from, data)

Получение сегмента по идентификатору сегмента (bucket id) из удаленного набора реплик.

Параметры:
  • bucket_id – идентификатор сегмента
  • from – UUID исходного набора реплик
  • data – данные, которые хранятся логически в сегменте, определенном по идентификатору сегмента (bucket_id), в том же формате, что и возвращаемое значение метода bucket_collect() <storage_api-bucket_collect>
vshard.storage.bucket_stat(bucket_id)

Возврат информации об идентификаторе сегмента (bucket id):

tarantool> vshard.storage.bucket_stat(1)
---
- 0
- status: active
  id: 1
...
Параметры:
  • bucket_id – идентификатор сегмента
vshard.storage.bucket_delete_garbage(bucket_id)

Принудительная сборка мусора для сегмента, найденного по идентификатору (bucket_id), если сегмент был перемещен в другой набор реплик.

Параметры:
  • bucket_id – идентификатор сегмента
vshard.storage.bucket_collect(bucket_id)

Сбор всех данных, которые хранятся логически в сегменте, найденном по идентификатору (bucket_id):

tarantool> vshard.storage.bucket_collect(1)
---
- 0
- - - 514
    - - [10, 1, 1, 100, 'Account 10']
      - [11, 1, 1, 100, 'Account 11']
      - [12, 1, 1, 100, 'Account 12']
      - [50, 5, 1, 100, 'Account 50']
      - [51, 5, 1, 100, 'Account 51']
      - [52, 5, 1, 100, 'Account 52']
  - - 513
    - - [1, 1, 'Customer 1']
      - [5, 1, 'Customer 5']
...
Параметры:
  • bucket_id – идентификатор сегмента
vshard.storage.bucket_force_create(first_bucket_id, count)

Принудительное создание сегментов (одного или нескольких) в текущем наборе реплик. Используется только для ручного аварийного восстановления или для начальной настройки.

Параметры:
  • first_bucket_id – идентификатор первого сегмента в диапазоне
  • count – количество вставляемых сегментов (по умолчанию, 1)
vshard.storage.bucket_force_drop(bucket_id)

Удаление сегмента вручную для тестирования или в аварийной ситуации.

Параметры:
  • bucket_id – идентификатор сегмента
vshard.storage.bucket_send(bucket_id, to)

Отправка указанного сегмента из текущего набора реплик в удаленный набор реплик.

Параметры:
  • bucket_id – идентификатор сегмента
  • to – UUID удаленного набора реплик
vshard.storage.rebalancer_request_state()

Проверка всех сегментов хост-хранилища в статусе отправки SENT или активном статусе ACTIVE, возврат количества активных сегментов.

возвращает:количество сегментов в активном статусе, если таковые обнаружены; в противном случае, nil
vshard.storage.buckets_discovery()

Сбор массива идентификаторов активных сегментов для обнаружения.