Xlong：创建页面，内容为“=== 介绍 === DBDB（狗床数据库）是一个 Python 库，它实现了一个简单的键值数据库。它允许你将一个键与一个值关联起来，并将这种关联存储在磁盘上以便以后检索。 DBDB 旨在计算机崩溃和错误情况下保存数据。它还避免一次性将所有数据都加载到 RAM 中，因此您可以存储比 RAM 容量更多的数据。 === DBDB数据库架构 === DBDB数据库将内容放在磁盘上的某个…”

2025-12-24T07:19:58Z

创建页面，内容为“=== 介绍 === DBDB（狗床数据库）是一个 Python 库，它实现了一个简单的键值数据库。它允许你将一个键与一个值关联起来，并将这种关联存储在磁盘上以便以后检索。 DBDB 旨在计算机崩溃和错误情况下保存数据。它还避免一次性将所有数据都加载到 RAM 中，因此您可以存储比 RAM 容量更多的数据。 === DBDB数据库架构 === DBDB数据库将内容放在磁盘上的某个…”

新页面

=== 介绍 ===
DBDB（狗床数据库）是一个 Python 库，它实现了一个简单的键值数据库。它允许你将一个键与一个值关联起来，并将这种关联存储在磁盘上以便以后检索。

DBDB 旨在计算机崩溃和错误情况下保存数据。它还避免一次性将所有数据都加载到 RAM 中，因此您可以存储比 RAM 容量更多的数据。

=== DBDB数据库架构 ===
DBDB数据库将内容放在磁盘上的某个地方（数据在文件中的布局方式；物理层）与数据的逻辑结构（本例中为二叉树；逻辑层）以及键值存储的内容（键 <code>a</code> 与值 <code>foo</code> 的关联；公共 API）分开。

许多数据库将逻辑方面和物理方面分开，因为提供每种方面的替代实现以获得不同的性能特征通常很有用，例如 DB2 的 SMS（文件系统中的文件）与 DMS（原始块设备）表空间，或者 MySQL 的替代引擎实现。

=== 探索设计 ===
本文的大部分章节都描述了程序从构思到完成的整个构建过程。然而，这并非我们大多数人与代码交互的方式。我们通常会发现别人编写的代码，然后想办法修改或扩展它，使其实现不同的功能。

在本章中，我们将假设 DBDB 是一个已完成的项目，并逐步讲解它的工作原理。首先，让我们来了解一下整个项目的结构。

=== 组织结构 ===

* <code>tool.py</code> 定义了一个命令行工具，用于从终端窗口浏览数据库。
* <code>interface.py</code> 定义了一个类 ( <code>DBDB</code> )，该类使用具体的 <code>BinaryTree</code> 实现来实现 Python 字典 API。这就是在 Python 程序中使用 DBDB 的方法。
* <code>logical.py</code> 定义了逻辑层。它是一个键值存储的抽象接口。
** <code>LogicalBase</code> 提供逻辑更新（例如 get、set 和 commit） API，并将更新的具体实现委托给具体的子类。它还管理存储锁定和内部节点的解引用。
** <code>ValueRef</code> 是一个 Python 对象，它指向数据库中存储的二进制数据块。这种间接方式使我们能够避免一次性将整个数据存储加载到内存中。
* <code>binary_tree.py</code> 在逻辑接口底层定义了一个具体的二叉树算法。
** <code>BinaryTree</code> 提供了二叉树的具体实现，并提供了获取、插入和删除键值对的方法。BinaryTree 代表一棵不可变树；更新操作会返回一棵与原树结构相同的新树。
** <code>BinaryNode</code> 实现了二叉树中的一个节点。
** <code>BinaryNodeRef</code> 是一个特殊的 <code>ValueRef</code> ，它知道如何序列化和反序列化 <code>BinaryNode</code> 。
* <code>physical.py</code> 定义了物理层。Storage提供持久化（主要是）仅追加记录存储。

