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 add wasmcloud-interface-keyvalue


capabilities = ["wasmcloud:keyvalue"]

Basic Operations

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

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
        &SetRequest {
            key: SAMPLE_KEY.to_string(),
            value: "myvalue".to_string(),
            expires: 0,
    // 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
            &IncrementRequest {
                key: "numericalkey".to_string(),
                value: 1,
    // Return the new value

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.