libmdbx/README.md

libmdbx
======================================
Extended LMDB, aka "Расширенная LMDB".

*The Future will Positive. Всё будет хорошо.*

[![Build Status](https://travis-ci.org/ReOpen/libmdbx.svg?branch=devel)](https://travis-ci.org/ReOpen/libmdbx)

English version by Google [is
here](https://translate.googleusercontent.com/translate_c?act=url&depth=1&hl=ru&ie=UTF8&prev=_t&rurl=translate.google.com&sl=ru&tl=en&u=https://github.com/ReOpen/libmdbx/tree/devel).

## Кратко
libmdbx - это встраиваемый key-value движок хранения со специфическим
набором возможностей, которые при правильном применении позволяют создавать
уникальные решения с чемпионской производительностью.

libmdbx является форком [Symas Lightning Memory-Mapped
Database](https://symas.com/products/lightning-memory-mapped-database/)
(известной под аббревиатурой
[LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database)), с
рядом существенных доработок, которые перечислены ниже.

Изначально модификация производилась в составе исходного кода проекта
[ReOpenLDAP](https://github.com/ReOpen/ReOpenLDAP). Примерно за год работы
внесенные изменения приобрели самостоятельную ценность.

Осенью 2015 доработанный движок был выделен в отдельный проект, который был
[представлен на конференции Highload++
2015](http://www.highload.ru/2015/abstracts/1831.html).


## Характеристики и ключевые особенности

### Общее для оригинальной LMDB и MDBX

* Данные хранятся в упорядоченном отображении (ordered map), ключи всегда
  отсортированы, поддерживается выборка диапазонов (range lookups).

* Транзакции согласно [ACID](https://ru.wikipedia.org/wiki/ACID), посредством
  [MVCC](https://ru.wikipedia.org/wiki/MVCC)
  и [COW](https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BF%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_%D0%BF%D1%80%D0%B8_%D0%B7%D0%B0%D0%BF%D0%B8%D1%81%D0%B8).

* Чтение [без
  блокировок](https://ru.wikipedia.org/wiki/%D0%9D%D0%B5%D0%B1%D0%BB%D0%BE%D0%BA%D0%B8%D1%80%D1%83%D1%8E%D1%89%D0%B0%D1%8F_%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F),
  без [атомарных операций](https://ru.wikipedia.org/wiki/%D0%90%D1%82%D0%BE%D0%BC%D0%B0%D1%80%D0%BD%D0%B0%D1%8F_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D1%8F).
  Мьютексы захватываются только при старте и завершении сеанса работы с БД.

* Читатели не конкурируют между собой, чтение масштабируется линейно по ядрам CPU.

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

* Амортизационная стоимость любой операции Olog(N),
  [WAF](https://en.wikipedia.org/wiki/Write_amplification) и RAF также Olog(N).

* Нет [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging) и журнала
  транзакций, после сбоев не требуется восстановление.

* Не требуется компактификация или какое-либо периодическое обслуживание.

* Эффективное хранение дубликатов (ключей с несколькими значениями) с
  сортировкой значений.

* Эффективная поддержка ключей фиксированной длины (uint32_t, uint64_t).

* Поддержка горячего резервного копирования.

* Файл БД отображается в память кажлого процесса, который работает с БД. К
  ключам и данным обеспечивается прямой доступ (без копирования), они не
  меняются до завершения транзакции чтения.

* Отсутствует какое-либо внутреннее управление памятью или кэшированием. Всё
  необходимое выполняет ядро ОС.


### Недостатки и Компромиссы

1. Единовременно может выполняться не более одной транзакция изменения данных
   (один писатель). Зато все изменения всегда последовательны, не может быть
   конфликтов или ошибок при откате транзакций.

2. Отсутствие [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging)
   обуславливает относительно большой
   [WAF](https://en.wikipedia.org/wiki/Write_amplification). Поэтому фиксация
   изменений на диске относительно дорога и является главным ограничителем для
   производительности по записи. В качестве компромисса предлагается несколько
   режимов ленивой и/или периодической фиксации. В том числе режим `WRITEMAP`,
   при котором изменения происходят только в памяти и асинхронно фиксируются на
   диске ядром ОС.

3. [COW](https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BF%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_%D0%BF%D1%80%D0%B8_%D0%B7%D0%B0%D0%BF%D0%B8%D1%81%D0%B8)
   для реализации [MVCC](https://ru.wikipedia.org/wiki/MVCC) выполняется на
   уровне страниц в [B+ дереве](https://ru.wikipedia.org/wiki/B-%D0%B4%D0%B5%D1%80%D0%B5%D0%B2%D0%BE).
   Поэтому изменение данных амортизационно требует копирования Olog(N) страниц,
   что расходует [пропускную способность оперативной
   памяти](https://en.wikipedia.org/wiki/Memory_bandwidth) и является основным
   ограничителем производительности в режиме `WRITEMAP`.

4. Проблема долгих чтений (зависших читателей), см. ниже.

5. Вероятность разрушения БД в режиме `WRITEMAP`, см ниже.


#### Проблема долгих чтений

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

* Изменение данных на фоне долгой операции чтения может приводить к исчерпанию
  места в БД.

* После чего любая попытка обновить данные будет приводить к ошибке `MAP_FULL`
  до завершения долгой операции чтения.

* Характерными примерами долгих чтений являются горячее резервное копирования
  и отладка клиентского приложения при активной транзакции чтения.

* В оригинальной LMDB после этого будет наблюдаться устойчивая деградация
  производительности всех механизмов обратной записи на диск (в I/O контроллере,
  в гипервизоре, в ядре ОС).

* В MDBX предусмотрен механизм аварийного прерывания таких операций, а также
  режим `LIFO RECLAIM` устраняющий последующую деградацию производительности.

Операции чтения выполняются в контексте снимка данных (версии БД), который был
актуальным на момент старта транзакции чтения. Такой читаемый снимок
поддерживается неизменным до завершения операции. В свою очередь, это не
позволяет повторно использовать страницы БД в последующих версиях (снимках
БД).

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

В результате, при интенсивном изменении данных и достаточно длительной
операции чтения, в БД могут быть исчерпаны свободные страницы, что не позволит
создавать новые снимки/версии БД. Такая ситуация будет сохраняться до
завершения операции чтения, которая использует старый снимок данных и
препятствует повторному использованию страниц БД.

Однако, на этом проблемы не заканчиваются. После описанной ситуации, все
дополнительные страницы, которые были выделены пока переработка старых была
невозможна, будут участвовать в цикле выделения/освобождения до конца жизни
экземпляра БД. В оригинальной LMDB этот цикл использования страниц работает по
принципу [FIFO](https://ru.wikipedia.org/wiki/FIFO). Поэтому увеличение
количества циркулирующий страниц, с точки зрения механизмов кэширования и/или
обратной записи, выглядит как увеличение рабочего набор данных. Проще говоря,
однократное попадание в ситуацию "уснувшего читателя" приводит к устойчивому
эффекту вымывания I/O кэша при всех последующих изменениях данных.

Для решения описанных проблемы в MDBX сделаны существенные доработки, см.
ниже. Иллюстрации к проблеме "долгих чтений" можно найти в [слайдах
презентации](http://www.slideshare.net/leoyuriev/lmdb). Там же приведен пример
количественной оценки прироста производительности за счет эффективной работы
[BBWC](https://en.wikipedia.org/wiki/BBWC) при включении `LIFO RECLAIM` в
MDBX.


## Доработки MDBX

1. Режим `LIFO RECLAIM`.

    Для повторного использования выбираются не самые старые, а самые новые
    страницы из доступных. За счет этого цикл использования страниц всегда
    имеет минимальную длину и не зависит от общего числа выделенных страниц.

    В результате механизмы кэширования и обратной записи работают с
    максимально возможной эффективностью. В случае использования контроллера
    дисков или системы хранения с [BBWC](https://en.wikipedia.org/wiki/BBWC)
    возможно многократное увеличение производительности по записи
    (обновлению данных).

2. Обработчик `OOM-KICK`.

    Посредством `mdbx_env_set_oomfunc()` может быть
    установлен внешний обработчик (callback), который будет вызван при исчерпания
    свободных страниц из-за долгой операцией чтения. Обработчику будет передан PID
    и pthread_id. В свою очередь обработчик может предпринять одно из действий:

   * отправить сигнал kill (#9), если долгое чтение выполняется сторонним процессом;
   * отменить или перезапустить проблемную операцию чтения, если операция
     выполняется одним из потоков текущего процесса;
   * подождать некоторое время, в расчете что проблемная операция чтения будет
     штатно завершена;
   * перервать текущую операцию изменения данных с возвратом кода ошибки.

3. Гарантия сохранности БД в режиме `WRITEMAP`.

    При работе в режиме `WRITEMAP` запись измененных страниц выполняется ядром ОС,
    что имеет ряд преимуществ. Так например, при крахе приложения, ядро ОС
    сохранит все изменения.

    Однако, при аварийном отключении питания или сбое в ядре ОС, на диске будет
    сохранена только часть измененных страниц БД. При этом с большой вероятностью
    может оказаться так, что будут сохранены мета-страницы со ссылками на страницы
    с новыми версиями данных, но не сами новые данные. В этом случае БД будет
    безвозвратна разрушена, даже если до аварии производилась полная синхронизация
    данных (посредством `mdb_env_sync()`).

    В MDBX эта проблема решена путем полной переработки пути записи данных:

     * В режиме `WRITEMAP` MDBX не обновляет мета-страницы непосредственно,
       а поддерживает их теневые копии с переносом изменений после фиксации
       данных.

     * При завершении транзакций, в зависимости от состояния
       синхронности данных между диском и оперативной память, MDBX помечает
       точки фиксации либо как сильные (strong), либо как слабые (weak). Так
       например, в режиме `WRITEMAP` завершаемые транзакции помечаются как
       слабые, а при явной синхронизации данных как сильные.

     * При открытии БД
       выполняется автоматический откат к последней сильной фиксации. Этим
       обеспечивается гарантия сохранности БД.

    К сожалению, такая гарантия надежности не дается бесплатно. Для сохранности
    данных, страницы формирующие крайний снимок с сильной фиксацией, не должны
    повторно использоваться (перезаписываться) до формирования следующей сильной
    точки фиксации. Таким образом, крайняя точки фиксации создает описанный выше
    эффект "долгого чтения", с разницей в том, что при исчерпании свободных
    страниц автоматически будет сформирована новая точка сильной фиксации.

    В последующих версиях MDBX будут предусмотрены средства для асинхронной записи
    данных на диск с формированием сильных точек фиксации.

4. Возможность автоматического формирования контрольных точек (сброса данных
на диск) при накоплении заданного объёма изменений, устанавливаемого функцией
`mdbx_env_set_syncbytes()`.

5. Возможность получить отставание текущей транзакции чтения от последней
версии данных в БД посредством `mdbx_txn_straggler()`.

6. Утилита mdbx_chk для проверки БД и функция `mdbx_env_pgwalk()` для обхода
всех страниц БД.

7. Управление отладкой и получение отладочных сообщений посредством
`mdbx_setup_debug()`.

8. Возможность связать с каждой завершаемой транзакцией до 3 дополнительных
маркеров посредством `mdbx_canary_put()`, и прочитать их в транзакции чтения
посредством `mdbx_canary_get()`.

9. Возможность узнать есть ли за текущей позицией курсора строка данных
посредством `mdbx_cursor_eof()`.

10. Возможность явно запросить обновление существующей записи, без создания
новой посредством флажка `MDB_CURRENT` для `mdb_put()`.

11. Возможность обновить или удалить запись с получением предыдущего значения
данных посредством `mdbx_replace()`.

12. Поддержка ключей нулевого размера.

13. Исправленный вариант `mdb_cursor_count()`, возвращающий корректное
количество дубликатов для всех типов таблиц и любого положения курсора.

14. Возможность открыть БД в эксклюзивном режиме посредством
`mdbx_env_open_ex()`, например в целях её проверки.

15. Возможность закрыть БД в "грязном" состоянии (без сброса данных и
формирования сильной точки фиксации) посредством `mdbx_env_close_ex()`.

16. Возможность получить посредством `mdbx_env_info()` дополнительную
информацию, включая номер самой старой версии БД (снимка данных), который
используется одним из читателей.