Introduction 引言

LMDB is a Btree-based database management library modeled loosely on the BerkeleyDB API, but much simplified. The entire database is exposed in a memory map, and all data fetches return data directly from the mapped memory, so no malloc's or memcpy's occur during data fetches. As such, the library is extremely simple because it requires no page caching layer of its own, and it is extremely high performance and memory-efficient. It is also fully transactional with full ACID semantics, and when the memory map is read-only, the database integrity cannot be corrupted by stray pointer writes from application code.
LMDB 是一个基于 B 树的数据库管理库，其模型大致基于 BerkeleyDB API，但进行了大幅简化。整个数据库以内存映射的形式暴露出来，所有数据获取都是直接从映射内存中返回数据，因此在数据获取过程中不会发生 malloc 或 memcpy 操作。因此，该库非常简单，因为它不需要自己的页面缓存层，同时具有极高的性能和内存效率。它还具有完全的事务性，具备完整的 ACID 语义，并且当内存映射为只读时，数据库完整性不会被应用程序代码中的随机指针写入所破坏。

The library is fully thread-aware and supports concurrent read/write access from multiple processes and threads. Data pages use a copy-on- write strategy so no active data pages are ever overwritten, which also provides resistance to corruption and eliminates the need of any special recovery procedures after a system crash. Writes are fully serialized; only one write transaction may be active at a time, which guarantees that writers can never deadlock. The database structure is multi-versioned so readers run with no locks; writers cannot block readers, and readers don't block writers.
该库是完全线程感知的，并支持从多个进程和线程进行并发读/写访问。数据页使用写时复制策略，因此不会覆盖任何活动数据页，这也提供了对损坏的抵抗力，并消除了系统崩溃后需要任何特殊恢复程序的需求。写入是完全序列化的；任何时候只能有一个写事务处于活动状态，这保证了写入者永远不会死锁。数据库结构是多版本的，因此读取器在不加锁的情况下运行；写入者不会阻塞读取者，读取者也不会阻塞写入者。

Unlike other well-known database mechanisms which use either write-ahead transaction logs or append-only data writes, LMDB requires no maintenance during operation. Both write-ahead loggers and append-only databases require periodic checkpointing and/or compaction of their log or database files otherwise they grow without bound. LMDB tracks free pages within the database and re-uses them for new write operations, so the database size does not grow without bound in normal use.
与使用预写事务日志或仅追加数据写入的其他知名数据库机制不同，LMDB 在操作期间不需要维护。预写日志器和仅追加数据库都需要定期检查点和/或压缩其日志或数据库文件，否则它们会无限增长，而 LMDB 跟踪数据库内的空闲页并将其重新用于新的写操作，因此数据库大小在正常使用中不会无限增长。

The memory map can be used as a read-only or read-write map. It is read-only by default as this provides total immunity to corruption. Using read-write mode offers much higher write performance, but adds the possibility for stray application writes thru pointers to silently corrupt the database. Of course if your application code is known to be bug-free (...) then this is not an issue.
翻译文本开始：

If this is your first time using a transactional embedded key/value store, you may find the Getting Started page to be helpful.
内存映射可以用作只读或读写映射。它默认是只读的，这样可以完全免疫于损坏。使用读写模式提供了更高的写入性能，但增加了通过指针的意外应用程序写入可能会无声地破坏数据库的可能性。当然，如果你的应用程序代码已知是无错误的（...），那么这不是一个问题。

Caveats 如果你是第一次使用事务性嵌入式键值存储，你可能会发现“入门”页面很有帮助。

Troubleshooting the lock file, plus semaphores on BSD systems:
解决锁定文件问题，以及 BSD 系统上的信号量：

A broken lockfile can cause sync issues. Stale reader transactions left behind by an aborted program cause further writes to grow the database quickly, and stale locks can block further operation.
损坏的锁定文件可能导致同步问题。被中止的程序遗留的陈旧读取事务会导致进一步的写入迅速扩大数据库，而陈旧的锁定可能会阻止进一步的操作。

Fix: Check for stale readers periodically, using the mdb_reader_check function or the mdb_stat tool. Stale writers will be cleared automatically on some systems:
修复方法：定期检查陈旧的读取者，使用 mdb_reader_check 函数或 mdb_stat 工具。在某些系统上，陈旧的写入者将自动被清除：
- Windows - automatic 视窗 - 自动
- Linux, systems using POSIX mutexes with Robust option - automatic
  Linux，使用具有鲁棒选项的 POSIX 互斥锁的系统 - 自动
- not on BSD, systems using POSIX semaphores. Otherwise just make all programs using the database close it; the lockfile is always reset on first open of the environment.
  不在 BSD 上，使用 POSIX 信号量的系统。否则，只需让所有使用数据库的程序关闭它；锁定文件总是在环境首次打开时重置。请注意，翻译时尽量保持了原文的结构和术语的准确性，但某些技术术语可能没有完全对应的中文术语，因此保留了英文原文。

On BSD systems or others configured with MDB_USE_POSIX_SEM, startup can fail due to semaphores owned by another userid.
翻译文本开始：

