Docs

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:

BackendAtomic operation
DynamoDBCondition expressions
FirestoreUpdate-time preconditions
Table StorageEntity tags (ETags)
LocalConditional 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:

LimitValue
Key1 to 512 bytes
Key charactersa-z A-Z 0-9 - _ : .
Value on Azure and Local24 KiB (24,576 bytes)
Value on AWS399 KiB (408,576 bytes)
Value on GCP765 KiB (783,360 bytes)
Scan page1,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:

PlatformPhysical deletion
AWSDynamoDB's TTL sweeper deletes expired items, typically within a few days of expiry. Expiry is stored with one-second precision.
GCPAlien doesn't configure a Firestore TTL policy. Expired documents stay until overwritten or deleted.
AzureTable Storage has no TTL. Expired entities stay until overwritten or deleted.
LocalExpired 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 limit items even when more keys match. It can even be empty while nextCursor is 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 nextCursor until 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 ttl attribute.
  • 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.

On this page