64 lines
1.8 KiB
Markdown
64 lines
1.8 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`
|
|
|
|
## 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.
|