abstract-level icon indicating copy to clipboard operation
abstract-level copied to clipboard

Define explicit snapshots

Open vweevers opened this issue 3 years ago • 0 comments

This is a documentation-only PR, acting as an RFC. I opted for a token-based approach (as suggested by Rod Vagg in https://github.com/Level/community/issues/45) instead of a dedicated snapshot API surface (as suggested by @juliangruber in https://github.com/Level/community/issues/47). Main reasons for not choosing the latter:

  • It would be a third API surface. We have the main database API surface which is roughly equal to that of a sublevel, and would now add another API surface which only has read methods, e.g. db.snapshot().get(). If you could pass around a snapshot as if it was a regular database (like you can with sublevels) then I'd be cool with it. But for that to happen, we'd have to implement write methods and thus transactions as well, which I consider to be out of scope although transactions are in fact a use case of snapshots.
  • It would have a higher complexity once you factor in sublevels. I.e. to make db.sublevel().snapshot().get(key) read from the snapshot but also prefix the given key. By instead doing db.sublevel().get(key, { snapshot }), the sublevel can just forward that snapshot option to its parent database.
  • Furthermore, with the token-based approach, you can pass a snapshot to multiple sublevels, which cleanly solves the main use case of retrieving data from an index (see example).

I renamed the existing snapshot mechanism to "implicit snapshots" and attempted to clarify the behavior of those as well.

Several related issues can be closed, because this PR:

  • Includes (a more complete write-up than) https://github.com/Level/classic-level/pull/40.
  • Mentions https://github.com/Level/leveldown/issues/796 (which should be moved rather than closed).
  • Answers https://github.com/Level/classic-level/issues/28.
  • Solves the main use case as described in https://github.com/Level/leveldown/issues/486.
  • Effectively completes https://github.com/Level/awesome/issues/19.

vweevers avatar Sep 25 '22 18:09 vweevers