Skip to main content

Key Value Store

Overview​

The Key-Value Store in RelayX provides a simple way to persist and retrieve small pieces of state that need to be shared across parts of your system.

It is designed for configuration, flags, counters, metadata, and other lightweight state that must be available quickly and consistently. It is not a database and does not provide querying, indexing, or transactions.

Before performing any key-value operations, the Key-Value Store must be explicitly initialized. All reads and writes happen through the initialized store handle.

How This Works​

The Key-Value Store is scoped to your RelayX account.

When you initialize the store, the SDK establishes access permissions and prepares a client-side handle. All operations are executed directly against the RelayX backend.

Writes overwrite existing values. Reads return the most recent value. Deletes permanently remove keys.

There is no versioning, no history, and no conflict resolution beyond last-write-wins.

Success for an operation means the backend has accepted the request and applied it.

Initializing the Key-Value Store​

Before using the Key-Value Store, you must initialize it from a connected client.

const kvStore = await client.initKVStore();

This returns a Key-Value Store handle that exposes all KV operations.

Initialization may fail if the client is not connected or does not have KV permissions.

Creating or Updating a Key​

API Usage​

await kvStore.put(key, value);

Key Rules​

  • Must be a string
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Value Rules​

Values may be:

  • String
  • Number
  • Boolean
  • Object (JSON)
  • Array
  • Null

If the key does not exist, it is created.

If the key already exists, the previous value is overwritten.

The method does not return anything.

Errors​

put() throws an error if:

  • The key is invalid
  • The value type is unsupported
  • The client does not have write permission

Example​

await kvStore.put("config.maxRetries", 5);
await kvStore.put("featureFlags.newUI", true);
await kvStore.put("service.metadata", { region: "ap-south-1" });

Getting a Value​

API Usage​

const value = await kvStore.get(key);

The method returns the stored value for the given key.

Key Rules​

  • Must be a string
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Errors​

get() throws an error if:

  • The key is invalid
  • The client does not have read permission

Example​

const retries = await kvStore.get("config.maxRetries");
console.log(retries);

Deleting a Key​

API Usage​

await kvStore.delete(key);

Deletes the key permanently from the Key-Value Store.

The method does not return anything.

Key Rules​

  • Must be a string
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Errors​

delete() throws an error if:

  • The key is invalid
  • The client does not have write permission

Example​

await kvStore.delete("featureFlags.newUI");

Listing All Keys​

API Usage​

const keys = await kvStore.keys();

Returns an array of strings representing all keys currently stored.

Errors​

keys() throws an error if:

  • The client does not have read permission

Example​

const allKeys = await kvStore.keys();
console.log(allKeys);

Common Mistakes​

  • Assuming values are versioned or transactional
  • Using the KV Store as a database
  • Writing large payloads
  • Ignoring permission errors

Notes & Limitations​

  • Last-write-wins behavior
  • No TTL or expiry
  • No atomic operations
  • No partial updates
  • Intended for small, shared state only


Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️