这些模块的出现源于让每个类只承担单一职责的尝试。换句话说，每个类应该只有一个修改的理由。

=== 读数据 ===
我们先从最简单的例子开始：从数据库中读取一个值。让我们看看当我们尝试获取 <code>example.db</code> 中键为 <code>foo</code> 值时会发生什么：
<code>$ python -m dbdb.tool example.db get foo</code>
这会运行模块 <code>dbdb.tool</code> 中的 <code>main()</code> 函数：<syntaxhighlight lang="python3" line="1">
# dbdb/tool.py
def main(argv):
if not (4 <= len(argv) <= 5):
usage()
return BAD_ARGS
dbname, verb, key, value = (argv[1:] + [None])[:4]
if verb not in {'get', 'set', 'delete'}:
usage()
return BAD_VERB
db = dbdb.connect(dbname) # CONNECT
try:
if verb == 'get':
sys.stdout.write(db[key]) # GET VALUE
elif verb == 'set':
db[key] = value
db.commit()
else:
del db[key]
db.commit()
except KeyError:
print("Key not found", file=sys.stderr)
return BAD_KEY
return OK
</syntaxhighlight><code>connect()</code> 函数打开数据库文件（可能会创建该文件，但绝不会覆盖它），并返回一个 <code>DBDB</code> 实例：<syntaxhighlight lang="python3" line="1">
# dbdb/__init__.py
def connect(dbname):
try:
f = open(dbname, 'r+b')
except IOError:
fd = os.open(dbname, os.O_RDWR | os.O_CREAT)
f = os.fdopen(fd, 'r+b')
return DBDB(f)

# dbdb/interface.py
class DBDB(object):

def __init__(self, f):
self._storage = Storage(f)
self._tree = BinaryTree(self._storage)
</syntaxhighlight>我们立刻发现 <code>DBDB</code> 引用了 <code>Storage</code> 的一个实例，但它也与 <code>self._tree</code> 共享该引用。

在设计中，确定哪些对象“拥有”某个资源通常是一个重要的问题，因为它能提示我们哪些更改可能存在安全隐患。

一旦我们有了 DBDB 实例，获取 <code>key</code> 的值是通过字典查找 ( <code>db[key]</code> ) 完成的，这会导致 Python 解释器调用 <code>DBDB.__getitem__()</code> 。<syntaxhighlight lang="python3" line="1">
# dbdb/interface.py
class DBDB(object):
# ...
def __getitem__(self, key):
self._assert_not_closed()
return self._tree.get(key)

def _assert_not_closed(self):
if self._storage.closed:
raise ValueError('Database closed.')
</syntaxhighlight><code>__getitem__()</code> 通过调用 <code>_assert_not_closed</code> 来确保数据库仍然处于打开状态。这里我们至少找到了一个 <code>DBDB</code> 需要直接访问 <code>Storage</code> 实例的原因：它可以强制执行前提条件。

然后，DBDB 通过调用 <code>LogicalBase</code> 提供的 <code>_tree.get()</code> 方法来检索与内部 <code>_tree</code> 上的 <code>key</code> 关联的值：<syntaxhighlight lang="python3" line="1">
# dbdb/logical.py
class LogicalBase(object):
# ...
def get(self, key):
if not self._storage.locked:
self._refresh_tree_ref()
return self._get(self._follow(self._tree_ref), key)

def _refresh_tree_ref(self):
self._tree_ref = self.node_ref_class(
address=self._storage.get_root_address())
</syntaxhighlight><code>_refresh_tree_ref</code> 会将树的“视图”重置为磁盘上当前的数据，从而允许我们执行完全最新的读取操作。

如果在尝试读取数据时存储''被''锁定怎么办？这意味着其他进程可能正在修改我们想要读取的数据；我们的读取结果很可能与数据的当前状态不符。这通常被称为“脏读”。这种模式允许多个读取器访问数据而无需担心阻塞，但代价是数据略微过时。