Fix: Open and close the database as the user which owns the semaphores (likely last user) or as root, while no other process is using the database.
在 BSD 系统或其他配置了 MDB_USE_POSIX_SEM 的系统上，启动可能会因为属于另一个用户 ID 的信号量而失败。

Restrictions/caveats (in addition to those listed for some functions):
修复方法：以拥有信号量的用户（可能是最后一个用户）或以 root 身份打开和关闭数据库，同时没有其他进程正在使用该数据库。

Only the database owner should normally use the database on BSD systems or when otherwise configured with MDB_USE_POSIX_SEM. Multiple users can cause startup to fail later, as noted above.
翻译文本开始：

There is normally no pure read-only mode, since readers need write access to locks and lock file. Exceptions: On read-only filesystems or with the MDB_NOLOCK flag described under mdb_env_open().
通常只有数据库所有者应该在 BSD 系统上或以其他方式配置了 MDB_USE_POSIX_SEM 的情况下使用数据库。多个用户可能会导致后续启动失败，如上所述。

By default, in versions before 0.9.10, unused portions of the data file might receive garbage data from memory freed by other code. (This does not happen when using the MDB_WRITEMAP flag.) As of 0.9.10 the default behavior is to initialize such memory before writing to the data file. Since there may be a slight performance cost due to this initialization, applications may disable it using the MDB_NOMEMINIT flag. Applications handling sensitive data which must not be written should not use this flag. This flag is irrelevant when using MDB_WRITEMAP.
通常没有纯粹的只读模式，因为读者需要对锁和锁文件进行写访问。例外情况：在只读文件系统上或使用 mdb_env_open()下描述的 MDB_NOLOCK 标志。

A thread can only use one transaction at a time, plus any child transactions. Each transaction belongs to one thread. See below. The MDB_NOTLS flag changes this for read-only transactions.
翻译开始：

Use an MDB_env* in the process which opened it, without fork()ing.
一个线程一次只能使用一个事务，加上任何子事务。每个事务都属于一个线程。请参见下文。MDB_NOTLS 标志为只读事务改变了这一点。

Do not have open an LMDB database twice in the same process at the same time. Not even from a plain open() call - close()ing it breaks flock() advisory locking.
在打开它的进程中使用 MDB_env*，不要使用 fork()。

Avoid long-lived transactions. Read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. Write transactions prevent other write transactions, since writes are serialized.
翻译文本开始：

Avoid suspending a process with active transactions. These would then be "long-lived" as above. Also read transactions suspended when writers commit could sometimes see wrong data.
避免长时间运行的交易。读取交易会阻止新写入交易释放的页面被重用，因此数据库可能会迅速增长。写入交易会阻止其他写入交易，因为写入是按顺序进行的。

...when several processes can use a database concurrently:
避免在有活动交易的情况下挂起进程。这些交易随后会像上面所说的那样成为“长时间运行”的。此外，当写入者提交时挂起的读取交易有时可能会看到错误的数据。

Avoid aborting a process with an active transaction. The transaction becomes "long-lived" as above until a check for stale readers is performed or the lockfile is reset, since the process may not remove it from the lockfile.
避免在有活动事务的情况下终止一个进程。由于进程可能不会从锁定文件中移除它，事务会像上面所说的那样变成“长期存在”的，直到执行了对过时读者的检查或锁定文件被重置。

This does not apply to write transactions if the system clears stale writers, see above.
如果系统清除了过时的写入者，如上所述，这不适用于写入事务。

If you do that anyway, do a periodic check for stale readers. Or close the environment once in a while, so the lockfile can get reset.
如果你无论如何都要这样做，请定期检查过时的读者。或者偶尔关闭环境，以便锁定文件可以被重置。翻译完成。

Do not use LMDB databases on remote filesystems, even between processes on the same host. This breaks flock() on some OSes, possibly memory map sync, and certainly sync between programs on different hosts.

Opening a database can fail if another process is opening or closing it at exactly the same time.

Author: Howard Chu, Symas Corporation.
霍华德·楚，Symas 公司。

Redistribution and use in source and binary forms, with or without modification, are permitted only as authorized by the OpenLDAP Public License.
仅在获得 OpenLDAP 公共许可证授权的情况下，才允许以源代码和二进制形式重新分发和使用，无论是否经过修改。

A copy of this license is available in the file LICENSE in the top-level directory of the distribution or, alternatively, at http://www.OpenLDAP.org/license.html.
本许可证的副本可在分发顶层目录中的文件 LICENSE 中找到，或者，也可在 http://www.OpenLDAP.org/license.html 上查看。

Derived From: 源自于：: This code is derived from btree.c written by Martin Hedenfalk.
此代码源自 Martin Hedenfalk 编写的 btree.c。

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
本软件的使用、复制、修改和分发权，无论是否收费，均在此授予，但前提是必须保留上述版权声明和本许可声明，并将其包含在所有副本中。

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
本软件按“原样”提供，作者不提供任何形式的保证，包括所有隐含的适销性和适用性保证。在任何情况下，作者均不对任何特殊、直接、间接或后果性损害或任何因使用、数据或利润损失而导致的任何损害负责，无论是在合同行为、疏忽或其他侵权行为中，均由本软件的使用或性能引起。