Утилита reindexer_tool для управления БД Reindexer через командную строку

Консольная утилита reindexer_tool предназначена для управления сервером Reindexer и базами данных с помощью интерфейса командной строки. Утилита может работать как клиент для сервера Reindexer с доступом по сети, или самостоятельно непосредственно с локальным дисковым хранилищем без участия сервера.

Возможности reindexer_tool

Консольная утилита reindexer_tool позволяет:

  • Выполнять бэкапы базы данных. Результат можно вывести в командную строку (консоль) или сохранить в текстовый файл.
  • Делать запросы к базе данных. Можно выполнять запросы из командной строки или из файла. Результаты также можно выводить в командную строку или записывать в файл.
  • Изменять записи в базе данных.
  • Изменять связанные с базой данных метаданные.
  • Конвертировать хранилище базы данных к другому типу.

Использование утилиты

Утилита может работать в интерактивном режиме или запускаться однократно для выполнения одной или нескольких команд с автоматическим завершением после этого. Обобщенный синтаксис команды для запуска reindexer_tool:

reindexer_tool [<db_name>] {<options>}

Здесь:

  • [<db_name>](обязательный) — имя базы данных, к которой нужен доступ;
  • {<options>} — набор опций.

В качестве [<db_name>] можно передавать:

  • Имя базы данных dbname. В этом случае происходит подключение к cproto://reindexer:reindexer@127.0.0.1:6534/dbname ( или cprotos://reindexer:reindexer@127.0.0.1:6535/dbname, если необходимо подключиться по RPC с использованием протокола TLS).
  • Имя источника данных — DSN (Data Source Name). Указывается как опция командной строки - d, --dsn и определяет особенности подключения к северу Reindexer или непосредственно к дисковому хранилищу. Возможные форматы:
    • builtin://<path> — для случая, когда Reindexer используется в режиме встроенного компонента (built-in, embedded). Здесь <path> — путь к дисковому хранилищу, доступ к нему со стороны reindexer_tool производится напрямую.
    • cproto(s)://<username>:<password>@<host>:<port>/<db_name> — подключение к автономному (stand-alone) или работающему в режиме встроенного сервера (built-in server) Reindexer по сети с помощью RPC/RPCs(RPC с поддержкой TLS). Здесь:
      • <username> — имя пользователя;
      • <password> — пароль;
      • <host> — имя или адрес хоста, на котором развернут сервер;
      • <port> — порт, который прослушивается сервером в рамках взаимодействия с клиентами по RPC;
      • <db_name> — имя базы данных;

Опции командной строки для запуска утилиты reindexer_tool

Опция Значение Особенности
-d, --dsn DSN для подключения к базе данных Возможные варианты: cproto://<ip>:<port>/<dbname>, cprotos://<ip>:<port>/<dbname>, builtin://<path> или ucproto://<unix.socket.path>:/<dbname>
-f, --filename Путь к файлу, содержащему список команд для выполнения После выполнения команд из файла утилита завершает работу
-c, --command Одиночная команда для выполнения, которая использует внутренний DSL или представляет собой SQL-запрос После выполнения команды утилита завершает работу
-o, --output Путь к файлу для вывода результатов выполнения одиночной команды либо запроса, или списка команд (запросов) Значение по умолчанию stdout - используется стандартный вывод
--createdb Флаг, предписывающий создать базу данных с заданным именем После выполнения команды reindexer_tool запускается в интерактивном режиме и подключается к созданной базе данных
--dry-run Проверка файла дампа без изменения целевой базы данных Применимо только с -f, --filename; несовместимо с -c, --command
--ignore-checksum-mismatch Применение дампа даже при несовпадении -- __checksum Предупреждение о несовпадении все равно выводится
--convfmt Формат, в который следует сконвертировать хранилище базы данных Возможные варианты: leveldb и rocksdb
--convbackup Путь к директории, в которую следует сохранить оригинальное хранилище базы данных в случае если выполняется его конвертация к другому типу. Данный параметр является опциональным, его можно указывать только вместе с указанием --convfmt
-l, --log Уровень логирования Задается в виде целого числа. Возможные значения:
1 - none
2 - warning
3 - error
4 - info
5 - trace
-C, --connections Количество одновременных соединений с базой данных
-r, --repair Флаг, который сообщает, что необходимо выполнить восстановление/исправление базы данных с нарушенной целостностью
-a, --appname Имя приложения-клиента, которое должно использоваться в составе данных о логине (при доступе с использованием аутентификации) со стороны reindexer_tool
-h, --help Флаг для вывода краткой справки о назначении аргументов командной строки После выполнения команды утилита завершает работу
-v, --version Флаг для вывода текущей версии reindexer_tool После выполнения команды утилита завершает работу

