django-pindb 0.1.12

TL;DR API

# Try to save without pinning:
foo = Model.objects.all()[0]

# UnpinnedWriteException raised under strict mode, or master pinning occurs under greedy mode.
foo.save()

# read only from the master, allow writes.
pindb.pin(alias)

# Initialize/end the container:
pindb.unpin_all()

with unpinned_replica(alias):
   ... # read from replicas despite pinning state
# or
queryset.using(pindb.get_replica('master-alias'))

with master(alias):
   ... # write to master despite pinning state

术语

master指的是可写数据库。副本（或slave）指的是只读数据库，其数据来自master的写入。一个或多个master/slave数据库集可以帮助扩展读取并避免master上的锁竞争。通常所有读取都发送到副本，直到发生写入操作 - 然后，所有后续的读取也发送到master，以避免由于复制延迟而导致的不一致读取。pinning基于时间，并通过cookie在Web请求之间进行往返。有关更多信息，请参阅下面的“设计说明”。

安装

pip install pindb

TL;DR

1. 将 DATABASES_ROUTERS 设置为使用pindb路由器

2. 在测试中将 PINDB_ENABLED 设置为False

3. 定义数据库master和副本集。

4. 使用 pindb.populate_replicas 填充 DATABASES

5. 将 PinDbMiddleware 添加到您的中间件中。

6. （如果需要）与celery集成。

7. 为显式跳过pinning的位置进行配置。

更明确地

将 pindb.StrictPinDbRouter 或 pindb.GreedyPinDbRouter 添加到 DATABASE_ROUTERS。

StrictPinDbRouter 需要在尝试写入之前声明绑定。优点是尽可能多地使用只读副本。缺点是您的代码需要许多声明来显式允许和放弃绑定。

GreedyPinDbRouter 一旦发生写入就会将绑定到主数据库。优点是大多数代码将正常工作。缺点是您将比可能更少地使用只读副本。您也可能遇到更多您的数据库状态在背后发生变化的情况：您可能从滞后副本中读取，然后根据旧信息执行写入（这将使您绑定到主数据库）。

PINDB_ENABLED 可用于在测试中禁用 pindb。每个通过 TEST_MIRROR 映射的别名都获得自己的连接（因此是事务），这在 Django 的 TestCase 中存在问题，其中主写入在副本连接下是不可见的。

pindb 拥有详尽的测试套件；在自己的测试套件中禁用它是合理/推荐的。

如果您需要管理多个主/副本集，请为 pindb 添加 PINDB_DELEGATE_ROUTERS 以在数据库集选择时进行委派。这只是一个 Django 的另一个 数据库路由器，它应该返回一个主别名；pindb 然后根据返回主数据库的当前绑定状态选择主数据库或副本。

定义 MASTER_DATABASES，与 DATABASES 具有相同的模式

DATABASES = {
  "unmanaged": {
    # HOST0, etc.
  }
}

MASTER_DATABASES = {
  "default": {
    # HOST1, etc.
  },
  "some_other_master": {
    ...
  }
}

定义 DATABASE_SETS，它覆盖特定副本的设置

DATABASE_SETS = {
  "default": [{HOST:HOST1}, {HOST:HOST2}, ...],
  "some_other_master": [...] # zero or more replicas is fine.
}

使用 pindb.populate_replicas 确定最终 DATABASES

DATABASES.update(populate_replicas(MASTER_DATABASES, DATABASE_SETS))

在预期数据库访问之前将 pindb.middleware.PinDbMiddleware 添加到您的 MIDDLEWARE_CLASSES

可选地，在您的代码库中，如果打算写入，尽早声明以避免从相关副本的不一致读取

pin("default")

这将导致所有后续读取都使用主数据库。

在 celery 中使用时，将 celery.signals.task_postrun 钩子连接到调用 pindb.unpin_all

import pindb
from celery.signals import task_postrun

def end_pinning(**kwargs):
  pindb.unpin_all()
task_postrun.connect(end_pinning)

异常及其避免

with pindb.unpinned_replica(alias):
  # code which reads from replicas

with pindb.master(alias):
  # code which writes to the DB

需求和设计注意事项

我们有多个独立的主数据库（不一定分片）。让我们称一个主数据库及其副本的组为一个“数据库集”。

我们希望拥有这些主数据库的只读副本，并尽可能多地从副本读取，同时希望所有写入操作都发送到该组的master。但我们还希望读取操作与写入操作保持一致性。

我们希望这不仅在web请求周期中可行，对于像任务或shell脚本这样的工作单元也同样适用。因此，我们将这个工作单元称为“固定上下文”。

对特定master的写入应继续从master读取，以避免在复制延迟窗口中出现不一致，因此将有一个API来声明这一点。声明（或优先选择）需要一组master的操作称为“固定”，所有数据库集的固定组称为“固定集”。

计划写入（或需要最新数据）的代码应尽可能早地声明，以从master获得完全一致的观点。

如果我们固定了错误（即，在从集读取后写入），将是一个明显的错误。这里的问题是，如果我们允许读取（不知道即将进行写入），这将给我们一个不一致的窗口。例如，一个进程从副本读取，获取在master中已被删除的PK，写入master，失败。或者获取在master中被修改的PK，因此不应该被处理等。

需要写入但不固定整个容器（例如，日志表）的代码应能够绕过固定。

我们应该能够在具有最小重复性的设置中管理数据库集，并且应该与多个设置文件很好地组合。

MASTER_DATABASES = {
  'master-alias': { 'HOST':"a", ...normal settings },
   ...
}

DATABASE_SETS = {
  'master-alias': [{'HOST':'someotherhost',...},],
   # override some of the master settings
}

DATABASES = DATABASES.update(populate_replicas(MASTER_DATABASES, DATABASE_SETS))

DATABASES = {
  'master-alias': { 'HOST':"a", ...normal settings },
  'master-alias-1': { 'HOST':"someotherhost", ...merged settings,
                      TEST_MIRROR='master-alias' },
  ...}

with pindb.unpinned_replica('master-alias'):
       ...

pindb.pin('master-alias')

覆盖率

查看 pindb 的覆盖率。

$ PYTHONPATH=.:$PYTHONPATH coverage run setup.py test $ coverage html

示例配置

MASTER_DATABASES = {
    'default': {
        'NAME': 'db1',
        'ENGINE': DB_ENGINE,
        'USER': '...',
        'PASSWORD': '...',
        'HOST': '10.0.1.0',
        'PORT': 3306,
        'OPTIONS': DB_OPTIONS
    },
    'api': {
        'NAME': 'db2',
        'ENGINE': DB_ENGINE,
        'USER': '...',
        'PASSWORD': '...',
        'HOST': '10.0.2.0',
        'PORT': 3306,
        'OPTIONS': DB_OPTIONS
    },
}

DATABASE_SETS = {
    "default": [{'HOST': '10.0.1.1'},{'HOST': '10.0.1.2'}],
    "api": [{'HOST': '10.0.2.1'}]
}

DATABASES = {...}

DATABASES.update(pindb.populate_replicas(MASTER_DATABASES, DATABASE_SETS))


PINDB_DELEGATE_ROUTERS = ["myapp.router.Router"]
DATABASE_ROUTERS = ['pindb.GreedyPinDbRouter']

# default values which you can override:
PINDB_ENABLED = True
PINDB_PINNING_COOKIE = 'pindb_pinned_set'
PINDB_PINNING_SECONDS = 15