CBDD

CBDD is an embedded, document-oriented database engine for .NET 10. It targets internal platform teams that need predictable ACID behavior, low-latency local persistence, and typed access patterns without running an external database server.

Purpose And Business Context

CBDD provides a local data layer for services and tools that need transactional durability, deterministic startup, and high-throughput reads/writes. The primary business outcome is reducing operational overhead for workloads that do not require a networked database cluster.

Ownership And Support

• Owning team: CBDD maintainers (repository owner: @dohertj2)
• Primary support path: open a Gitea issue in this repository with labels incident or bug
• Escalation path: follow docs/runbook.md and page the release maintainer listed in the active release PR

Architecture Overview

CBDD has four primary layers:

1. Storage and transaction engine (src/CBDD.Core/Storage, src/CBDD.Core/Transactions)
2. BSON serialization (src/CBDD.Bson)
3. Indexing and query execution (src/CBDD.Core/Indexing, src/CBDD.Core/Query)
4. Source-generated mapping (src/CBDD.SourceGenerators)

Detailed architecture material:

• docs/architecture.md
• RFC.md
• C-BSON.md

Prerequisites

• .NET SDK 10.x
• Bash (for repository scripts)
• Read/write permissions for the local working directory
• Gitea access for pull requests and release publishing

Setup And Local Run

1. Clone the repository.

git clone https://gitea.dohertylan.com/dohertj2/CBDD.git
cd CBDD

Expected outcome: local repository checkout with CBDD.slnx present.

2. Restore dependencies.

dotnet restore

Expected outcome: restore completes without package errors.

3. Build the solution.

dotnet build CBDD.slnx -c Release

Expected outcome: solution builds without compiler errors.

4. Run tests.

dotnet test CBDD.slnx -c Release

Expected outcome: all tests pass.

5. Run the full repository fitness check.

bash scripts/fitness-check.sh

Expected outcome: format, build, tests, coverage threshold, and package checks complete.

Configuration And Secrets

• Default local usage requires only a filesystem path for the database file.
• Do not commit secrets in source, test fixtures, benchmark assets, or .env files.
• If publishing packages, keep feed credentials in CI secrets or local keychain-backed credential storage.
• Store environment-specific values outside the repository and inject them at runtime.

Build, Test, And Quality Gates

Required pre-merge commands:

dotnet format --verify-no-changes
dotnet build -t:Rebuild
dotnet test
bash scripts/coverage-check.sh

Optional full gate:

bash scripts/fitness-check.sh

Deployment And Rollback

CBDD is released as an internal package.

• Deployment workflow: docs/deployment.md
• Rollback workflow: docs/deployment.md#rollback-procedure

Operations And Incident Response

Operational procedures, diagnostics, and escalation are documented in:

• docs/runbook.md
• docs/troubleshooting.md

Checkpoint Modes

DocumentDbContext and StorageEngine support explicit checkpoint modes via CheckpointMode:

• Passive: non-blocking; skips if checkpoint lock is contended.
• Full: applies committed WAL pages and appends a checkpoint marker, without truncating WAL.
• Truncate: applies committed WAL pages and truncates WAL.
• Restart: truncate + WAL writer restart.

Example:

using ZB.MOM.WW.CBDD.Core.Transactions;

var result = db.Checkpoint(CheckpointMode.Full);
if (!result.Executed)
{
    // passive checkpoint can be skipped under contention
}

Security And Compliance Posture

• CBDD relies on host and process-level access controls.
• Sensitive payload classification and handling requirements are defined in docs/security.md.
• Role and approval requirements are defined in docs/access.md.

Troubleshooting

Common issues and remediation:

• Build/test environment failures: docs/troubleshooting.md#build-and-test-failures
• Data-file recovery procedures: docs/troubleshooting.md#data-file-and-recovery-issues
• Query/index behavior verification: docs/troubleshooting.md#query-and-index-issues

Change Governance

• Use feature branches from main.
• Open pull requests with at least one reviewer approval before merge.
• Keep release notes in pull request descriptions and tagged release notes.
• Run documented quality gates before requesting review.

Documentation Index

• Documentation home: docs/README.md
• Major feature inventory: docs/features/README.md
• Architecture decisions: docs/adr/0001-storage-engine-and-source-generation.md