Бэкап и восстановление базы данных

Создание дампа базы данных в виде файла:

reindexer_tool --dsn cproto://127.0.0.1:6534/mydb --command '\dump' --output mydb.rxdump

Созданный дамп содержит служебную команду -- __checksum: "<md5>". MD5-хеш вычисляется по всем непустым логическим строкам, которые не являются комментариями (не начинаются с --): строки хэшируются без символов перевода строки, чтобы один и тот же файл давал одинаковый хеш в Windows и Linux. Комментарии, включая саму строку checksum, баннеры, __dump_mode и заголовки Dumping namespace ..., не участвуют в вычислении хеша.

Восстановление базы данных из дампа:

reindexer_tool --dsn cproto://127.0.0.1:6534/mydb --filename mydb.rxdump

По умолчанию reindexer_tool в процессе восстановления из дампа не будет создавать целевую БД, если она отсутствует. Если требуется автоматическое создание БД, то следует добавить опцию --createdb.

Проверка файла дампа без изменения целевой базы данных:

reindexer_tool --dsn cproto://127.0.0.1:6534/mydb --filename mydb.rxdump --dry-run

Что проверяет dry-run

  • Необязательные метаданные -- __checksum:: если они есть, хеш пересчитывается по тем же правилам, что и при выполнении \dump, и должен совпадать.
  • Формат и порядок команд дампа: начальные комментарии, \NAMESPACES ADD, \META PUT, \UPSERT.
  • JSON в каждой команде \NAMESPACES ADD: он должен разбираться как корректный NamespaceDef, имя неймспейса в команде должно совпадать с именем в JSON, а в дампе не должно быть дубликатов \NAMESPACES ADD для одного неймспейса.
  • JSON в каждой команде \UPSERT: он должен разбираться и соответствовать схеме и типам, объявленным в соответствующей команде \NAMESPACES ADD (для проверки схемы используется временная in-memory база данных). Для записей #config проверка пропускает элементы с type=action и type=sharding, повторяя поведение восстановления.
  • Команды \META PUT: они должны ссылаться на ранее объявленный неймспейс.
  • Для каждого неймспейса, который есть и в дампе, и на целевой стороне, полный набор IndexDef должен совпадать: имя, JSON paths, типы индексов и полей, expire-after, опции и параметры.

Вывод и код завершения

Утилита выводит три секции, каждая со своим заголовком:

  1. ошибки дампа с номерами строк;
  2. неймспейсы, которые есть и в дампе, и на целевой стороне, если на целевой стороне они непустые (потенциальные конфликты);
  3. неймспейсы, которые есть на целевой стороне, но отсутствуют в дампе.

Если найдена хотя бы одна ошибка, утилита завершается с ненулевым кодом. Списки конфликтов и неймспейсов, присутствующих только на целевой стороне, являются предупреждениями: они выводятся в любом случае, но не влияют на код завершения. Флаг --ignore-checksum-mismatch влияет на то, является ли несовпадение контрольных сумм(__checksum) ошибкой или предупреждением.

Ограничения

  • --dry-run требует -f, --filename и несовместим с -c, --command.
  • --createdb намеренно не применяется в режиме dry-run, поэтому целевая база данных должна уже существовать. Если ее нет, утилита завершится с ошибкой до начала проверки.
  • --dry-run никогда не записывает данные в целевую базу данных. Неймспейсы для проверки создаются в памяти с явно отключенным хранилищем.
  • При обычном восстановлении, если дамп содержит -- __checksum и хеш не совпадает, reindexer_tool выводит предупреждение Dump checksum mismatch. Expected '...', Computed '...' и по умолчанию прерывает восстановление. Чтобы продолжить восстановление несмотря на несовпадение, используйте --ignore-checksum-mismatch. Предупреждение при этом все равно выводится.

Конвертация хранилища базы данных к другому типу

В момент конвертации БД не должна использовать другими процессами.

Пример конвертации хранилища в формат rocksdb:

