# DATVIA **Repository Path**: loongspears/datvia ## Basic Information - **Project Name**: DATVIA - **Description**: DATVIA 是一个用一套 Python API 接入 MongoDB、MySQL 和 Redis,按需使用原生驱动的数据库集成系统。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: https://gitee.com/loongspears/datvia - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-19 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: Database, MongoDB, MySQL, Redis ## README

DATVIA

Data via one Python API.

用一套 Python API 接入 MongoDB、MySQL 和 Redis,按需使用原生驱动。

Python 3.10+ · 同步与异步 API · MIT 许可证

快速开始 · 原生客户端 · 连接管理 · 记录操作 · 文档 · 发布日志

--- ## 🎯 快速开始 ### 安装 准备 Python 3.10 或更高版本和 Git。克隆 DATVIA 源码并安装。 ```bash git clone https://gitee.com/loongspears/datvia.git cd datvia python -m pip install . ``` 发行包名和 Python 导入名均为 `datvia`。已检出源码时,在仓库根目录运行 `python -m pip install .`。安装包含三个后端的驱动,依赖约束见 [requirements.txt](requirements.txt)。 | 后端 | 默认驱动依赖 | | --- | --- | | MongoDB | `pymongo>=4.6.0` | | MySQL | `mysql-connector-python>=8.3.0` | | Redis | `redis>=5.0.0` | ### 第一个连接 下面连接到本机 `127.0.0.1:6379` 上的 Redis,检查一次连接并在退出上下文时关闭它。 ```python from datvia import ConnectionConfig from datvia import Connections connections = Connections({ 'cache': ConnectionConfig(backend='redis', host='127.0.0.1', port=6379), }) with connections.create('cache') as connection: result = connection.check() print(result.backend, result.elapsed_ms) ``` ## ✨ 核心特性 - 🗂️ **按名称管理连接**。在同一个 `Connections` 中登记多个后端或同一后端的多个实例。 - 🔌 **直接使用原生驱动**。用 `Client` 工厂或句柄的 `.native` 访问驱动对象,继续使用原生查询、事务和命令。 - ⚡ **同步与异步**。统一入口管理创建和关闭,支持 Redis 单机、Sentinel 与 Cluster。 - 🩺 **显式检查与统一异常**。用 `check()` 查看一次探测结果,从 `DatabaseError.original` 获取原始异常。 ## 原生客户端 ### MongoDB PyMongo 4.6–4.8 支持同步的 `create()`。异步的 `create_async()` 需要 PyMongo 4.9 或更高版本。使用 MongoDB 异步连接的应用应在自己的依赖中声明 `pymongo>=4.9`。 ```python import asyncio from datvia.mongodb import Client with Client.create("mongodb://127.0.0.1:27017/") as client: client.admin.command("ping") async def ping_mongodb(): async with Client.create_async("mongodb://127.0.0.1:27017/") as client: await client.admin.command("ping") asyncio.run(ping_mongodb()) ``` #### MongoDB 分批写入与读取 `datvia.mongodb.utils` 接收原生 PyMongo 集合和游标。批处理器借用集合,MongoDB 客户端和连接池由调用方关闭。 ```python from datvia.mongodb.utils import BatchInsert, BatchUpdate, cursor_batches from pymongo import UpdateOne def migrate(source, target): with cursor_batches(source.find({'ready': True}).batch_size(500), step=500) as pages: with BatchInsert(target, step=500, ordered=False) as writer: for page in pages: writer.extend(page) def mark_processed(target, ids): with BatchUpdate(target, step=500) as writer: writer.extend(UpdateOne({'_id': key}, {'$set': {'processed': True}}) for key in ids) ``` - `BatchInsert` 写入文档,`BatchUpdate` 支持 `add(filter, update)` 和原生 `UpdateOne`。`BatchWrite` 接收原生 `InsertOne`、`UpdateOne`、`UpdateMany`、`ReplaceOne`、`DeleteOne` 和 `DeleteMany`,可以混合插入、更新、替换和删除。 - `extend()` 逐项消费输入,达到 `step` 立即写入。`step` 调整每批条数,驱动的网络读取批量可用游标的 `batch_size()` 单独调整。大输入可使用生成器或游标,调用方应及时释放消费完的批次。 - `execute()` 和 `close()` 都会写出尾批。上下文退出时也会写出尾批,包括因业务异常退出。需要放弃尾批时,在退出前调用 `discard()`。每次尝试写入后都会释放该批缓冲,失败的批次由应用结合原生错误判断如何处理。 - `on_error` 默认抛出原生 `BulkWriteError`,也可设为 `'log'` 或 `'ignore'`。`success_count` 分别累计已确认的插入数、修改数或混合写入影响的文档数。`error_count` 统计驱动报告的逐条写入错误,`unacknowledged_count` 统计使用非确认写入提交的操作数。`write_concern_error_count` 统计驱动报告的写关注错误条数。`success_count` 仅纳入满足写关注的批次计数。 - 有序批次可能在首个逐条写入错误处停止。保留默认错误策略可从原生异常的 `details` 查看部分写入结果和写关注错误。 - `cursor_batches()` 接管传入游标,在离开 `with` 时关闭它。提前 `break` 后退出作用域,或消费过程中抛出异常,都会执行关闭。 异步使用 `AsyncBatchInsert`、`AsyncBatchUpdate`、`AsyncBatchWrite` 和 `async_cursor_batches()`。`extend()` 也接收异步可迭代对象。 ```python from datvia.mongodb.utils import AsyncBatchInsert, async_cursor_batches async def migrate_async(source, target): async with async_cursor_batches(source.find({'ready': True}), step=500) as pages: async with AsyncBatchInsert(target, step=500) as writer: async for page in pages: await writer.extend(page) ``` #### MongoDB 分页读取与流式续读 `scan_collection()` 和 `stream_collection()` 接收集合与筛选条件,按 `_id` 升序逐条交付。适用于具有常规 `_id_` 索引、简单排序规则和全局唯一 `_id` 的普通集合。续读用索引下界定位,保留原筛选条件。每次查询读取当时可见的数据,恢复位置保存在本次遍历中。 ```python from datvia.mongodb.utils import scan_collection, stream_collection def process_in_pages(articles, process): for article in scan_collection(articles, {'approved': True}, step=1000): process(article) def process_in_stream(articles, process): with stream_collection(articles, {'approved': True}, batch_size=1) as rows: for article in rows: process(article) ``` - 分页在交付前读完并关闭本页游标,适合批间有长时间等待的任务。默认每页最多 1000 条,内存开销随页大小和文档大小增长。默认 `max_retries=0`,显式开启后从上一页末尾的断点重读失败页。 - 流式在游标有效时按需取数,遇到可恢复的读取中断时从最后交付的 `_id` 续读。默认 `batch_size=1`,同一位置最多额外尝试 3 次。离开 `with` 时关闭当前游标。较大的驱动批次可减少网络往返,也会增加缓冲。 - 可恢复的读取中断包括游标失效、查询计划被终止和 `AutoReconnect` 类连接中断。权限错误、查询执行超时、业务异常和取消信号直接传播。重试次数耗尽时抛出最后一次原生异常。`max_retries` 控制 SDK 的恢复次数,驱动的读重试由 PyMongo 客户端选项单独控制。 - 异步使用 `async_scan_collection()` 配合 `async for`,或使用 `async_stream_collection()` 配合 `async with` 和 `async for`。 ### MySQL 使用 MySQL Connector/Python。`create_async()` 需要 `await`,驱动完成建连后返回原生异步连接。示例从 `MYSQL_USER` 和 `MYSQL_PASSWORD` 环境变量读取凭据。 ```python import asyncio import os from datvia.mysql import Client options = { "host": "127.0.0.1", "user": os.environ["MYSQL_USER"], "password": os.environ["MYSQL_PASSWORD"], } with Client.create(**options) as connection: connection.ping() async def ping_mysql(): async with await Client.create_async(**options) as connection: await connection.ping() asyncio.run(ping_mysql()) ``` ### Redis `create()` 和 `create_async()` 默认获取单机客户端。`connect()` 还支持 `mode="sentinel"` 和 `mode="cluster"`,可传 `is_async=True` 获取异步对象。Sentinel 模式返回 `Sentinel`,可用 `master_for()` 获取主节点的数据客户端。 ```python import asyncio from datvia.redis import Client with Client.create(host="127.0.0.1", port=6379) as client: client.ping() async def ping_redis(): async with Client.create_async(host="127.0.0.1", port=6379) as client: await client.ping() asyncio.run(ping_redis()) ``` ## 统一配置和显式连接管理 新高层接口只接受调用方传入的参数,不读取环境变量、不加载 `.env`。上文 MySQL 示例中的环境读取发生在调用方代码中。可以自行读取密钥服务或配置文件,再传入 SDK。 ```python from contextlib import ExitStack from datvia import ConnectionConfig, Connections def build_connections(mysql_password): return Connections({ "orders": ConnectionConfig( backend="mysql", host="127.0.0.1", username="app", password=mysql_password, options={"database": "orders"}, ), "documents": ConnectionConfig( backend="mongodb", host="mongodb://127.0.0.1:27017/", ), "cache": ConnectionConfig( backend="redis", host="127.0.0.1", options={"db": 0}, ), }) connections = build_connections("由调用方提供的密码") with ExitStack() as stack: orders = stack.enter_context(connections.create("orders")) documents = stack.enter_context(connections.create("documents")) cache = stack.enter_context(connections.create("cache")) for connection in (orders, documents, cache): result = connection.check() print(result.scope, result.elapsed_ms) with orders.errors(operation="read_order"): with orders.native.cursor() as cursor: cursor.execute("SELECT 1") print(cursor.fetchone()) ``` 同名配置每次创建独立对象,由调用方决定何时复用与关闭。可以增加另一个名字来连接第二个 MySQL。新配置必须给出显式目标,重复的共同参数和原生参数会报错;`options` 中使用驱动原生名称,例如 MySQL 的 `database`、Redis 的 `db`、MongoDB 的 `authSource`。 创建保持驱动原生初始化时机,不额外探测。显式 `check()` 成功也不代表持续在线或拥有全部 CRUD 权限;SDK 不提供持续有效的 `is_connected` 状态。 ### 异步 ```python async def read_document(connections, document_id): async with await connections.create_async("documents") as connection: await connection.check() with connection.errors(operation="read_document"): return await connection.native["app"]["items"].find_one( {"_id": document_id} ) ``` 高层 `Connections.create_async()` 统一使用 `await`。原生工厂 `datvia..Client` 的调用方式见各后端示例。异步句柄应在创建它的事件循环内检查和关闭;同步与异步实例相互独立。 ### Redis 拓扑 ```python sentinel_config = ConnectionConfig( backend="redis", mode="sentinel", nodes=[("127.0.0.1", 26379)], service_name="cache-primary", options={"socket_timeout": 2, "sentinel_kwargs": {"socket_timeout": 2}}, ) cluster_config = ConnectionConfig( backend="redis", mode="cluster", nodes=[("127.0.0.1", 7000), ("127.0.0.1", 7001)], options={"socket_timeout": 2}, ) ``` Sentinel 的 `native` 仍是原生 Sentinel 对象,可以调用 `master_for()` 和 `slave_for()`。检查会通过指定服务建立临时主节点数据客户端,执行 PING 后清理。Sentinel 节点凭据通过 `sentinel_kwargs` 显式设置,不自动复制数据节点密码。 Cluster 检查客户端当前发现的全部主节点快照,逐个 PING;首次失败即抛出异常,未检查节点不会标记为正常。不会检查全部副本或保证集群持续健康。 ### 异常和原生访问 ```python from datvia.errors import DatabaseError try: with connections.create("orders") as connection: connection.check() except DatabaseError as error: print(error.connection_name, error.phase) # 原始对象、错误码、详情及已有异常链保存在 error.original。 # 输出原始异常前,由调用方决定如何处理其中可能包含的私密信息。 ``` SDK 自动转换其自身配置、创建、检查及关闭范围内的已识别错误。原生业务操作只有位于 `connection.errors(...)` 中时才转换所属驱动的异常;上下文外完全遵循原生行为。惰性游标迭代和异步等待也必须位于上下文中。业务异常和取消信号原样传播。 统一类别不意味着写入必然失败或可以安全重试。没有可靠分类的驱动错误保留为 `DriverError`,不按错误文本猜测原因。原始对象在 `original` 中,因果链通过 `__cause__` 保留。已有主异常时发生的关闭错误附加在 `database_cleanup_errors` 中,不覆盖主异常。 ### 资源和超时 高层上下文管理器清理 SDK 创建的客户端和自有资源,不关闭调用方传入的外部池;MySQL 池化连接按驱动语义归还池。自行创建的游标、Pipeline 或额外客户端由调用方管理。不要依赖句柄为原生对象增加线程安全或并发安全保证。 `connect_timeout_s` 是正整数秒,仅控制建立连接阶段。读取响应、节点选择和等待连接池等限制通过 `options` 使用驱动支持的参数配置。MySQL Connector/Python 8.3 不支持后来 9.2 加入的 `read_timeout`,本 SDK 不承诺统一的整体检查硬超时,也不增加自动重试。 MongoDB 的检查结果使用 `scope="selected_server"`,`targets` 为空:原生 `ping` 不公开实际执行节点,因此 SDK 不猜测地址。Windows 上 MySQL 需要显式主机地址,不能仅用驱动不支持的 Unix socket 参数指定目标。同步 Redis Cluster 的 `startup_nodes` 不接受已经绑定客户端的节点,以防意外关闭调用方资源。 原生驱动负责异步创建返回句柄前的资源清理。Connector/Python 握手取消的限制和 Redis 拓扑的连接验证见 [连接管理验收记录](docs/connection-management-validation.md)。Redis 记录操作的验证见 [基础使用验收记录](docs/crud-basic-implementation.md#5-隔离真实服务验证)。 ## 基础结构准备与键值操作 在使用记录 CRUD 前,可以通过 `datvia.schema.Schema` / `AsyncSchema` 显式准备 MySQL 数据库与基础表、MongoDB 普通集合及必要身份约束。已有结构只做兼容性校验,不自动迁移。Redis 直接绑定 Hash 命名空间,或通过 `RedisStrings` / `AsyncRedisStrings` 使用 String 单键、批量与 TTL 接口。 MySQL 的初始化连接应省略尚未创建的业务库并启用 autocommit;创建完毕后另建选定业务库的连接。MongoDB 的集合准备和 Redis 的键空间绑定保留各自概念。上述对象都借用既有连接,原生高级能力仍通过 `connection.native` 使用。 下面用 MongoDB 演示最短完整流程,包含配置、集合准备、绑定、增删改查和资源关闭。请传入演示实例地址并使用专用演示集合。 ```python from datvia import ConnectionConfig, Connections from datvia.crud import Records from datvia.schema import Schema def demo(mongodb_uri): connections = Connections({ "documents": ConnectionConfig(backend="mongodb", host=mongodb_uri), }) with connections.create("documents") as connection: Schema.mongodb(connection).ensure_collection("sdk_demo", "users") with Records.mongodb( connection, database="sdk_demo", collection="users" ) as users: users.insert({"_id": "u1", "name": "Alice"}) print(users.get({"_id": "u1"}, fields=["name"])) users.update({"_id": "u1"}, set_values={"name": "Alicia"}) users.delete({"_id": "u1"}) ``` 从显式配置到三种数据库同步、异步 CRUD 的完整代码见 [完整使用示例](examples/basic_usage.py),接口、结构管理和 String 语义见 [使用说明](docs/crud-usage.md)。实际验证范围及剩余事项见 [基础使用封装验收记录](docs/crud-basic-implementation.md)。 ## 高级记录操作 `datvia.crud` 提供可选的记录层:MySQL 表、MongoDB 集合和显式选择的 Redis Hash 格式共用按键读取、字段投影及批量写入接口。它借用已有连接,保留 `connection.native` 的全部能力。 ```python from datvia.crud import Records with connections.create('orders') as connection: with Records.mysql(connection, table='orders', key_fields=('id',)) as orders: items = orders.get_many([{'id': 1001}, {'id': 1002}], fields=['status']) result = orders.bulk_update([ {'key': {'id': 1001}, 'set_values': {'status': 'paid'}}, {'key': {'id': 1002}, 'set_values': {'status': 'cancelled'}}, ]) # 是否提交及如何回滚由调用方决定。 with connection.errors(operation='commit_orders'): connection.native.commit() ``` 异步使用 `AsyncRecords`、`async with` 和 `await`,方法及返回结构一致。MongoDB/MySQL 支持有界条件查询和集合更新;Redis 只提供指定键的 Hash 操作,不扫描整个数据库模拟条件查询。 `fields=[]` 对存在记录返回 `{}`,未命中返回 `None`;MongoDB/Redis 的缺失字段与明确空值分开保留。批量失败提供逐项状态,已发送但无法确认的项标为 `unknown`,不会伪装成未执行。写入确认不等于事务提交,SDK 不自动重试、提交或回滚。 完整接口、同步/异步示例、Redis 格式与 TTL、原始错误及事务边界见 [高级记录操作使用说明](docs/crud-usage.md)。本功能的实际验证范围见 [CRUD 实施与验收记录](docs/crud-implementation.md)。 ## 数据库账号与权限管理 `datvia.accounts` 借用现有管理连接,支持本库句柄或原生 PyMongo、Connector/Python、redis-py 客户端。MongoDB 用认证库和用户名定位账号,MySQL 用用户名和来源主机定位账号,Redis ACL 作用于固定的数据节点。下例中的连接由调用方提供。 ```python from datvia.accounts import Accounts, AsyncAccounts, MongoRole, MongoUser, MySQLAccount with connections.create("mongo_admin") as conn: mongo = Accounts.mongodb(conn) user = MongoUser(auth_db="staff", name="analyst") mongo.grant_roles(user, roles=[MongoRole(db="reports", name="read")]) details = mongo.get_user(user, expand_privileges=True) mysql = Accounts.mysql(native_mysql) grants = mysql.show_grants(MySQLAccount(user="analyst", host="10.0.0.8")) async def inspect_redis(native_async_redis): return await AsyncAccounts.redis(native_async_redis).get_user("analyst") ``` MySQL 账号写操作使用启用自动提交且没有活动事务的连接。Redis 的 `apply_user` 对同名用户按顺序应用规则,`save_acl` 单独确认当前节点的 ACL 文件写入。账号写入遇到 `AccountWriteOutcomeUnknown` 时,请先回读目标状态,改密可通过独立认证核对。各方法所需权限、使用示例与已验证的环境见[需求清单](docs/account-management-requirements.md)、[实现设计](docs/account-management-design.md)和[验收记录](docs/account-management-validation.md)。 ## 文档与贡献 - [文档索引](docs/README.md) 汇总连接管理设计、验收记录和源码目录说明。 - [发布日志](CHANGELOG.md) 记录功能、兼容性变化和验证范围。 - [贡献指南](CONTRIBUTING.md) 说明开发环境、代码检查和提交约定。 - 项目讨论和贡献遵循 [社区行为准则](CODE_OF_CONDUCT.md)。 - [测试指南](tests/README.md) 提供离线测试及隔离数据库的验证命令。 - [安全说明](SECURITY.md) 说明凭据、日志和安全问题反馈方式。 本项目采用 [MIT 许可证](LICENSE)。