WormDb.Core 1.0.8

.NET 8.0

dotnet add package WormDb.Core --version 1.0.8

NuGet\Install-Package WormDb.Core -Version 1.0.8

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="WormDb.Core" Version="1.0.8" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="WormDb.Core" Version="1.0.8" />
                    

                            Directory.Packages.props

<PackageReference Include="WormDb.Core" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add WormDb.Core --version 1.0.8

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: WormDb.Core, 1.0.8"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package WormDb.Core@1.0.8

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=WormDb.Core&version=1.0.8
                    

                            Install as a Cake Addin

#tool nuget:?package=WormDb.Core&version=1.0.8
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

WormDb.Core

WORM（Write Once Read Many）追加型日志数据库引擎核心。

提供 Protobuf 序列化、LZ4 压缩、mmap 零拷贝读取、时间索引和 Tag 倒排索引。零外部依赖（不依赖数据库、消息队列等），纯 .NET 8.0 实现。

功能

特性	说明
WORM 不可变	只追加写入，禁止 Update/Delete，编译期 + 运行期 + OS 三层防护
纳秒时间戳	引擎自动填充 Unix 纳秒时间戳，全局有序
Protobuf 序列化	紧凑二进制格式，支持跨语言读写
mmap 零拷贝读	MemoryMappedFile + unsafe 指针，多线程无锁并发
LZ4 压缩	后台分段合并时自动压缩，读取无须解压全段
TagIndex 倒排索引	按 Tag `key=value` 快速过滤，多条件 AND 取交集 O(m+n)
单写多读	单线程顺序 IO + BlockingCollection 背压队列

核心 API

ILogDatabase 是主要的对外接口：

// 写入
void Append(LogEntry entry);
void AppendBatch(IReadOnlyList<LogEntry> entries);

// 时间范围查询
IReadOnlyList<LogEntry> Query(long startNs, long endNs);
PagedResult<LogEntry> QueryPaged(PagedQuery query);
LogEntry? GetLatest();

// Tag 倒排索引查询
IReadOnlyList<LogEntry> QueryByTag(string tagKey, string tagValue, long startNs, long endNs);
IReadOnlyList<LogEntry> QueryByTags(IReadOnlyList<(string Key, string Value)> conditions, ...);
PagedResult<LogEntry> QueryPagedByTag(string tagKey, string tagValue, PagedQuery query);

// 运维
void Flush();
void TriggerMerge();
void PurgeBefore(long retainBeforeNs);
int WriteQueueDepth { get; }

核心组件

类	职责
`LogDatabase`	数据库主入口，组装所有子组件
`SegmentManager`	管理 `.logseg` 分段文件生命周期
`LogSegment`	单个分段文件的追加/封存/读取
`AppendWriter`	单写线程写入器（BlockingCollection 背压）
`MmapReader`	mmap 并发读取器，跨分段路由查询
`LogIndex`	时间索引，内存 SortedList + 持久化 `.logidx`
`TagIndex`	Tag 倒排索引，支持 AND 交集查询
`SegmentMerger`	后台周期合并小分段，LZ4 压缩

存储格式

扩展名	内容
`.logseg`	分段数据文件（WORM 魔数 + 64 字节头部 + 变长记录）
`.logidx`	时间索引文件（LIDX 魔数 + N×16 字节 [ts+offset]）
`.tagidx`	Tag 倒排索引文件（TIDX 魔数 + key/value/offset 分层结构）

依赖

<PackageReference Include="Google.Protobuf" Version="3.35.0" />
<PackageReference Include="Grpc.Tools" Version="2.81.0" PrivateAssets="All" />
<PackageReference Include="K4os.Compression.LZ4" Version="1.3.8" />
<PackageReference Include="Microsoft.IO.RecyclableMemoryStream" Version="3.0.1" />

使用

using WormDb.Core;

// 创建数据库实例
var db = new LogDatabase(new LogDatabaseOptions
{
    DataDirectory = "./data",
    SegmentMaxBytes = 256 * 1024 * 1024, // 256 MB
    TagIndexKeys = new[] { "level", "service" }
});

// 写入日志
db.Append(new LogEntry
{
    TimestampNs = AppendWriter.NanoTime(),
    Level = "INFO",
    Service = "order-service",
    Message = "Order created",
    Tags = { ["userId"] = "12345", ["orderId"] = "ORD-001" }
});

// 查询最近 1 小时的日志
var results = db.Query(
    startNs: AppendWriter.NanoTime() - TimeSpan.FromHours(1).ToNanoSeconds(),
    endNs: AppendWriter.NanoTime()
);

// 按 Tag 过滤
var errors = db.QueryByTag("level", "ERROR", startNs, endNs);

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Google.Protobuf (>= 3.35.0)
- K4os.Compression.LZ4 (>= 1.3.8)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
net8.0
- Google.Protobuf (>= 3.35.0)
- K4os.Compression.LZ4 (>= 1.3.8)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
net9.0
- Google.Protobuf (>= 3.35.0)
- K4os.Compression.LZ4 (>= 1.3.8)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)

NuGet packages (3)

Showing the top 3 NuGet packages that depend on WormDb.Core:

Package	Downloads
WormDb WORM (Write Once Read Many) append-only log database engine. Built-in TagIndex inverted index, LZ4 compression, mmap zero-copy reads, Protobuf serialization, gRPC cluster replication, and ASP.NET Core Minimal API. Zero external dependencies, single-binary deployment.	273
WormDb.Cluster WORM (Write Once Read Many) append-only log database engine. Built-in TagIndex inverted index, LZ4 compression, mmap zero-copy reads, Protobuf serialization, gRPC cluster replication, and ASP.NET Core Minimal API. Zero external dependencies, single-binary deployment.	144
WormDb.Extensions WORM (Write Once Read Many) append-only log database engine. Built-in TagIndex inverted index, LZ4 compression, mmap zero-copy reads, Protobuf serialization, gRPC cluster replication, and ASP.NET Core Minimal API. Zero external dependencies, single-binary deployment.	112

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.8	0	6/4/2026