81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
|
# Date-Range Backup Spec
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
- Draft only.
|
||
|
|
- Do not implement until full-backup import/export has been exercised in real usage.
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
|
||
|
|
Allow users to export and import only a selected time range without weakening the safety guarantees introduced by full JSON backups.
|
||
|
|
|
||
|
|
## Non-goals
|
||
|
|
|
||
|
|
- No implementation in this change.
|
||
|
|
- No automatic migration across JSON backup format versions.
|
||
|
|
- No merging logic for conflicting edits yet.
|
||
|
|
|
||
|
|
## Proposed backup modes
|
||
|
|
|
||
|
|
- `full`: current behavior, exports every managed collection and can fully replace the database.
|
||
|
|
- `dateRange`: future behavior, exports only documents relevant to a user-selected inclusive date interval.
|
||
|
|
|
||
|
|
## Proposed JSON shape changes
|
||
|
|
|
||
|
|
Add a top-level `scope` object while keeping the existing version markers.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"backupFormatVersion": 1,
|
||
|
|
"databaseSchemaVersion": 1,
|
||
|
|
"exportedAtUtc": "2026-04-24T12:00:00Z",
|
||
|
|
"scope": {
|
||
|
|
"mode": "full"
|
||
|
|
},
|
||
|
|
"collections": {
|
||
|
|
"app_settings": [],
|
||
|
|
"users": [],
|
||
|
|
"workdays": []
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Future date-range backups would use:
|
||
|
|
|
||
|
|
```json
|
||
|
|
"scope": {
|
||
|
|
"mode": "dateRange",
|
||
|
|
"from": "2026-04-01",
|
||
|
|
"to": "2026-04-30"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Selection rules for `dateRange`
|
||
|
|
|
||
|
|
- `workdays`: include documents whose logical day falls within `from` and `to` inclusive.
|
||
|
|
- `app_settings`: exclude by default. Settings are global, not time-scoped.
|
||
|
|
- `users`: exclude by default. Authentication data is global, not time-scoped.
|
||
|
|
- Future collections must declare whether they are `global`, `timeScoped`, or `derived` before they participate in range backups.
|
||
|
|
|
||
|
|
## Import semantics for `dateRange`
|
||
|
|
|
||
|
|
- Import must not reuse the current full-overwrite flow.
|
||
|
|
- Import must require a different confirmation message than full restore.
|
||
|
|
- Import must define conflict rules before implementation.
|
||
|
|
- Preferred first version: replace only the selected date range inside time-scoped collections.
|
||
|
|
- Global collections must remain untouched unless explicitly opted in by the user and supported by the backup format version.
|
||
|
|
|
||
|
|
## Compatibility and versioning requirements
|
||
|
|
|
||
|
|
- Keep `backupFormatVersion` and `databaseSchemaVersion` mandatory for every backup mode.
|
||
|
|
- If `scope.mode` is unknown, reject import.
|
||
|
|
- If `backupFormatVersion` is unsupported, reject import and surface that a migration/importer is required.
|
||
|
|
- If `databaseSchemaVersion` is unsupported, reject import and surface that a schema migration is required.
|
||
|
|
- When date-range import is implemented, version-specific import handlers should be introduced behind a dispatch layer such as `ImportV1Full`, `ImportV1DateRange`, and future `ImportV2*` handlers.
|
||
|
|
|
||
|
|
## UI requirements for future work
|
||
|
|
|
||
|
|
- Add date pickers for `from` and `to`.
|
||
|
|
- Validate `from <= to` before export/import is enabled.
|
||
|
|
- Show a summary of what will be affected before confirming import.
|
||
|
|
- Keep full-backup export/import available as the safer recovery path.
|