Тулинг: утилиты командной строки

Смежные: Первые шаги · Режимы долговечности · Справочник

Амальгамированный пакет включает утилиты для администрирования и диагностики БД (сборка — MDBX_BUILD_TOOLS=ON или make mdbx_chk и т.п.).

Каждая утилита печатает баннер версии по -V, сообщение с синтаксисом по -h/--help, завершается статусом 0 при успехе и ненулевым при ошибке. Большинство утилит корректно прерываются по SIGINT/SIGTERM (Ctrl-C).

mdbx_chk — проверка целостности

Валидация структуры БД: B+tree, согласованность GC, порядок ключей, бухгалтерия страниц. Рекомендуется:

после сбоев при отладке собственной интеграции;
периодически — как часть операционного мониторинга;
после восстановления из резервной копии.

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

mdbx_chk database.mdb          # базовая проверка только для чтения
mdbx_chk -vv database.mdb      # подробный вывод
mdbx_chk -w database.mdb       # режим записи: устраняет исправимые проблемы

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-v`	Более подробный вывод; повторяется до 9 раз (`-vv`, `-vvv`, ...).
`-q`	Тихий режим.
`-c`	Принудительно кооперативный режим; не пытаться открывать эксклюзивно. Только эксклюзивный режим позволяет полностью проверить все meta-страницы и фактический размер файла БД.
`-w`	Открыть для чтения и записи с блокировкой. Позволяет откатиться к последнему устойчивому коммиту и проверить идентификаторы транзакций meta-страниц.
`-d`	Отключить постраничный обход B+дерева (тогда потерянные/дважды используемые страницы не обнаруживаются).
`-i`	Игнорировать ошибки неправильного порядка (часты при кастомных компараторах).
`-s table`	Проверить и показать информацию только для указанной таблицы.
`-0`/`-1`/`-2`	Использовать для проверки указанную meta-страницу.
`-t`	Перейти к указанной meta-странице при успешной проверке.
`-T`	Перейти к указанной meta-странице даже при неуспешной проверке.
`-u`	Прогреть БД перед проверкой.
`-U`	Прогреть и принудительно заблокировать страницы БД в памяти перед проверкой.
`-n`	Легаси-вариант без действия (однофайловые окружения определяются автоматически).
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

mdbx_chk различает классы проблем кодом возврата:

Код	Значение
`0`	ошибок не обнаружено
`1`	второстепенные проблемы (не связаны с meta/значениями/GC)
`2`	серьёзные проблемы (meta-страницы, пары ключ-значение или GC)
`3`	ошибка libmdbx
`4`	системная ошибка
`5`	прервано пользователем или некорректный вызов

mdbx_copy — горячее копирование

Консистентная копия БД без остановки писателей — упорядоченный обход страниц в снапшоте. Обычное копирование файла (cp) во время активной записи такой гарантии не даёт. Назначение может быть путём к файлу/каталогу или стандартным выводом. Учтите: параллельное копирование с активными писателями может временно увеличить исходный файл.

mdbx_copy source.mdb backup.mdb
mdbx_copy -c source.mdb backup.mdb  # компактная копия: без неиспользуемых страниц
mdbx_copy source.mdb > backup.mdb   # вывод в stdout

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-q`	Тихий режим.
`-c`	Компактность при копировании: копируются только актуальные страницы данных, свободные/неиспользуемые пропускаются. Медленнее и затратнее по CPU; сейчас завершается ошибкой, если окружение пострадало от утечки страниц.
`-f`	Молча перезаписать целевой файл, если он существует, вместо ошибки.
`-d`	Принудительно сделать копию БД с динамическим размером (рост/сжатие разумными шагами на лету).
`-p`	Использовать парковку/вытеснение read-транзакций при копировании MVCC-снапшота, чтобы не блокировать переработку и не переполнить БД.
`-u`	Прогреть БД перед копированием.
`-U`	Прогреть и принудительно заблокировать страницы БД в памяти перед копированием.
`-n`	Легаси-вариант; однофайловые окружения определяются автоматически.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

Программный аналог — mdbx_env_copy2...() (C API).

mdbx_dump / mdbx_load — выгрузка и загрузка

Текстовый (или unicode-escape) дамп содержимого БД → перенос между платформами, диагностика содержимого, восстановление:

mdbx_dump database.mdb > dump.txt
mdbx_load new.mdb < dump.txt

Важно: при выгрузке/загрузке БД с кастомными функциями сравнения эти функции теряются — после перезагрузки используется сравнение по умолчанию, что почти наверняка повредит данные. Такие БД нужно загружать с -a.

