Skip to content
EN

Учебник по libmdbx — Том 0. Каркас (оглавление)

Это оглавление и структура учебника из шести томов: от базовых концепций до биндингов. Каждый том — отдельный файл в этом каталоге; все тома связаны перекрёстными ссылками и единым сквозным проектом.

Общая логика прогрессии

Базовые концепции (Том I) → Практика использования (Том II) → Внутренние механизмы (Том III)
→ Производительность и оптимизация (Том IV) → Экспертные темы и edge cases (Том V) → Привязки (Том VI)

Каждая глава — по схеме «концепция → механизм → практика → нюанс». Термин определяется при первом употреблении. Сквозной проект (конфигуратор приложений) ведётся с Тома I по Том II; упражнения — шаги этого проекта.

Том I. Основы (для новичков)

Цель: читатель без опыта работы с embedded key-value БД понимает libmdbx, умеет собрать и выполнить первые операции. Объём ~50–100 страниц.

  • Гл. 1. Что такое libmdbx
  • Встраиваемые vs клиент-серверные БД; key-value модель; почему mmap; место в ландшафте (LMDB/BerkeleyDB/LevelDB/RocksDB/SQLite на уровне архитектурных свойств); лицензия, экосистема, известные пользователи (Erigon, Reth, Isar, Monica Pass).
  • Гл. 2. Установка и первый запуск
  • Сборка (амальгама vs полный исходник), подключение (CMake/pkg-config/статика/динамика), ключевые опции сборки; минимальный пример open→put→get; запуск тестов.
  • Гл. 3. Базовая модель данных
  • MDBX_val; главная таблица и dbi; флаги MDBX_CREATE; ограничения (ключ/значение/число таблиц); integer-ключи; нулевые ключи/значения (отличие от LMDB).
  • Гл. 4. Базовые операции CRUD
  • put/get/del/replace; флаги (NOOVERWRITE/NODUPDATA/CURRENT/ALLDUPS); чтение get vs курсор; полные C-примеры; обработка кодов возврата.
  • Гл. 5. Транзакции — первые шаги
  • Зачем транзакции; begin/commit/abort; read-only vs read-write; MVCC интуитивно; правило «одна транзакция — один поток»; примеры.

Том II. Практическое использование (для разработчиков)

Цель: читатель строит приложения: курсоры, мультизначения, индексы, конфигурация, долговечность, многопоточность, обработка ошибок. Объём ~100–200 страниц.

  • Гл. 6. Курсоры — позиционирование (FIRST/LAST/NEXT/PREV/SET/SET_RANGE/LOWER/UPPER_BOUND), пакетные операции, UB после удаления, clone/bind, паттерн safe-delete в DUPSORT, примеры.
  • Гл. 7. Мультизначения и DUPSORT — DUPFIXED/INTEGERDUP/REVERSEDUP, вложенное поддерево значений, инвертированные индексы «ключ→список ID», GET_BOTH/GET_BOTH_RANGE, вторичный индекс.
  • Гл. 8. Вторичные индексы — основная таблица + индексные; DUPSORT-индекс vs отдельная таблица; поддержание консистентности; составные ключи; удаление по индексу; мини-ORM.
  • Гл. 9. Конфигурация окружения — геометрия (lower/now/upper/growth_step/shrink_threshold), maxreaders/maxdbs/pagesize, flags, runtime options MDBX_opt_*, выбор страницы 4/8/64 КБ, env_info/env_stat.
  • Гл. 10. Режимы долговечности — SYNC_DURABLE/NOMETASYNC/SAFE_NOSYNC/UTTERLY_NOSYNC/WRITEMAP; когда какой; syncbytes/syncperiod; mdbx_env_sync_ex; платформенные нюансы (F_FULLFSYNC, boot_id, LockFileEx).
  • Гл. 11. Многопоточность — sticky threads; NOSTICKYTHREADS (пулы/корутины); регистрация потоков; TLS-деструкторы; fork+resurrect; txn_clone; парковка/вытеснение; несколько сред; MDBX_EXCLUSIVE.
  • Гл. 12. Обработка ошибок — положительные/отрицательные коды; RESULT_TRUE/FALSE; strerror_r vs strerror; MAP_FULL/TXN_FULL; ожидаемые коды (KEYEXIST/NOTFOUND); BAD_TXN/BAD_DBI/EBADSIGN; WANNA_RECOVERY/MVCC_RETARDED; THREAD_MISMATCH/TXN_OVERLAPPING/BUSY; retry-стратегии.

