schapman1974/briskdb 来源：https://github.com/schapman1974/briskdb # BriskDB CI (https://github.com/schapman1974/briskdb/actions/workflows/ci.yml) 发布版 (https://github.com/schapman1974/briskdb/actions/workflows/release.yml) PyPI (https://pypi.org/project/briskdb/) 许可证：MIT > SQLite 文件，一个分片数据库。 BriskDB 将普通的 SQLite 文件转化为一个支持并行写入、PostgreSQL 兼容性、HTTP 访问以及内嵌 Rust/Python API 的数据库。它保留了 SQLite 成熟的存储引擎和工具链；BriskDB 增加了路由层、分片安全的 ID、跨分片索引、协议和运维保障。 | 核心能力 | 意味着什么 | | — | — | | 并行 SQLite 写入 | 独立的分片文件拥有独立的 WAL 写锁。 | | 使用现有客户端 | PostgreSQL 和 HTTP 客户端现已支持；MongoDB 和 MySQL 客户端正在计划中。 | | 嵌入式或服务运行 | 同一个 Rust 引擎驱动二进制文件、Python 轮子包和 Rust 库。 | | 保持文件可检查性 | 每个数据分片仍然是一个标准的 SQLite 数据库——没有 SQLite 分支。 | 无需编译器试用 · 下载 alpha 版 (https://github.com/schapman1974/briskdb/releases) · 打开数据浏览器 · 关注 MongoDB 和 MySQL 开发 > [!重要提示] > BriskDB 是一个 alpha 版本，尚未达到生产就绪的数据库服务标准。其 > 边界已明确说明，即使结果不尽如人意，我们也会公布经过测量的结果。 ## 为什么开发者可能会感兴趣 - 非 SQLite 分支。 每个分片都是一个普通的 SQLite WAL 数据库，可用标准工具检查。 - 无中央写锁。 对不同分片的写入使用不同的 WAL，并且可以并行进行。 - 无需逐行中央 ID 写入。 原生的范围分配和 hi/lo 分配机制提供跨分片和跨进程的无冲突生成 ID。 - 安全的跨分片裁剪。 全局唯一性得到保证；异步索引通过验证、水位线、布隆过滤器和最小/最大值摘要来确保优化操作不会悄悄隐藏行数据。 - 单一引擎，无处不在。 PostgreSQL、HTTP、Rust 和 Python 共享相同的路由、限制、取消、错误处理和存储行为。 - 操作可见性。 /health、/metrics、管理用 JSON 接口和 Rust 状态报告公开了延迟、修复、重建、资源竞争和发件箱压力等信息。 ## 一个引擎，多种接入方式 mermaid flowchart LR subgraph 客户端 WEB[浏览器 + HTTP] PG[PostgreSQL 客户端] MONGO[MongoDB 客户端 · 计划中] MYSQL[MySQL 客户端 · 计划中] RUST[Rust 嵌入式] PY[Python 嵌入式] end WEB --> ENGINE PG --> ENGINE MONGO -.-> ENGINE MYSQL -.-> ENGINE RUST --> ENGINE PY --> ENGINE ENGINE[协议中立的 Rust 引擎] --> ROUTER[4,096 个虚拟桶] ROUTER --> S0[(SQLite WAL · 分片 0)] ROUTER --> S1[(SQLite WAL · 分片 1)] ROUTER --> S2[(SQLite WAL · 分片 2)] ROUTER --> SN[(SQLite WAL · 分片 N)] 协议适配器并不拥有数据库语义。路由、限制、取消、值、会话和执行都位于共享的 Rust 引擎中，为未来的协议和存储适配器预留了空间。 ## 浏览整个逻辑数据库 BriskDB 数据浏览器，展示跨四个 SQLite 分片的一个逻辑表 BriskDB 在 /admin 路径提供响应式的只读数据浏览器。它与其他客户端使用相同的带限制的 HTTP 引擎路径，将分片行合并为一个逻辑视图，一次性读取全局表，并保留大整数值。对于当前本地 alpha 版本： text http://127.0.0.1:7654/admin username: admin password: admin 临时凭据是开发便利性设施，并非安全边界——这也是为什么服务器目前拒绝非回环 HTTP 地址的原因。 ## 独特之处：分片安全的生成 ID BriskDB 有两种用于分片表的生成 ID 设计： - native_range_v1 为每个分片分配一个不重叠的正 64 位范围。SQLite 自身的 INTEGER PRIMARY KEY AUTOINCREMENT 在本地执行实际分配，无需每行插入都进行中央写入。 - hilo_v1 从清单文件中持久租用 4,096 个 ID 的块，然后在内存中分配，并通过哈希将每个 ID 路由到相应分片。崩溃可能会留下空隙，但 ID 永远不会被重复使用。 两种策略都在清单文件中进行了版本管理。生成键的执行仍是实验性功能，需手动启用；具体合约详见 生成的键。 ## 目前可用功能 | 能力 | Alpha 状态 | | — | — | | 基于独立 SQLite WAL 文件的持久虚拟桶路由 | 可用 | | 精确键路由和有限制的 scatter/gather 读取 | 可用 | | HTTP 查询/写入 API 和管理数据浏览器 | 可用，仅限回环访问 | | PostgreSQL 线协议 | 支持 TLS/SCRAM、背压行流式传输、SQLite-interrupt 取消、文本/二进制 CRUD、真正的单分片事务，以及一个活跃的 psql/tokio-postgres/psycopg/SQLAlchemy 兼容性矩阵 | | 从标准 SQLite 数据库离线导入 | 可用 | | 原生范围和 hi/lo 生成 ID | 实验性，需手动启用 | | 跨分片索引和全局值租用 | 实验性/需手动启用：正确性、恢复和分片裁剪通过；当前延迟/写入开销记录在发布门控中 | | 全局索引健康状况和 Prometheus 指标 | /health、/v1/admin/global-indexes、/metrics，以及 Rust 运维报告 | | Ubuntu/macOS x86-64 和 ARM64 发布产物 | 已发布 | | Debian 包和加固的 systemd 服务 | 已发布 | | Rust 库入口点，可选附加监听器 | 可用 | | 共享同一就绪根目录的主机内服务和嵌入式进程 | 在本地文件系统上可用 | | 具备 TinyMongo 兼容性的原生 MongoDB 线协议 | 计划中 (https://github.com/schapman1974/briskdb/issues/160) | | MySQL 线协议 | 计划中 (https://github.com/schapman1974/briskdb/issues/40) | | 原生 Python 扩展 | 同步/异步 API 可用；已标记的发布版本构建并审计了 macOS/Linux ARM/x86 轮子包 | | 无服务器生命周期 | 计划中 (https://github.com/schapman1974/briskdb/issues/194) | ## BriskDB 的定位 这些项目解决不同的问题。此表格是指南针，而非基准测试成绩单。 | 项目 | 构建目的 | 写入模型 | 访问方式 | 存储形态 | | — | — | — | — | — | | BriskDB | 主机内分片，服务 + 嵌入式 | 跨独立分片 WAL 并行写入 | PostgreSQL, HTTP, Rust, Python | 清单文件 + 普通 SQLite 分片文件 | | SQLite (https://sqlite.org/wal.html) | 小型、嵌入式、单文件数据库 | 每个 WAL 文件一个写入者 | SQLite API 和生态系统 | 一个普通 SQLite 文件 | | rqlite (https://rqlite.io/docs/features/) | 简单多节点可用性 | 写入流经 Raft 日志；为高可用性而非写入扩展而优化 | HTTP + 客户端库 | 跨节点复制 SQLite 状态 | | Turso / libSQL (https://docs.turso.tech/sdk/introduction) | 云/边缘访问和本地优先同步 | 产品相关，主模型或本地推送/拉取模型 | SDK + HTTP | Turso 数据库或与遗留 SQLite 兼容的 libSQL | | Citus (https://www.postgresql.org/about/news/citus-120-released-2687/) | 成熟的分布式 PostgreSQL | 跨 PostgreSQL 工作节点分片并行写入 | PostgreSQL | PostgreSQL 协调器 + 工作节点集群 | 当您希望使用一个本地服务或嵌入式引擎，将写入竞争分散到可检查的 SQLite 文件中，同时使用熟悉的数据库协议时，请选择 BriskDB。当真正的单个 SQLite 文件、复制高可用性、托管边缘同步或成熟的多节点 PostgreSQL 集群是实际需求时，请选择其他方案。 ## 30秒试用 安装已发布的原生轮子包——无需克隆和 Rust 编译器： bash python -m pip install --only-binary=:all: briskdb curl -fsSLO https://raw.githubusercontent.com/schapman1974/briskdb/main/examples/launch_demo.py python launch_demo.py 该演示从四个 Python 线程发起 32 个路由写入，证明四个普通的 SQLite 分片文件都接收到了行数据，读回每一行，检查 HTTP 健康状态，并启动 PostgreSQL 监听器。它使用一个临时目录，并在执行后自行清理。GIF 渲染器执行此确切场景，CI 针对每个已发布的轮子包目标进行测试。要运行独立服务，从最新的 GitHub 发布版 (https://github.com/schapman1974/briskdb/releases) 下载匹配的 macOS/Linux ARM64 或 x86-64 归档文件，然后： bash ./briskdb --data-dir ./briskdb-data --shards 4 打开数据浏览器 (http://127.0.0.1:7654/admin) 或检查服务： bash curl http://127.0.0.1:7654/health curl http://127.0.0.1:7654/metrics 显式启用 PostgreSQL 监听器。简单的参数化文本/二进制预处理查询共享相同的带限制引擎路径： bash ./briskdb --data-dir ./briskdb-data --postgres-listen 127.0.0.1:5433 psql -h 127.0.0.1 -p 5433 -d default 这种本地开发形式无需认证，因此仅限回环访问。PostgreSQL 快速入门指南 展示了实现 TLS 加 SCRAM-SHA-256 认证所需的四项设置；任何远程绑定都需要安全模式。已注册的表也可以通过 HTTP 进行查询： bash curl -X POST http://127.0.0.1:7654/v1/query \ -H 'content-type: application/json' \ -d '{"sql":"SELECT id, name FROM widgets WHERE id = ?1","params":["widget-1"]}' 有一个现有的 SQLite 数据库？请使用离线 SQLite 导入器。Linux 发布版还包括带有加固 systemd 服务的 .deb 包。 嵌入 Rust 从 BriskDb::open() 或经过验证的构建器开始。内嵌 Rust 指南 包含一个完整的无监听器示例。创建数据时选择分片数量；后续打开操作会从清单文件中检测该数量，并拒绝显式不匹配。使用 default-features = false 和 embedded 特性可以排除网络和 CLI 栈；参见 crate 特性映射。 Python 在进程内直接运行相同的引擎。默认情况下不启动监听器，但 Database.serve() 可以附加 HTTP/PostgreSQL 监听器（远程 PostgreSQL 需要其 TLS/SCRAM 参数）： python with briskdb.open("./data", shards=4) as db: with db.serve(postgres="127.0.0.1:0") as server: print(server.http_address, server.postgres_address) 有关同步和 asyncio 写入/读取示例，请参阅 Python 快速入门指南。已标记的发布版本发布了无需编译器的 cp39-abi3 轮子包，适用于支持的平台矩阵；仓库检出版本仍可使用 Rust 1.85+ 从源码安装。独立启动的 Python、Rust 和服务器进程可以共享一个就绪的本地数据目录；部署此模式前请阅读多进程合约。 ## 仍然是可检查的文件 text briskdb-data/ ├── .briskdb-process.lock ├── .briskdb-startup.lock ├── manifest.sqlite ├── global-indexes/ │ └── global.sqlite └── shards/ ├── 0000.sqlite ├── 0001.sqlite ├── 0002.sqlite └── 0003.sqlite 清单文件对路由、目录、迁移、生成 ID 所有权和完整性元数据进行版本控制。应用数据行仍保存在普通 SQLite 文件中。 ## 未来发展方向 - MongoDB： 一个原生的 Rust Mongo 监听器，具备 BSON、查询、更新、索引、游标、聚合和差异化的 TinyMongo 兼容性。 - 更多线协议： 更广泛的 PostgreSQL 客户端兼容性和一个 MySQL 监听器，都共享相同的核心引擎行为。 - 无服务器存储： 原子快照、对象存储适配器以及超越当前嵌入式温处理模式的受限单写入者操作。 - 未来的存储适配器： SQLite 是第一个后端，同时引擎边界被设计为可复用于其他持久化后端。 请关注路线图或浏览开放问题 (https://github.com/schapman1974/briskdb/issues)。 ## 关注开发 如果您想关注以下任何押注，请为 BriskDB 点星： - 具备大型应用 TinyMongo 兼容性的原生 MongoDB 线协议； - 在相同的协议中立 Rust 引擎上实现 MySQL 兼容性； - 无服务器快照和对象存储支持的生命周期； - 在不放弃普通 SQLite 选项的前提下增加更多存储后端； - 随着 alpha 版本成为正式发布版，提供诚实的基准测试和故障证据。 如果您尝试了它，一个关于您客户端、工作负载或缺失的 SQL 模式的问题甚至比一个星标更有价值。请从 alpha 发布版 (https://github.com/schapman1974/briskdb/releases) 开始，然后告诉我们什么出错了或者什么让您感到惊讶 (https://github.com/schapman1974/briskdb/issues/new/choose)。 ## 诚恳的 alpha 边界 - PostgreSQL 具有 TLS 和单一身份的 SCRAM-SHA-256 认证，但尚未实现角色或授权功能。HTTP 仍然是一个仅限回环的开发接口。 - 没有跨多个分片文件的通用原子事务。 - 全局排序/分页和通用聚合下推仍然有限。 - 当前支持的备份方式是在每个服务器和嵌入式进程退出后，停止服务器并复制完整数据目录。被动检查点现在报告分片、清单和全局索引存储状况，但不是在线快照；计划提供在线/无服务器快照。 - 多进程访问仅限于同一主机/本地文件系统。模式、目录、升级和恢复工作需要独占进程所有权。 - 1.0 版本之前的存储和公共库兼容性可能会在发布版之间发生变化。 - Ubuntu 24.04 x86-64 接收完整的必需 Rust CI 测试套件。Python 轮子包在 Linux/macOS x86-64 和 ARM64 上接受原生构建、审计、安装、重启、损坏和并发检查。 - 全局索引运维指标已可用，但 BriskDB 仍然缺乏更广泛的生产套件，如追踪、慢查询日志、资源饱和、告警规则和长时间运行的能力验证。 ## 深入了解 - 架构 - 全局唯一性和值权威 - 全局索引生产门控 - 内嵌 Rust - 内嵌 SQL - Crate 特性和支持层级 - PostgreSQL 快速入门 - 已测试的 PostgreSQL 客户端 - SQL 兼容性 - 生成的键 - 存储格式 - 在进程间共享同一数据目录 - Debian 和 systemd 安装 - 1.0 版本前的兼容性策略 - 贡献指南 BriskDB 基于 MIT 许可证 提供。