KV behavior and limits
What a KV store guarantees on every platform, its limits, and how each cloud's backing service differs.
Guarantees
Strong single-key consistency. A get after a successful set on the same key returns the new value. Alien uses strongly consistent DynamoDB reads; Firestore is strongly consistent, and Table Storage is strongly consistent within its region.
Atomic conditional writes. set and delete with ifVersion are atomic on every platform. When two callers race on the same key, exactly one wins and the other gets false. Locks, idempotency checks, and read-modify-write loops are safe.
Idempotent deletes. An unconditional delete of a missing key succeeds.
Durability. Each cloud replicates the data. DynamoDB and Firestore replicate across zones in the region. Table Storage uses the stack's storage account, which is locally redundant (three copies in one datacenter).
On Kubernetes, the guarantees are those of the service in the external binding.
Versions and conditional writes
Every read (get, getText, getJson, scan) returns an opaque version with the value. It changes on every applied write.
- Create if absent:
set(key, value, { ifVersion: null })writes only when the key is absent or expired. Of several concurrent creators, exactly one succeeds. - Compare and set:
set(key, value, { ifVersion: entry.version })replaces the value only if the key still has that version. - Compare and delete:
delete(key, { ifVersion: entry.version })deletes only if the key is unchanged.
A failed condition resolves false and writes nothing. It isn't an error.
Rules for versions:
- A version is bound to the key it was read from. Passing a version from another key fails with
INVALID_INPUT. - Don't parse, compare, or store versions. Their only use is passing one back as
ifVersion. - A version read from an entry that has since expired never matches, because conditions treat expired keys as absent.
Alien maps each condition onto the backend's own atomic operation, with no client-side locking:
| Backend | Atomic operation |
|---|---|
| DynamoDB | Condition expressions |
| Firestore | Update-time preconditions |
| Table Storage | Entity tags (ETags) |
| Local | Conditional update in the local database |
When a key has expired but its row still exists, a create-if-absent write takes over the row. That write is conditioned on the expired row's version, so a racing writer can't be overwritten.
Limits
Alien checks these before calling the backend, and rejects violations with INVALID_INPUT:
| Limit | Value |
|---|---|
| Key | 1 to 512 bytes |
| Key characters | a-z A-Z 0-9 - _ : . |
| Value on Azure and Local | 24 KiB (24,576 bytes) |
| Value on AWS | 399 KiB (408,576 bytes) |
| Value on GCP | 765 KiB (783,360 bytes) |
| Scan page | 1,000 items by default |
For code that runs on every platform, keep values under 24 KiB.
TTL
A TTL is a hint for cleanup, not a deletion schedule. Once a key's expiry passes, reads treat it as absent: get returns null, exists returns false, and scan skips it.
When the stored row is actually deleted depends on the platform:
| Platform | Physical deletion |
|---|---|
| AWS | DynamoDB's TTL sweeper deletes expired items, typically within a few days of expiry. Expiry is stored with one-second precision. |
| GCP | Alien doesn't configure a Firestore TTL policy. Expired documents stay until overwritten or deleted. |
| Azure | Table Storage has no TTL. Expired entities stay until overwritten or deleted. |
| Local | Expired rows are deleted when read. |
Don't rely on storage being reclaimed at a particular time.
Scan
Scan is deliberately weak so it behaves the same on every backend:
- Unordered. Items come in the backend's natural order. On DynamoDB and Table Storage the store is spread over 16 partitions, so results are grouped by partition, not by key.
- Short pages. A page can hold fewer than
limititems even when more keys match. It can even be empty whilenextCursoris still set, for example when entries expired between pages. - Duplicates. A key can appear on more than one page. De-duplicate on the client.
- Not a snapshot. Concurrent writes may or may not appear.
- Complete without concurrent writes. If nothing changes during the scan, following every
nextCursoruntil it's absent visits every matching, unexpired key. - Cursors are short-lived. A cursor is bound to its prefix, can stop working after the data changes, and has no guaranteed lifetime. Don't persist or share it.
- Invalid cursors fail. An invalid cursor returns an error, not partial results.
Per-cloud details
AWS (DynamoDB)
- On-demand (pay-per-request) capacity. No capacity planning.
- Keys are spread over 16 hash buckets in the partition key, so traffic to similar keys doesn't land on one partition.
- TTL is enabled on the table's
ttlattribute. - Tables that the setup template creates have server-side encryption and point-in-time recovery turned on.
- A DynamoDB partition serves up to 3,000 read units and 1,000 write units per second. Spreading keys over buckets keeps a single hot prefix from hitting that limit.
GCP (Firestore)
- Each KV resource is a collection in the project's
(default)Firestore database. Alien creates the database if the project doesn't have one. - Firestore is strongly consistent.
- New collections start at about 500 writes per second and scale by 50% every 5 minutes under sustained load.
- No TTL policy; see TTL.
Azure (Table Storage)
- Each KV resource is a table in the stack's storage account. Keys are spread over 16 partitions.
- No native TTL. Alien filters expired entities on read but never deletes them.
- A partition serves up to 2,000 entities per second.
- Table Storage limits a property to 64 KiB. Values are base64-encoded and stored as UTF-16, which is why the value limit is 24 KiB.
Kubernetes
Alien creates nothing. Point each KV resource at DynamoDB, Firestore, or Table Storage in the Helm values. The limits above still apply.
Local
- An embedded database file,
localkv.sqlite, in the local data directory. Data survives restarts, and several processes can share it. - Expired rows are deleted when read.
- Scan returns keys in sorted order. Don't rely on that; the cloud backends don't.
Design decisions
512-byte keys. DynamoDB sort keys and Table Storage row keys allow 1,024 bytes and Firestore document IDs 1,500. 512 bytes fits all of them.
Restricted key characters. Table Storage rejects /, \, #, ?, and control characters in keys, and other characters cause encoding problems across backends. One character set everywhere means a key that works locally works in every cloud.
Per-platform value limits. Each backend accepts what fits its own item or document size, after encoding. The 24 KiB Azure limit is the portable floor. Store larger objects in Storage and keep a pointer in KV.
Opaque versions. Versions wrap each backend's own concurrency token. Keeping them opaque lets conditional writes use native atomic operations instead of an extra version column or a lock.