Skip to content

feat(db): gcore:db Database KV — kv-types + kv-sync - #10

Closed
godronus wants to merge 2 commits into
feat/db-interfacefrom
feat/db-interface-kv
Closed

godronus wants to merge 2 commits into
feat/db-interfacefrom
feat/db-interface-kv

Conversation

@godronus

@godronus godronus commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stacked on #8 (base feat/db-interface): Database KV, the second gcore:db interface. Regional, durable and writable from the app. This is not Edge Storage (key-value, read-only, on every edge) and not cache-sync (PoP-local). First backend: Upstash Redis.

  • deps/db/kv-types.wit: kv-value (list<u8>), set-condition, set-options, op / op-result variants, op-error, error
  • deps/db/kv-sync.wit: resource database { open, get, exists, set, delete, incr, expire, batch }, blocking. Plain kv is kept for an async variant, as with sql.
  • world.wit: world reactor imports gcore:db/kv-sync@0.1.0

Contract:

  • Fixed op set, with no Redis command passthrough.
  • set takes a TTL and a condition (always / if-not-exists / if-exists), and returns whether it wrote.
  • batch is all-or-nothing, and each op sees earlier ops.
  • v1: values must be valid UTF-8.

Decisions needed

# Decision Proposal
1 Op set Fixed and small, so any future backend can implement it; compare-and-set deferred (a check op inside batch later, non-breaking)
2 batch semantics All-or-nothing (the host validates, then applies, in one Lua script). The alternative is Redis semantics: isolated, but no rollback. Implementing it is a promise for every future backend
3 Name kv-value instead of value The wit-bindgen 0.52 C generator gives option<value> one global name, so a value alias here collides with key-value's and sdk-js bindings don't compile (cache-types uses payload for the same reason)
4 UTF-8-only values in v1 Upstash's REST API can't take raw bytes inside a JSON command; lifting the restriction later doesn't change the interface
5 Consistency wording "Read-your-writes within a request; other requests see a write once it has replicated" (eventual with read replicas), not "strongly consistent"

Engine design, Upstash mapping and test results: docs/db/KV.md in G-Core/FastEdge (branch feat/db-interface-kv).

Related: #8 (base), G-Core/FastEdge#661, G-Core/FastEdge-sdk-rust#94, G-Core/FastEdge-sdk-js#158

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant