Key-Value Store (`kv`)

The kv component is Diom’s key-value store component.

It’s disk backed, and allows storing infinite keys with values up to a few MB in size (per value).

Setting keys (`kv.set`)

When storing data in kv you need to pass the wanted key and value, and you can optionally pass additional configuration.

Some of the values you can pass to kv.set:

key: a string with the key name.
value: a byte array with the wanted value.
ttl: optional expiry time, after which the key will be deleted.
version: expected value version (see OCC section below)
behavior: how to behave on conflicts. Allowed values:
- upsert (default): update if key exists, insert if doesn’t.
- insert: fail if key exists, insert if doesn’t.
- update: update if key exists, fail if doesn’t.

Example setting a value with a 60s TTL:


import { Diom } from "diom";
import { Temporal } from "temporal-polyfill-lite";
 
const client = new Diom("AUTH_TOKEN");
await client.kv.set("my-key", new TextEncoder().encode("value goes here"), {
    behavior: "insert",
    ttl: Temporal.Duration.from({ seconds: 60 }),
});


from datetime import timedelta
from diom import Diom
from diom.models import KvSetIn, OperationBehavior
 
client = Diom("AUTH_TOKEN")
client.kv.set("my-key", b"value goes here", KvSetIn(
    behavior=OperationBehavior.INSERT,
    ttl_ms=timedelta(seconds=60),
))


use diom::{DiomClient, models::{KvSetIn, OperationBehavior}};
use std::time::Duration;
 
let client = DiomClient::new("AUTH_TOKEN".to_string(), None);
client.kv().set(
    "my-key".to_string(),
    b"value goes here".to_vec(),
    KvSetIn::new()
        .with_behavior(OperationBehavior::Insert)
        .with_ttl(Duration::from_secs(60)),
)
.await?;


import diom "diom.com/go/diom"
 
client, _ := diom.New("AUTH_TOKEN", nil)
behavior := diom.OPERATIONBEHAVIOR_INSERT
ttl := diom.DurationMs(60_000)
client.Kv().Set(ctx, "my-key", []byte("value goes here"), diom.KvSetIn{
    Behavior: &behavior,
    Ttl:      &ttl,
})


import com.svix.diom.Diom;
import com.svix.diom.models.KvSetIn;
import com.svix.diom.models.OperationBehavior;
import java.time.Duration;
 
Diom diom = new Diom("AUTH_TOKEN");
diom.kv().set("my-key", "value goes here".getBytes(),
    new KvSetIn()
        .behavior(OperationBehavior.INSERT)
        .ttl(Duration.ofSeconds(60)));


export DIOM_AUTH_TOKEN='AUTH_TOKEN'
diom kv set 'my-key' 'value goes here' '{"ttl_ms": 60000, "behavior": "insert"}'

Getting keys (`kv.get`)

Returns None when a value is not found.


const out = await client.kv.get("my-key", {});
if (out.value) {
    console.log("Got:", new TextDecoder().decode(out.value));
} else {
    console.log("Key not found");
}
console.log("Version:", out.version);


from diom.models import KvGetIn
 
out = client.kv.get("my-key", KvGetIn())
if out.value:
    print(f"Got: {out.value.decode()}")
else:
    print("Key not found")
print(f"Version: {out.version}")


let out = client.kv()
    .get(
        "my-key".to_string(),
        KvGetIn::new()
    )
    .await?;
 
match out.value {
    Some(bytes) => println!("Got: {}", String::from_utf8_lossy(&bytes)),
    None => println!("Key not found"),
}
println!("Version: {}", out.version);


out, err := client.Kv().Get(ctx, "my-key", diom.KvGetIn{})
if err != nil {
    log.Fatal(err)
}
if out.Value != nil {
    fmt.Printf("Got: %s\n", string(out.Value))
} else {
    fmt.Println("Key not found")
}
fmt.Printf("Version: %d\n", out.Version)


KvGetOut out = diom.kv().get("my-key");
if (out.getValue() != null) {
    System.out.println("Got: " + new String(out.getValue()));
} else {
    System.out.println("Key not found");
}
System.out.println("Version: " + out.getVersion());


diom kv get 'my-key'

Deleting keys (`kv.delete`)

To delete a key, call the kv.delete operation with the wanted key:


await client.kv.delete("my-key", {});


from diom.models import KvDeleteIn
 
client.kv.delete("my-key", KvDeleteIn())


client.kv().delete(
    "my-key".to_string(),
    KvDeleteIn::new()
)
.await?;


client.Kv().Delete(ctx, "my-key", diom.KvDeleteIn{})


diom.kv().delete("my-key");


diom kv delete 'my-key'

Optimistic concurrency control (OCC)

Diom supports optimistic concurrency control as a way to ensure data consistency. This is achieved using the version parameter that’s supported by both kv.set and kv.delete.

The way it works is that when you fetch a key, you get a version identifier in addition to the value. You can then pass this version to subsequent calls to kv.set and kv.delete to ensure that the key hasn’t been written to since you last read the value.