mdbx_dump

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-q`	Тихий режим.
`-c`	Краткий режим без повторения ключей; несовместим с Berkeley DB и LMDB.
`-f file`	Писать в указанный файл вместо stdout.
`-l`	Перечислить таблицы окружения и выйти (без вывода данных).
`-p`	Выводить печатные символы как есть (подмножество переносимого текста; менее переносимо между системами).
`-a`	Выгрузить все таблицы окружения.
`-s table`	Выгрузить только указанную таблицу (по умолчанию — главную).
`-r`	Режим спасения: игнорировать часть ошибок для выгрузки повреждённой БД.
`-u`	Прогреть БД перед выгрузкой.
`-U`	Прогреть и принудительно заблокировать страницы БД в памяти перед выгрузкой.
`-n`	Легаси-вариант; однофайловые окружения определяются автоматически.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

mdbx_load

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-q`	Тихий режим.
`-a`	Добавлять все записи в порядке входных данных; без сортировки и проверки дубликатов. Обязательно для перезагрузки выгрузок БД с кастомными компараторами.
`-b number`	Размер пакета вставки в записях (по умолчанию 100K).
`-L megabytes`	Ограничить единичную транзакцию указанным размером в мегабайтах.
`-d percent`	Желаемая плотность заполнения страниц, 50..100 (по умолчанию 100).
`-G L:U:G:S:P`	Переопределить геометрию БД: минимальный размер, максимальный размер, шаг роста, порог сжатия, размер страницы (в байтах).
`-f file`	Читать из указанного файла вместо stdin.
`-s table`	Загрузить в указанную таблицу (по умолчанию — главную).
`-N`	Не перезаписывать существующие записи, пропускать их.
`-p`	Очистить целевые таблицы перед загрузкой.
`-T`	Загружать простой текст: пары строк (ключ, затем значение).
`-r`	Режим спасения: игнорировать ошибки для загрузки повреждённого дампа.
`-n`	Легаси-вариант; однофайловые окружения определяются автоматически.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

mdbx_stat — статистика

Статистика окружения, таблиц, транзакций и читателей: размеры, счётчики страниц/записей, перечисление активных читателей (полезно при диагностике «долгоживущих читателей» — см. ограничения).

mdbx_stat database.mdb
mdbx_stat -a -e database.mdb     # инфо об окружении + все таблицы

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-q`	Тихий режим.
`-p`	Статистика операций со страницами текущей многопроцессной сессии.
`-e`	Информация об окружении.
`-a`	Статус всех таблиц.
`-s table`	Статус указанной таблицы.
`-f`	Информация о GC/свободном списке. `-ff` — сводка по каждой записи GC, `-fff` — полный список идентификаторов страниц.
`-r`	Таблица читателей (pid, поток, id транзакции). `-rr` — дополнительно проверить и очистить устаревшие записи о читателях.
`-n`	Легаси-вариант; однофайловые окружения определяются автоматически.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

mdbx_drop — удаление БД/таблицы

Опустошает или удаляет базу данных (таблицу) в окружении:

mdbx_drop -d database.mdb            # удалить главную БД
mdbx_drop -s named_table database.mdb

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-q`	Тихий режим.
`-d`	Удалить указанную БД, а не просто опустошить её.
`-s table`	Работать с указанной таблицей (по умолчанию — главной).
`-n`	Легаси-вариант; однофайловые окружения определяются автоматически.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

mdbx_defrag — дефрагментация

Перенос живых страниц к началу файла с усечением хвоста. Обычно не требуется (непрерывная zero-overhead компактация работает на каждом коммите), но полезно после массовых удалений в старых версиях БД. БД остаётся полностью доступной во время дефрагментации; утилиту можно прервать по Ctrl-C без повреждения базы.

mdbx_defrag database.mdb
mdbx_defrag -t 600 database.mdb    # ограничить длительность 10 минутами

Опция	Описание
`-V`	Вывести версию и сборочную информацию библиотеки, выйти.
`-v`	Более подробный вывод; повторяется до 9 раз.
`-q`	Тихий режим.
`-1`	Один быстрый цикл дефрагментации без двухэтапных переносов.
`-2`..`-9`	Ограничить число циклов дефрагментации.
`-t seconds`	Ограничить длительность дефрагментации.
`-f percent`	Дефрагментировать, пока не освободится указанный процент неиспользуемого места (1..100, по умолчанию 100).
`-r percent`	Допустимый недефрагментированный остаток (процент от занятого места, по умолчанию 0).
`-s megabytes`	Предпочтительный размер шага/транзакции дефрагментации.
`-c`	Принудительно кооперативный режим; не пытаться открывать эксклюзивно.
`-u`	Прогреть БД перед дефрагментацией.
`-U`	Прогреть и принудительно заблокировать страницы БД в памяти перед дефрагментацией.
`-h`/`--help`	Вывести сообщение с синтаксисом и выйти.

Общие рекомендации

Все утилиты безопасно применять к копии для диагностики.
mdbx_chk -V показывает сборочные опции (options: строка) — при контейнерном/кросс-хостовом использовании строка должна совпадать (см. Установка и сборка).
Для автоматизации — коды возврата соответствуют статусу операции; подробный вывод управляется опциями verbosity.