rotation: second-precision rotated filenames, int-days retention

- Rotated filename timestamp is now ISO basic at second precision
  (20260902T143000Z); the exact cutoff ts remains inside the files.
- Kanta(retention=N) accepts a plain int as number of days.
This commit is contained in:
2026-09-02 16:40:13 +00:00
parent b8285e9170
commit 3074de2950
5 changed files with 43 additions and 22 deletions
+10 -8
View File
@@ -44,15 +44,16 @@ The history that aged out is preserved at:
- The timestamp is the **ts of the last record dropped by the rotation** (see
step 4 — the leading snapshot of the rewritten main file carries the same
ts), not the current time. The name tells you exactly which point in history
the rotated file ends at. Rendered in ISO 8601 basic format with the same
microsecond precision as the record's ``ts`` in the database (e.g.
`20260902T143000.123456Z`), so the filename matches precisely the ``ts`` of
the final line of the rotated file and of the snapshot at the start of the
new file.
the rotated file ends at. Rendered in ISO 8601 basic format at second
precision (e.g. `20260902T143000Z`). The exact microsecond timestamp of the
cutoff remains available inside the file (it is the ``ts`` of the final
line of the rotated file and of the snapshot at the start of the new file);
a second rotation within the same second cannot occur because rotation
requires history to have aged past the cutoff.
- The rotated name always ends in `.kantadb`, regardless of the original
extension. Users may name their databases with no extension, `.kantadb`, or
anything else (`.db`, …). Since the rotated name is derived from the *stem*,
all of these work uniformly: `data` → `data@20260902T143000.123456Z.kantadb`,
all of these work uniformly: `data` → `data@20260902T143000Z.kantadb`,
`data.kantadb` → `data@….kantadb`, `data.db` → `data@….kantadb`.
- Rotated files live in the same directory.
- Collision: if a rotated file with the same name already exists (rotation
@@ -216,8 +217,9 @@ original `record_offset`, so binary checksums stay valid).
Add keyword options to `Kanta(...)` (`kanta/kanta.py`), surfaced through
`open()`:
- `retention: timedelta | None = None` — history window to keep. `None`
(default) disables rotation entirely; current behavior is unchanged.
- `retention: timedelta | int | None = None` — history window to keep; a plain
`int` is interpreted as a number of days. `None` (default) disables rotation
entirely; current behavior is unchanged.
- `rotate_keep: int = 3` (optional, later) — how many rotated backups to
retain; older ones are pruned at rotation time.