Document storage.blobRetention - #622
Conversation
New in harper#2145: how long a superseded blob file is kept on disk so an in-flight read (or a replication peer that has not fetched it yet) can still get the bytes, and the disk cost of widening it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for the storage.blobRetention configuration option in reference/database/storage-tuning.md. The feedback suggests adding a version badge under the heading to indicate when this configuration option was introduced, aligning with the repository's documentation guidelines.
| Blobs are not relocated when `blobPaths` changes — only new blobs honor the updated configuration. Existing blob references continue to resolve at their original path. | ||
|
|
||
| ### `storage.blobRetention` | ||
|
|
There was a problem hiding this comment.
According to the repository's guidelines, we should include a version badge when documenting new configuration options or behavior changes to indicate when they were introduced. Please add the appropriate <VersionBadge type="changed" version="v5.2.0" /> under the heading.
| <VersionBadge type="changed" version="v5.2.0" /> | |
References
- Use the
<VersionBadge type="changed" version="vX.Y.0" />format when documenting behavior changes to existing surface, as prescribed in the repository's guidelines.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-622 This preview will update automatically when you push new commits. |
1 participant
Documents
storage.blobRetention, the new config option added in HarperFast/harper#2145.The option controls how long a superseded blob file stays on disk. The section explains why the window exists (blob bytes are read lazily, so a request that resolved a record just before it was overwritten opens the file afterwards — and the resulting failure lands after the response headers are committed, so the client sees a truncated body rather than an error), when to raise it (large blobs, slow clients, a cache table rewritten while being served, replication lag), and what it costs (write rate × window of superseded bytes on disk, plus a wider window for files orphaned by an abrupt exit).
Placed in
reference/database/storage-tuning.mdnext tostorage.blobPaths, matching the surrounding option format.Verification
Prose-only change to an existing reference page; no build run —
npx prettiercannot run in this worktree (@harperfast/code-guidelinesis not installed), so formatting was matched to the surrounding sections by hand. Worth a docs-site preview check before merge.For the human reviewer
One judgment call: I documented the replication-lag guidance ("a cluster with significant replication lag wants a value comfortably above that lag") as a real tuning lever. That is accurate for the current design but is exactly the workaround that lag-aware retention would remove — if harper#2145's judgment call 1 goes the other way, this paragraph should be revisited rather than kept.
🤖 Generated by Claude (claude-opus-5)