现在，让我们来看看我们实际是如何获取数据的：<syntaxhighlight lang="python3" line="1">
# dbdb/binary_tree.py
class BinaryTree(LogicalBase):
# ...
def _get(self, node, key):
while node is not None:
if key < node.key:
node = self._follow(node.left_ref)
elif node.key < key:
node = self._follow(node.right_ref)
else:
return self._follow(node.value_ref)
raise KeyError
</syntaxhighlight>这是一个标准的二叉树搜索，通过节点引用进行查找。我们从 <code>BinaryTree</code> 文档中得知， <code>Node</code> ）和 <code>NodeRef</code> ）都是值对象：它们不可变，其内容永远不会改变。 <code>Node</code> 创建时会关联一个键和一个值，以及左子节点和右子节点。这些关联也永远不会改变。只有当根节点被替换时，整个 <code>BinaryTree</code> 的内容才会发生可见的变化。这意味着在执行搜索时，我们无需担心树的内容会发生变化。

一旦找到关联的值， <code>main()</code> 函数会将其写入 <code>stdout</code> ，而不添加任何额外的换行符，以完全保留用户的数据。

=== 插入和更新 ===
现在我们将 <code>example.db</code> 中键为 <code>foo</code> 的值设置为 <code>bar</code> ：
<code>$ python -m dbdb.tool example.db set foo bar</code>
同样，这段代码会运行 <code>dbdb.tool</code> 模块中的 <code>main()</code> 函数。由于我们之前已经见过这段代码，所以这里只重点介绍一下其中的关键部分：<syntaxhighlight lang="python3" line="1">
# dbdb/tool.py
def main(argv):
...
db = dbdb.connect(dbname) # CONNECT
try:
...
elif verb == 'set':
db[key] = value # SET VALUE
db.commit() # COMMIT
...
except KeyError:
...
</syntaxhighlight>这次我们使用 <code>db[key] = value</code> 来设置值，它会调用 <code>DBDB.__setitem__()</code> 。<syntaxhighlight lang="python3" line="1">
# dbdb/interface.py
class DBDB(object):
# ...
def __setitem__(self, key, value):
self._assert_not_closed()
return self._tree.set(key, value)
</syntaxhighlight><code>__setitem__</code> 确保数据库仍然打开，然后通过调用 <code>_tree.set()</code> 将 <code>key</code> 到 <code>value</code> 关联存储在内部 <code>_tree</code> 中。

<code>_tree.set()</code> 由 <code>LogicalBase</code> 提供：<syntaxhighlight lang="python3">
# dbdb/logical.py
class LogicalBase(object):
# ...
def set(self, key, value):
if self._storage.lock():
self._refresh_tree_ref()
self._tree_ref = self._insert(
self._follow(self._tree_ref), key, self.value_ref_class(value))
</syntaxhighlight><code>set()</code> 首先检查存储锁：<syntaxhighlight lang="python3" line="1">
# dbdb/storage.py
class Storage(object):
...
def lock(self):
if not self.locked:
portalocker.lock(self._f, portalocker.LOCK_EX)
self.locked = True
return True
else:
return False
</syntaxhighlight>这里有两点需要注意：

* 我们的锁是由名为 portalocker 的第三方文件锁定库提供的。
* <code>lock()</code> 如果数据库已被锁定则返回 <code>False</code> ，否则返回 <code>True</code> 。

回到 <code>_tree.set()</code> ，我们现在可以理解它最初为什么要检查 <code>lock()</code> 的返回值：这使我们能够调用 <code>_refresh_tree_ref</code> 获取最新的根节点引用，从而避免丢失自上次从磁盘刷新树以来其他进程所做的更新。然后，它会将根树节点替换为包含插入（或更新）的键/值对的新树。