Example code:


import { Temporal } from "temporal-polyfill-lite";
 
const key = "test-key";
 
// Set the key. Pass version 0 to enforce the key isn't already set.
await client.kv.set(key, new TextEncoder().encode("value 1"), { version: 0 });
 
// Get the value back
const out = await client.kv.get(key, {});
console.log("Got:", new TextDecoder().decode(out.value!));
console.log("Version:", out.version);
 
// Conditional write using the version token
await client.kv.set(key, new TextEncoder().encode("updated value"), { version: out.version });
 
// This write will fail, as version is stale.
await client.kv.set(key, new TextEncoder().encode("write will fail"), { version: out.version });
 
// This delete will fail, as version is stale.
await client.kv.delete(key, { version: out.version });


from diom.models import KvSetIn, KvGetIn, KvDeleteIn
 
key = "test-key"
 
# Set the key. Pass version 0 to enforce the key isn't already set.
client.kv.set(key, b"value 1", KvSetIn(version=0))
 
# Get the value back
out = client.kv.get(key, KvGetIn())
print(f"Got: {out.value.decode()}")
print(f"Version: {out.version}")
 
# Conditional write using the version token
client.kv.set(key, b"updated value", KvSetIn(version=out.version))
 
# This write will fail, as version is stale.
client.kv.set(key, b"write will fail", KvSetIn(version=out.version))
 
# This delete will fail, as version is stale.
client.kv.delete(key, KvDeleteIn(version=out.version))


let key = "test-key";
 
// Set the key. Pass 0 as the version to enforce the key isn't already set.
client.kv().set(
    key.to_string(),
    b"value 1".to_vec(),
    KvSetIn::new().with_version(0),
)
.await?;
 
// Get the value back
let out = client.kv()
    .get(key.to_string(), KvGetIn::new())
    .await?;
 
match out.value {
    Some(bytes) => println!("Got: {}", String::from_utf8_lossy(&bytes)),
    None => println!("Key not found"),
}
println!("Version: {}", out.version);
 
// Conditional write using the version token
client.kv().set(
    key.to_string(),
    b"updated value".to_vec(),
    KvSetIn::new().with_version(out.version),
)
.await?;
 
// This write will fail, as version is stale.
client.kv().set(
    key.to_string(),
    b"write will fail".to_vec(),
    KvSetIn::new().with_version(out.version),
)
.await?;
 
// This delete will fail, as version is stale.
client.kv().delete(
    key.to_string(),
    KvDeleteIn::new().with_version(out.version),
)
.await?;


key := "test-key"
 
// Set the key. Pass version 0 to enforce the key isn't already set.
version0 := uint64(0)
client.Kv().Set(ctx, key, []byte("value 1"), diom.KvSetIn{Version: &version0})
 
// Get the value back
out, _ := client.Kv().Get(ctx, key, diom.KvGetIn{})
fmt.Printf("Got: %s\n", string(out.Value))
fmt.Printf("Version: %d\n", out.Version)
 
// Conditional write using the version token
client.Kv().Set(ctx, key, []byte("updated value"), diom.KvSetIn{Version: &out.Version})
 
// This write will fail, as version is stale.
client.Kv().Set(ctx, key, []byte("write will fail"), diom.KvSetIn{Version: &out.Version})
 
// This delete will fail, as version is stale.
client.Kv().Delete(ctx, key, diom.KvDeleteIn{Version: &out.Version})


String key = "test-key";
 
// Set the key. Pass version 0 to enforce the key isn't already set.
diom.kv().set(key, "value 1".getBytes(), new KvSetIn().version(0L));
 
// Get the value back
KvGetOut out = diom.kv().get(key);
System.out.println("Got: " + new String(out.getValue()));
System.out.println("Version: " + out.getVersion());
 
// Conditional write using the version token
diom.kv().set(key, "updated value".getBytes(), new KvSetIn().version(out.getVersion()));
 
// This write will fail, as version is stale.
diom.kv().set(key, "write will fail".getBytes(), new KvSetIn().version(out.getVersion()));
 
// This delete will fail, as version is stale.
diom.kv().delete(key, new KvDeleteIn().version(out.getVersion()));


# Set the key with version 0 (enforce key doesn't exist)
diom kv set 'test-key' 'value 1' '{"version": 0}'
 
# Get the value back (note the version in the response)
diom kv get 'test-key'
 
# Conditional write using the version from the get response
diom kv set 'test-key' 'updated value' '{"version": 1}'
 
# Delete with version check
diom kv delete 'test-key' '{"version": 2}'

Key-Value Store (kv)

Setting keys (kv.set)

Getting keys (kv.get)

Deleting keys (kv.delete)

Optimistic concurrency control (OCC)

Key-Value Store (`kv`)

Setting keys (`kv.set`)

Getting keys (`kv.get`)

Deleting keys (`kv.delete`)