reindexer_tool --dsn builtin:///tmp/rx/dbase_name --convfmt rocksdb --convbackup /tmp/rx_backup/dbase_name_leveldb

Здесь dsn задает путь к хранилищу базы данных, которое требуется скорректировать (при этом требуется использовать builtin://-вариант подключения), convfmt задает формат, в который нужно сконвертировать хранилище (rocksdb или leveldb). При этом новый тип должен отличаться от текущего, иначе выполнение команды будет завершено с ошибкой. Необязательный параметр convbackup позволяет указать директорию, в которую следует сохранить оригинальное хранилище в случае если это необходимо.

Для конвертации хранилища обратно в leveldb можно использовать предыдущую команду, заменив в ней значение convfmt:

reindexer_tool --dsn builtin:///tmp/rx/dbase_name --convfmt leveldb --convbackup /tmp/rx_backup/dbase_name_rocksdb

Использование reindexer_tool в интерактивном режиме

Для запуска reindexer_tool в интерактивном режиме используется shell-команда вида

reindexer_tool [<db_name>]

или

reindexer_tool [<db_name>] {<options>}

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

При работе в интерактивном режиме reindexer_tool может выполнять SQL-запросы и команды, которые записываются с префиксом \.

Получение справки

Для получения справки по запросам и командам, поддерживаемым reindexer_tool в интерактивном режиме, выполните команду:

\help

SQL-запросы

Указываются без префикса. В качестве команды для утилиты reindexer_tool может выступать SQL-запрос, который начинается с ключевых слов:

  • SELECT,
  • DELETE,
  • UPDATE,
  • EXPLAIN.

Добавление новой записи (документа) в неймспейс

Обобщенный синтаксис команды:

\upsert <namespace> <document>

Здесь:

  • <namespace> — имя неймспейса;
  • <document> — содержимое новой записи (документа).

Пример использования команды:

\upsert books {"id":5,"name":"NewBook"}

Удаление записи (документа) из неймспейса

Обобщенный синтаксис команды:

\delete <namespace> <document>

Здесь:

  • <namespace> — имя неймспейса;
  • <document> — содержимое записи (документа).

Пример использования команды:

\delete books {"id":5}

Создание бэкапа базы данных в виде дампа в текстовом формате

Обобщенный синтаксис команды:

\dump [namespace1 [namespace2]...]

Здесь <namespace_*> — имена неймспейсов, данные которых нужно включить в дамп. Эти параметры необязательны. Если их не указывать и выполнить команду \dump, произойдет бэкап базы данных, к которой подключен reindexer_tool, целиком.

Команды для управления неймспейсами

Создание нового неймспейса

Обобщенный синтаксис команды:

\namespaces add <namespace> <definition>

Здесь:

  • <namespace> — имя нового неймспейса;
  • <definition> — определение нового неймспейса.
Вывод списка доступных неймспейсов в текущей базе данных

Синтаксис команды:

\namespaces list
Удаление неймспейса из базы данных

Обобщенный синтаксис команды:

\namespaces drop <namespace>

Здесь <namespace> — имя удаляемого неймспейса.

Команды для управления базами данных

Вывод списка доступных баз данных

Синтаксис команды:

\databases list
Переключение между базами данных

Обобщенный синтаксис команды:

\databases use <dbname>

Здесь <dbname> — имя базы данных, на которую нужно переключиться.

Команды для управления метаданными

Добавление новой порции метаданных

Обобщенный синтаксис команды:

\meta put <namespace> <key> <value>

Здесь:

  • <namespace> — имя неймспейса;
  • <key> — ключ добавляемой порции метаданных;
  • <value> — содержимое метаданных.
Вывод всех метаданных, которые относятся к неймспейсу

Обобщенный синтаксис команды:

\meta list <namespace>

Здесь <namespace> — имя неймспейса.

Задание выходного формата данных

Обобщенный синтаксис команды:

\set output <format>

Здесь <format> — выходной формат. Возможные значения:

  • json — неформатированный JSON;
  • pretty — JSON с разбиением на строки и форматированием;
  • table — табличное представление (со строками и столбцами).

Запуск простого теста производительности

Обобщенный синтаксис команды:

\bench [<time>]

Здесь [<time>] — необязательный параметр, устанавливающий длительность выполнения теста в секундах. Значение по умолчанию — 5 секунд.

Завершение работы утилиты reindexer_tool

Синтаксис команды:

\quit