Том III. Внутренние механизмы (для понимающих)

Цель: читатель объясняет поведение БД через архитектуру — мост между «как пользоваться» и «как настраивать/отлаживать». Объём ~100–200 страниц.

  • Гл. 13. Архитектура хранения: B+tree и mmap — ветви/листья/overflow; почему B+tree; страница; mmap без буферного кэша; CoW страницы; состояния страницы; инвариант достижимости.
  • Гл. 14. MVCC и снапшоты — версионность страниц; тройка мета-страниц (Troika), двухфазный коммит, конечный автомат 216 состояний; RLT; wait-free чтение; safe64; писатель (мьютекс, front txnid, DPL); сравнение с PostgreSQL/Oracle.
  • Гл. 15. Copy-on-Write и конвейер коммита — touch→копия→DPL→спилл→коммит; дедупликация DPL; спилл (LRU, приоритет overflow, защита курсоров, знаменатели); loose; refund; стадии конвейера (GC→refund→спилл→аудит→мета→sync→разблокировка) и влияние на задержку.
  • Гл. 16. GC — почему не free-list; формат записей (ключ=txnid, значение=PNL); детент и его вычисление/кэширование; FIFO vs LIFO; BigFoot; рекурсивность обновления; rp_augment_limit/ gc_time_limit; ранняя очистка GC 2025; не-отложенная очистка (devel 0.14.x).
  • Гл. 17. Рост, сжатие и дефрагментация — почему растёт (читатели/SAFE_NOSYNC/фрагментация); геометрия; MAP_FULL и разрешающие меры (steady-point/HSR/выселение); авто-компактификация refund и её пределы; mdbx_env_defrag; гистерезис; оценка ёмкости.
  • Гл. 18. Вложенные транзакции — назначение; CoW-тень родителя, спаренные курсоры; join vs undo; судьба таблиц; анти-паттерн «вложенная в каждой функции»; workaround нехватки места; совместимость с WRITEMAP.
  • Гл. 19. Файл блокировок и межпроцессная синхронизация — зачем LCK; реализации (POSIX-2008/2001, SysV, WIN32FILES), почему LockFileEx, а не именованные мьютексы; версионирование LCK; восстановление после сбоя; reader_check; режим без LCK.
  • Гл. 20. Долговечность и восстановление — two-phase мета (weak/steady); восстановление без WAL; open for recovery (монотонные номера, эксклюзив); boot_id и LXC; некогерентность page cache (#269, FORCE_CHECK_MMAP_COHERENCY); mdbx_chk; что переживёт сбой питания по режимам.

Том IV. Производительность и оптимизация (для опытных)

Цель: читатель настраивает libmdbx под сценарий, находит и устраняет узкие места. Объём ~80–150 страниц.

  • Гл. 21. WAF — что и почему; источники амплификации; батчинг как главный рычаг; высота дерева; спилл-компромисс; prefer_waf_insteadof_balance/merge_threshold; расчёт WAF с числами.
  • Гл. 22. Выбор конфигурации под сценарий — 6 сценариев (запись-heavy, чтение-heavy, мобильное, аналитика, многопроцессное чтение, низкая задержка): режимы/флаги/геометрия/страница/батчинг/числа.
  • Гл. 23. Микрооптимизации — SIMD-поиск, branchless bsearch, radix-sort, атомики для слабых моделей, минимизация syscall, prefault+mincore, auto-appending split, merge с грязным соседом; когда важны.
  • Гл. 24. Кэш-поиск (get-cached) — понятие, статусы HIT/CONFIRMED/REFRESHED/DIRTY/BEHIND/UNABLE/RACE; когда ускоряет; ABA; многопоточный вариант + NOSTICKYTHREADS; SingleThreaded vs multithreaded; история (Gabriel RABHI, Ghost Body Object).
  • Гл. 25. Массовые операции — bunch_delete, get_batch, GET/PUT_MULTIPLE, estimate_range/distance/move, txn_clone, батчинг 100–10000 операций; когда «максимальная транзакция» — анти-паттерн.
  • Гл. 26. Бенчмарки и измерения — ioarena; что измерять; commit_latency по стадиям; PROFGC; типичные ошибки бенчмаркинга; «6–7× медленнее LMDB» — что это значит; ориентиры (200 TPS, 1–3M get/s, 20K–10M вставок/с); масштабирование чтения.

Том V. Экспертные темы и edge cases (для продвинутых)

Цель: читатель знает тонкости и грабли, умеет отлаживать и принимать архитектурные решения. Объём ~100–200 страниц.

  • Гл. 27. Правила и советы — проверенные практики и «грабли», контекст критичности, контрпримеры.
  • Гл. 28. Платформенные нюансы — Linux (boot_id, /proc, /dev/shm, tmpfs/ENOSPC, page cache, mincore); Windows (LockFileEx, LARGEADDRESSAWARE, 2G/4G, WSL1/2); macOS/iOS (F_FULLFSYNC, APPLE_SPEED_INSTEADOF_DURABILITY, F_PREALLOCATE); Android/bionic; контейнеры (LXC/Docker); Wine; Linux <4.x; tmpfs.
  • Гл. 29. Handle-Slow-Readers (HSR) — зачем; mdbx_env_set_hsr; параметры и возвраты (ждать/убить/рост/MAP_FULL); типовые реализации; HSR + SAFE_NOSYNC; пример на C.
  • Гл. 30. Диагностика и отладка — инструменты (mdbx_chk опции и exit-коды, PROFGC и семантика gc_prof, commit_latency по стадиям, txn_info, reader_check/list, логирование, ASAN/UBSAN/valgrind); пошаговые сценарии (рост БД, тормоз коммита, MAP_FULL, deadlock/ BUSY, долгий читатель, повреждение, утечка слотов, производительность, фрагментация, fork, Windows-тормоза, контейнеры); чек-листы перед production.
  • Гл. 31. Миграция с LMDB — преимущества; совместимость форматов (0.11.x ↔ 0.12.x); breaking changes (NOLOCK убран, NOTLS → NOSTICKYTHREADS); таблица соответствия mdb_ → mdbx_; поведенческие отличия (троика мет, двухфазный коммит, контрольные суммы); чек-лист миграции.
  • Гл. 32. Паттерны проектирования — 8 паттернов (auto-ID через sequence, вторичный индекс DUPSORT, составной ключ+компаратор, очередь задач table-as-queue, кольцевой буфер, полносканирующий итератор, репликация через per-table txnid, read-your-writes через clone/ embark_read): задача → решение с кодом → компромиссы → альтернативы.
  • Гл. 33. Roadmap и будущее: MithrilDB — текущее состояние; общий API нескольких форматов; амальгамация; репликация (нелинейная GC); подписка на изменения; шифрование/сжатие; потоковые BLOB; SWIG.

Том VI. Привязки (bindings)

Цель: читатель использует libmdbx из своего языка с пониманием специфики и ограничений биндинга. Объём ~50–150 страниц.

  • Гл. 34. Обзор экосистемы — полный список официально отслеживаемых биндингов; статусы (зрелый/экспериментальный/устаревший); карта «язык → биндинг».
  • Гл. 35–46. Карточки биндингов (по единому шаблону: обзор/установка/базовый пример/ threading/память/нюансы/типовые ошибки/производительность/пробелы/ссылки): 35 Rust (mdbx-sys/mdbx-rs), 36 Go (mdbx-go), 37 Python (python-lmdbx/mdbx-py), 38 Node.js (node-mdbx), 39 .NET/C# (libmdbx-dotnet), 40 C++ (mdbx.h++), 41 Dart (mdbx-dart), 42 Nim, 43 Java, 44 Haskell, 45 Ruby, 46 Scala. Zig (официально отслеживаемый) — краткая справка в гл. 34 (§34.2), без отдельной карточки.
  • Обязательные нюансы: Go+NOSTICKYTHREADS (deadlock-сценарии, CGO); Rust+async (Send/Sync, use-after-free после commit, блокирующие вызовы); .NET+GC (SafeHandle, pinning, время жизни); Python+GIL (долгие чтения, fork после import).
  • Честность: при недостатке данных — «требует анализа репозитория биндинга».