Django-Multidb-Router 技术文档

1. 安装指南

在开始使用 django-multidb-router 前，请确保已经安装了 Django。安装 django-multidb-router 的方法如下：

使用 pip 安装：

pip install django-multidb-router

2. 项目的使用说明

django-multidb-router 提供了两种 Django 数据库路由器，用于主从数据库部署。

ReplicaRouter

使用 multidb.ReplicaRouter，所有读操作都会指向从数据库；所有插入、更新和删除操作都会指向 default 数据库。

首先，在您的 settings 中定义 REPLICA_DATABASES。它应该是一个可以在 DATABASES 中找到的数据库别名列表：

DATABASES = {
    'default': {...},
    'shadow-1': {...},
    'shadow-2': {...},
}
REPLICA_DATABASES = ['shadow-1', 'shadow-2']

然后将 multidb.ReplicaRouter 添加到 DATABASE_ROUTERS 中：

DATABASE_ROUTERS = ('multidb.ReplicaRouter',)

从数据库将以轮询方式选择。

如果您想在应用中获得一个指向从数据库的连接，请使用 multidb.get_replica：

from django.db import connections
import multidb

connection = connections[multidb.get_replica()]

PinningReplicaRouter

在某些应用中，主数据库接收到写入操作和复制到从数据库之间的延迟足够大，以至于会导致最终用户的不一致性。如果您的应用存在这个问题，可以考虑使用 multidb.PinningReplicaRouter。这个路由器与 multidb.middleware.PinningRouterMiddleware 一起工作，确保在写入 default 数据库后，同一用户代理的后续读取操作在配置的时间内指向 default 数据库。

3. 项目API使用文档

PinningRouterMiddleware

PinningRouterMiddleware 主要通过请求类型识别数据库写入操作，假设除 GET、TRACE、HEAD 或 OPTIONS 外的 HTTP 方法都是写入操作。您可以使用 multidb.db_write 装饰器指示任何视图写入数据库，这将会产生与请求是 POST 等方法相同的结果。

您也可以手动设置 response._db_write = True 来指示发生了写入操作。这不会在本请求中使用 default 数据库，但会在下一个请求中使用。

配置

要使用 PinningReplicaRouter，请将其添加到您的 settings 中的 DATABASE_ROUTERS：

DATABASE_ROUTERS = ('multidb.PinningReplicaRouter',)

然后安装中间件。它必须排在任何执行数据库写入操作的其他中间件之前：

MIDDLEWARE_CLASSES = (
    'multidb.middleware.PinningRouterMiddleware',
    # 其他中间件...
)

PinningRouterMiddleware 会为刚刚写入的用户代理附加一个 cookie。该 cookie 应该设置为一个长于复制延迟的时间。默认情况下，其值是一个保守的 15 秒，但可以调整如下：

MULTIDB_PINNING_SECONDS = 5

如果您需要更改 cookie 的名称，请使用 MULTIDB_PINNING_COOKIE 设置：

MULTIDB_PINNING_COOKIE = 'multidb_pin_writes'

您还可以通过以下设置设置 'Secure'、'HttpOnly' 和 'SameSite' cookie 属性。这些设置基于 Django 的会话和 CSRF cookie 设置：

MULTIDB_PINNING_COOKIE_SECURE = False
MULTIDB_PINNING_COOKIE_HTTPONLY = False
MULTIDB_PINNING_COOKIE_SAMESITE = 'Lax'

注意：'SameSite' 属性在 django 2.1 及更高版本中可用。

use_primary_db

multidb.pinning.use_primary_db 是一个上下文管理器，也是一个装饰器，用于包装代码以使用主数据库。您可以使用它作为一个上下文管理器：

from multidb.pinning import use_primary_db

with use_primary_db:
    touch_the_database()
touch_another_database()

或者作为一个装饰器：

from multidb.pinning import use_primary_db

@use_primary_db
def func(*args, **kw):
    """Touches the primary database."""

4. 项目安装方式

请参考“安装指南”部分。

以上就是 django-multidb-router 的技术文档，希望能帮助您更好地使用和理解该项目。