BTDB.Replication 35.13.0-preview

BTDB.Replication

BTDB.Replication runs one or more logical BTDB databases on several disposable compute nodes. One elected leader authors a single canonical history in Azure Blob Storage; every node keeps a local, disposable BTDB cache and executes the application's ordered events locally. The application's event log remains the source for replaying a recent tail that was not yet published.

Status: preview. Implemented and tested with deterministic simulation and seeded schedule exploration, loopback HTTP, Azurite, and subprocess failover and ObjectDB application tests; the adapter and subprocess suites also pass against live Azure, and restore throughput is measured on Azure VMs. Packages are published as -preview versions. Open before production use: qualification with the production application (see Architecture).

Install

Requires .NET 10. For an ASP.NET Core host with Azure Blob Storage, install both adapters at the same preview version:

dotnet add package BTDB.Replication.Http --version 35.11.0-preview
dotnet add package BTDB.Replication.Azure --version 35.11.0-preview

Both depend on BTDB.Replication, which brings in BTDB. The optional BTDB.Replication.EventLog namespace is included in the core package; its HTTP hosting and Azure storage are included in the two adapters. There is no separate EventLog package. See the package and release guide and the hosting guide for integration.

Properties

• Split-brain safety. A node leads only while it holds a finite Blob lease and the CAS-selected leader.json names its term and session. Losing contact with the leader never grants authority; when authority cannot be proven, canonical progress stops. Every canonical write is a conditional operation checked against that authority.
• One shared recovery base. Blob Storage holds one canonical history per database (native TRL chain plus KVI checkpoints), independent of the replica count. Local files are only a validated cache.
• Disposable compute. A new node restores from the latest checkpoint and canonical TRL, reusing local files only when their identity, length and SHA-256 match. No persistent volume is required. A restore keeps working while the leader publishes and cleans up.
• Local-speed commits. Application commits and default reads are local. Followers compare their native TRL bytes with the leader's through a lightweight poll; a mismatch restarts and rebuilds the follower.
• Independent compaction. Every node compacts locally without creating a KVI. Only the leader publishes checkpoints (native KVI written after all its files) and deletes superseded remote files after a delay.
• Rolling upgrades. A monotonic application generation and database-name set are selected with the term. A prepared newer node receives a planned lease handoff; older nodes never lead again. Added databases are initialized by the leader; removed ones continue locally on old nodes. Schema transactions detach running followers.

Projects

Documents

• Architecture: behavior, invariants, mechanisms, open work and design history.
• Hosting: how an application integrates and configures a node.
• Core APIs: the opt-in BTDB core features replication builds on.
• Object storage: the provider-neutral storage contract and Azure/S3 research.
• Testing: test harness, coverage and measurements. M1 evidence: authority clock model.
• Implementation plan: implementation status and remaining steps.
• Event log plan: design, measurements and status of the optional event log.
• AGENTS.md: working agreement for changes to this library.