插入或更新树不会改变任何节点，因为 <code>_insert()</code> 返回的是一棵新树。新树与原树共享未更改的部分，以节省内存和执行时间。很自然地，可以用递归的方式实现这一点：<syntaxhighlight lang="python3" line="1">
# dbdb/binary_tree.py
class BinaryTree(LogicalBase):
# ...
def _insert(self, node, key, value_ref):
if node is None:
new_node = BinaryNode(
self.node_ref_class(), key, value_ref, self.node_ref_class(), 1)
elif key < node.key:
new_node = BinaryNode.from_node(
node,
left_ref=self._insert(
self._follow(node.left_ref), key, value_ref))
elif node.key < key:
new_node = BinaryNode.from_node(
node,
right_ref=self._insert(
self._follow(node.right_ref), key, value_ref))
else:
new_node = BinaryNode.from_node(node, value_ref=value_ref)
return self.node_ref_class(referent=new_node)
</syntaxhighlight>注意我们总是返回一个新节点（用 <code>NodeRef</code> 包裹）。我们不是更新一个节点使其指向新的子树，而是创建一个新节点，该节点共享未更改的子树。这使得二叉树成为一种不可变数据结构。

您可能已经注意到这里有些奇怪：我们还没有对磁盘上的任何数据进行任何更改。我们所做的只是通过移动树节点来改变我们对磁盘数据的视图。

为了将这些更改实际写入磁盘，我们需要显式调用 <code>commit()</code> ，我们在本节开头在 <code>tool.py</code> 中看到的是 <code>set</code> 操作的第二部分。

提交操作包括将内存中的所有脏状态写入磁盘，然后保存树的新根节点的磁盘地址。

'''从 API 开始：'''<syntaxhighlight lang="python3" line="1">
# dbdb/interface.py
class DBDB(object):
# ...
def commit(self):
self._assert_not_closed()
self._tree.commit()

# dbdb/logical.py
class LogicalBase(object)
# ...
def commit(self):
self._tree_ref.store(self._storage)
self._storage.commit_root_address(self._tree_ref.address)

# dbdb/logical.py
class ValueRef(object):
# ...
def store(self, storage):
if self._referent is not None and not self._address:
self.prepare_to_store(storage)
self._address = storage.write(self.referent_to_string(self._referent))

# dbdb/binary_tree.py
class BinaryNodeRef(ValueRef):
def prepare_to_store(self, storage):
if self._referent:
self._referent.store_refs(storage)

</syntaxhighlight><code>_tree.commit()</code> 的实现来自 <code>LogicalBase</code> ：

所有 <code>NodeRef</code> 都知道如何通过首先请求其子节点使用 <code>prepare_to_store()</code> 进行序列化来将自身序列化到磁盘：

在这种情况下， <code>LogicalBase</code> 中的 <code>self._tree_ref</code> 实际上是一个 <code>BinaryNodeRef</code> （ <code>ValueRef</code> 的子类），因此 <code>prepare_to_store()</code> 的具体实现如上边代码所示：

相关 <code>BinaryNode</code> <code>_referent</code> 要求其引用存储自身：<syntaxhighlight lang="python3" line="1">
# dbdb/binary_tree.py
class BinaryNode(object):
# ...
def store_refs(self, storage):
self.value_ref.store(storage)
self.left_ref.store(storage)
self.right_ref.store(storage)
</syntaxhighlight>这会一直递归下去，直到找到任何有未写入更改的 <code>NodeRef</code> （例如 <code>_address</code> ）。

