82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# Storage And Transactions
|
|
|
|
## Purpose And Business Outcome
|
|
|
|
Provide durable, ACID-compliant local persistence for embedded workloads that need consistent commit and recovery semantics.
|
|
|
|
## Scope And Non-Goals
|
|
|
|
Scope:
|
|
- Page-based storage
|
|
- Write-ahead logging
|
|
- Transaction lifecycle and commit/rollback semantics
|
|
|
|
Non-goals:
|
|
- Distributed transactions
|
|
- Multi-node replication
|
|
|
|
## User And System Workflows
|
|
|
|
1. Application writes through `DocumentDbContext`.
|
|
2. Engine records WAL entries.
|
|
3. Commit persists pages and marks transaction durable.
|
|
4. Recovery replays WAL to restore committed state after restart.
|
|
|
|
## Interfaces And APIs
|
|
|
|
- `DocumentDbContext`
|
|
- `Transaction` and `ITransaction`
|
|
- `WriteAheadLog`
|
|
- Storage engine modules under `src/CBDD.Core/Storage`
|
|
|
|
Checkpoint APIs:
|
|
- `DocumentDbContext.Checkpoint(CheckpointMode mode = CheckpointMode.Truncate)`
|
|
- `DocumentDbContext.CheckpointAsync(CheckpointMode mode = CheckpointMode.Truncate, CancellationToken ct = default)`
|
|
- `StorageEngine.Checkpoint(CheckpointMode mode)`
|
|
- `StorageEngine.CheckpointAsync(CheckpointMode mode, CancellationToken ct = default)`
|
|
|
|
Checkpoint modes:
|
|
- `Passive`: non-blocking best-effort checkpoint. Returns `Executed = false` when lock is contended.
|
|
- `Full`: applies committed WAL pages and appends a WAL checkpoint marker without truncating WAL.
|
|
- `Truncate`: applies committed WAL pages and truncates WAL (default behavior).
|
|
- `Restart`: same as truncate, then reinitializes WAL writer session.
|
|
|
|
Usage guidance:
|
|
- Use `Passive` for background/low-priority maintenance where latency matters more than immediate WAL cleanup.
|
|
- Use `Full` when you want durable page-file sync but prefer to preserve WAL history until a later truncate.
|
|
- Use `Truncate` for routine manual checkpoints and disk-space recovery.
|
|
- Use `Restart` for aggressive maintenance boundaries (for example after incident remediation flows).
|
|
|
|
## Permissions And Data Handling
|
|
|
|
- Database files require host-managed filesystem access controls.
|
|
- Transaction data should be treated as sensitive if payloads contain regulated information.
|
|
|
|
## Dependencies And Failure Modes
|
|
|
|
Dependencies:
|
|
- Local filesystem I/O
|
|
- WAL and page file consistency
|
|
|
|
Failure modes:
|
|
- Interrupted writes
|
|
- Corrupted WAL entries
|
|
- Invalid page metadata after unsafe process termination
|
|
|
|
## Monitoring, Alerts, And Troubleshooting
|
|
|
|
- Use CI/test failures and incident issues as primary signals.
|
|
- Follow [`../runbook.md`](../runbook.md) for triage.
|
|
- Follow [`../security.md`](../security.md) for data handling and control requirements.
|
|
- Use [`../troubleshooting.md`](../troubleshooting.md#data-file-and-recovery-issues) for recovery issues.
|
|
|
|
## Rollout And Change Considerations
|
|
|
|
- Any storage format or WAL behavior change requires migration and rollback validation.
|
|
- Release notes must document backward compatibility impact.
|
|
|
|
## Validation Guidance
|
|
|
|
- Run transaction and recovery tests in `tests/CBDD.Tests`.
|
|
- Execute `dotnet test CBDD.slnx -c Release` before merge.
|