Skip to main content

Key-Value Store

The key-value store capability allows your application component to store, retrieve, and manage data as key-value pairs. This enables flexible, persistent data storage for applications that can range from short-lived data for quick access to long-lived data that you manage as your application runs. This capability is included as one of the open source wasmCloud interfaces and has the capability contract ID wasmcloud:keyvalue.

Using this Capability​

This capability can be used in your project by adding a dependency on the wasmcloud-interface-keyvalue crate, and by adding wasmcloud:keyvalue to the capabilities section in your application's wasmcloud.toml file.

Cargo.toml

toml
wasmcloud-interface-keyvalue = "0.9.1"
toml
wasmcloud-interface-keyvalue = "0.9.1"

wasmcloud.toml

toml
[actor]
capabilities = ["wasmcloud:keyvalue"]
toml
[actor]
capabilities = ["wasmcloud:keyvalue"]

Basic Operations​

OperationInputOutput
getString, &str, or anything implementing ToStringGetResponse
setSetRequestResult that indicates success or failure
delString, &str, or anything implementing ToStringBoolean, true if deleted
containsString, &str, or anything implementing ToStringBoolean, true if the key exists
incrementIncrementRequestThe number of the new value

Advanced Operations​

Operations pertaining to list operations, set queries, unions, intersections, and more can be found on the wasmcloud-interface-keyvalue library page.

Example Usage​

rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_keyvalue::{IncrementRequest, KeyValue, KeyValueSender, SetRequest};
const SAMPLE_KEY: &str = "mykey";
async fn keyvalue_sample(ctx: &Context) -> RpcResult<i32> {
    // Create the communication sender to a key-value store
    let kv = KeyValueSender::new();
    // Set a key in the store
    kv.set(
        ctx,
        &SetRequest {
            key: SAMPLE_KEY.to_string(),
            value: "myvalue".to_string(),
            expires: 0,
        },
    )
    .await?;
    // Get a key from the store
    let get_resp = kv.get(ctx, SAMPLE_KEY).await?;
    assert_eq!(get_resp.value, "myvalue".to_string());
    // See if a key is contained in the store
    assert!(kv.contains(ctx, SAMPLE_KEY).await?);
    // Increment some `key` by 1
    let new_value = kv
        .increment(
            ctx,
            &IncrementRequest {
                key: "numericalkey".to_string(),
                value: 1,
            },
        )
        .await?;
    // Return the new value
    Ok(new_val)
}
rust
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_keyvalue::{IncrementRequest, KeyValue, KeyValueSender, SetRequest};
const SAMPLE_KEY: &str = "mykey";
async fn keyvalue_sample(ctx: &Context) -> RpcResult<i32> {
    // Create the communication sender to a key-value store
    let kv = KeyValueSender::new();
    // Set a key in the store
    kv.set(
        ctx,
        &SetRequest {
            key: SAMPLE_KEY.to_string(),
            value: "myvalue".to_string(),
            expires: 0,
        },
    )
    .await?;
    // Get a key from the store
    let get_resp = kv.get(ctx, SAMPLE_KEY).await?;
    assert_eq!(get_resp.value, "myvalue".to_string());
    // See if a key is contained in the store
    assert!(kv.contains(ctx, SAMPLE_KEY).await?);
    // Increment some `key` by 1
    let new_value = kv
        .increment(
            ctx,
            &IncrementRequest {
                key: "numericalkey".to_string(),
                value: 1,
            },
        )
        .await?;
    // Return the new value
    Ok(new_val)
}

Choosing an Implementation​

After you've written your component to use the key-value capability, you will choose an implementation, or capability provider, at runtime to connect to a real key-value database. Depending on what your application requirements are, you could choose to use the Cosmonic-managed key-value store for a managed experience, or use an external data store for more control over the database itself.

Available Implementations

Below you can find the different implementations of key-value stores that you can use out-of-the-box. If the options don't meet your needs, you can always implement the wasmcloud:keyvalue interface with your own implementation, please reach out to us on Discord so we can collaborate with you on a solution.