现在我们又回到了 <code>ValueRef</code> 的 <code>store</code> 方法中，调用栈的上一级函数。store <code>store()</code> 的最后一步是序列化这个节点并保存它的存储地址：<syntaxhighlight lang="python3">
# dbdb/logical.py
class ValueRef(object):
# ...
def store(self, storage):
if self._referent is not None and not self._address:
self.prepare_to_store(storage)
self._address = storage.write(self.referent_to_string(self._referent))
</syntaxhighlight>此时， <code>NodeRef</code> 的 <code>_referent</code> 保证拥有其所有引用的可用地址，因此我们通过创建一个表示此节点的字节串来对其进行序列化：<syntaxhighlight lang="python3" line="1">
# dbdb/binary_tree.py
class BinaryNodeRef(ValueRef):
# ...
@staticmethod
def referent_to_string(referent):
return pickle.dumps({
'left': referent.left_ref.address,
'key': referent.key,
'value': referent.value_ref.address,
'right': referent.right_ref.address,
'length': referent.length,
})
</syntaxhighlight>在 <code>store()</code> 方法中更新地址，从技术上讲是对 <code>ValueRef</code> 的修改。由于它不会影响用户可见的值，因此我们可以认为它是不可变的。

当对根 <code>_tree_ref</code> 的 <code>store()</code> 操作完成（在 <code>LogicalBase.commit()</code> 中）后，我们就知道所有数据都已写入磁盘。现在我们可以通过调用以下方法提交根地址：<syntaxhighlight lang="python3">
# dbdb/physical.py
class Storage(object):
# ...
def commit_root_address(self, root_address):
self.lock()
self._f.flush()
self._seek_superblock()
self._write_integer(root_address)
self._f.flush()
self.unlock()
</syntaxhighlight>我们确保文件句柄被刷新（以便操作系统知道我们希望将所有数据保存到像固态硬盘这样的稳定存储设备上），并写入根节点的地址。我们知道最后一次写入是原子性的，因为我们将磁盘地址存储在扇区边界上。它是文件中的第一个元素，因此无论扇区大小如何，这个结论都成立，并且磁盘硬件保证单扇区磁盘写入是原子性的。

由于根节点地址要么是旧值，要么是新值（绝不会同时包含一部分旧值和一部分新值），其他进程无需加锁即可从数据库读取数据。外部进程可能看到旧树或新树，但绝不会同时看到两者。这样，提交操作就具有原子性。

由于我们在写入根节点地址之前就将新数据写入磁盘并调用了 <code>fsync</code> 系统调用 ，因此未提交的数据是无法访问的。相反，一旦根节点地址更新，我们就知道它引用的所有数据也都已在磁盘上。这样，提交操作也具有持久性。

=== NodeRefs 如何节省内存 ===

为了避免同时将整个树结构保存在内存中，当从磁盘读取一个逻辑节点时，其左右子节点的磁盘地址（以及该子节点的值）会被加载到内存中。访问子节点及其值需要额外调用一次 <code>NodeRef.get()</code> 函数来解引用（“真正获取”）数据。

构建 <code>NodeRef</code> 只需要一个地址：
<code>+---------+
| NodeRef |
| ------- |
| addr=3 |
| get() |
+---------+</code>
对其调用 <code>get()</code> 方法将返回具体的节点，以及该节点的引用（以 <code>NodeRef</code> 的形式）：
<code>+---------+ +---------+ +---------+
| NodeRef | | Node | | NodeRef |
| ------- | | ------- | +-> | ------- |
| addr=3 | | key=A | | | addr=1 |
| get() ------> | value=B | | +---------+
+---------+ | left ----+
| right ----+ +---------+
+---------+ | | NodeRef |
+-> | ------- |
| addr=2 |
+---------+</code>
当对树的更改尚未提交时，这些更改会以引用的形式存在于内存中，从根节点一直指向已更改的叶节点。这些更改尚未保存到磁盘，因此已更改的节点包含具体的键值对，但没有磁盘地址。执行写入操作的进程可以看到未提交的更改，并且可以在发出提交指令之前进行更多更改，因为如果存在未提交的值， <code>NodeRef.get()</code> 会返回该值；通过 API 访问时，已提交和未提交的数据之间没有区别。所有更新对于其他读取者来说都是原子性的，因为只有当新的根节点地址写入磁盘时，更改才可见。并发更新会被磁盘上的锁文件阻塞。锁在首次更新时获取，并在提交后释放。

=== 思考练习 ===
DBDB 允许多个进程同时读取同一个数据库而不会阻塞；但缺点是读取器有时会检索到过时的数据。如果我们需要以一致的方式读取某些数据该怎么办？一个常见的用例是读取一个值，然后根据该值更新数据库。您会如何在 <code>DBDB</code> 中编写一个方法来执行此操作？为了实现此功能，您需要做出哪些权衡？

更新数据存储所用的算法可以通过替换 <code>interface.py</code> 中的字符串 <code>BinaryTree</code> 来完全更改。数据存储通常使用更复杂的搜索树类型，例如 B 树、B+ 树等，以提高性能。虽然平衡二叉树（而这里使用的并非平衡二叉树）需要这样做。例如， ''O''(''log2N)'' 随机节点读取即可找到一个值，而 B+ 树所需的读取次数要少得多。因为每个节点会分成 32 个分支，而不是只有 2 个，查找复杂度为''O''(''log''32''n'')。这在实践中会产生巨大的差异，因为遍历 40 亿个条目将需要从''log'' 2 (232) =32到 ''log''32(232)≈6.4 次查找。每次查找都是一次随机访问，这对使用旋转盘片的硬盘来说开销极大。固态硬盘 (SSD) 有助于降低延迟，但 I/O 方面的开销优势依然存在。

默认情况下，值由 <code>ValueRef</code> 存储，ValueRef 接受字节作为值（直接传递给 <code>Storage</code> ）。二叉树节点本身只是 <code>ValueRef</code> 的一个子类。要通过 JSON 或 msgpack 存储更丰富的数据，只需编写自定义的 ValueRef <code>BinaryNodeRef</code> 并将其设置为 <code>value_ref_class</code> 即可。BinaryNodeRef 是使用 pickle 序列化数据的一个示例。

数据库压缩是另一个有趣的练习。压缩可以通过对树进行中值遍历来实现，边遍历边写入数据。最好将所有树节点放在一起，因为查找任何数据都需要遍历这些节点。将尽可能多的中间节点打包到一个磁盘扇区中应该可以提高读取性能，至少在压缩后是如此。如果您尝试自己实现，这里会有一些细节（例如内存使用情况）。记住：务必在压缩前后进行性能基准测试！结果往往会让您感到惊讶。

=== 模式与原则 ===
测试的是接口，而不是实现。在开发 DBDB 的过程中，我编写了许多测试用例，描述了我希望如何使用它。最初的测试用例是针对数据库的内存版本运行的，后来我扩展了 DBDB 的功能，使其能够持久化到磁盘，甚至后来还添加了 NodeRef 的概念。大多数测试用例都不需要修改，这让我确信系统仍然运行良好。

遵循单一职责原则。类最多只能有一个修改的理由。虽然数据库数据库（DBDB）并非完全如此，但它有很多扩展途径，只需要进行局部修改。在添加新功能的同时进行重构，真是令人愉悦！

=== 总结 ===
DBDB 是一个简单的数据库，它提供的保证也很简单，但即便如此，问题还是很快变得复杂起来。为了应对这种复杂性，我做的最重要的事情就是用一个不可变的数据结构来实现一个表面上可变的对象。下次当你遇到棘手的问题，觉得各种边界情况多到难以处理时，建议你考虑一下这种方法。

# 附加功能：您能保证压缩后的树状结构保持平衡吗？这有助于长期维持性能。↩

2. 对文件描述符调用 <code>fsync</code> 函数会请求操作系统和硬盘（或固态硬盘）立即写入所有缓冲数据。为了提高性能，操作系统和硬盘通常不会立即写入所有数据。

500行代码构建自己的数据库 DBDB - 版本历史