Key Value Store
- Using Key Value Store From Applications
- Custom Key Value Stores
- Granting Key Value Store Permissions to Components
Spin provides an interface for you to persist data in a key value store managed by Spin. This key value store allows Spin developers to persist non-relational data across application invocations. To learn more about key value store use cases and how to enable your Spin application to use a key value store, check out our key value tutorial.
Why do I need a Spin interface? Why can't I just use my own external store?
You can absolutely still use your own external store either with the Redis or Postgres APIs, or outbound HTTP. However, if you’re interested in quick, non-relational local storage without any infrastructure set-up then Spin’s key value store is a great option.
Using Key Value Store From Applications
The Spin SDK surfaces the Spin key value store interface to your language. The following characteristics are true of keys and values:
- Keys as large as 256 bytes (UTF-8 encoded)
- Values as large as 1 megabyte
- Capacity for 1024 key value tuples
The set of operations is common across all SDKs:
Operation | Parameters | Returns | Behavior |
---|---|---|---|
open | name | store | Open the store with the specified name. If name is the string “default”, the default store is opened, provided that the component that was granted access in the component manifest from spin.toml . Otherwise, name must refer to a store defined and configured in a runtime configuration file supplied with the application. |
get | store, key | value | Get the value associated with the specified key from the specified store . |
set | store, key, value | - | Set the value associated with the specified key in the specified store , overwriting any existing value. |
delete | store, key | - | Delete the tuple with the specified key from the specified store . error::invalid-store will be raised if store is not a valid handle to an open store. No error is raised if a tuple did not previously exist for key . |
exists | store, key | boolean | Return whether a tuple exists for the specified key in the specified store . |
get-keys | store | list | Return a list of all the keys in the specified store . |
close | store | - | Close the specified store . |
The exact detail of calling these operations from your application depends on your language:
Want to go straight to the reference documentation? Find it here.
Key value functions are available in the spin_sdk::key_value
module. The function names match the operations above. For example:
use anyhow::Result;
use spin_sdk::{
http::{IntoResponse, Request, Response},
http_component,
key_value::{Store},
};
#[http_component]
fn handle_request(_req: Request) -> Result<impl IntoResponse> {
let store = Store::open_default()?;
store.set("mykey", b"myvalue")?;
let value = store.get("mykey")?;
let response = value.unwrap_or_else(|| "not found".into());
Ok(Response::builder()
.status(200)
.header("content-type", "text/plain")
.body(response)
.build())
}
General Notes
set
Operation
- For set, the value argument can be of any type that implements
AsRef<[u8]>
get
Operation
- For get, the return value is of type
Option<Vec<u8>>
. If the key does not exist it returnsNone
.
open
and close
Operations
- The close operation is not surfaced; it is called automatically when the store is dropped.
set_json
and get_json
Operation
- Rust applications can store and retrieve serializable Rust types.
Want to go straight to the reference documentation? Find it here.
With Typescript, the key value functions can be accessed after opening a store using either the Kv.open
or the Kv.openDefault
methods which returns a handle to the store. For example:
import { HandleRequest, HttpRequest, HttpResponse, Kv } from "@fermyon/spin-sdk"
const encoder = new TextEncoder()
export const handleRequest: HandleRequest = async function (request: HttpRequest): Promise<HttpResponse> {
let store = Kv.openDefault()
store.set("mykey", "myvalue")
return {
status: 200,
headers: {"content-type":"text/plain"},
body: store.get("mykey") ?? encoder.encode("Key not found")
}
}
General Notes
- The spinSdk object is always available at runtime. Code checking and completion are available in TypeScript at design time if the module imports anything from the @fermyon/spin-sdk package. For example:
- The JavaScript SDK doesn’t surface the
close
operation. It automatically closes all stores at the end of the request; there’s no way to close them early.
- The result is of the type
ArrayBuffer | null
- If the key does not exist,
get
returnsnull
- The value argument is of the type
ArrayBuffer | string
.
- JavaScript and TypeScript applications can store JavaScript objects using
setJson
; these are serialized within the store as JSON. These serialized objects can be retrieved and deserialized usinggetJson
. If you callgetJson
on a key that doesn’t exist then an error is thrown (note that this is different behavior fromget
).
Want to go straight to the reference documentation? Find it here.
The key value functions are provided through the spin_key_value
module in the Python SDK. For example:
from spin_sdk import http, key_value
from spin_sdk.http import Request, Response
class IncomingHandler(http.IncomingHandler):
def handle_request(self, request: Request) -> Response:
with key_value.open_default() as store:
store.set("test", bytes("hello world!", "utf-8"))
val = store.get("test")
return Response(
200,
{"content-type": "text/plain"},
val
)
General Notes
- The Python SDK doesn’t surface the
close
operation. It automatically closes all stores at the end of the request; there’s no way to close them early.
- If a key does not exist, it returns
None
Want to go straight to the Spin SDK reference documentation? Find it here.
Key value functions are provided by the github.com/fermyon/spin/sdk/go/v2/kv
module. See Go Packages for reference documentation. For example:
import "github.com/fermyon/spin/sdk/go/v2/kv"
func example() error {
store, err := kv.OpenStore("default")
if err != nil {
return err
}
defer store.Close()
previous, err := store.Get("mykey")
return store.Set("mykey", []byte("myvalue"))
}
Custom Key Value Stores
Spin defines a key-value store named "default"
and provides automatic backing storage. If you need to customize Spin with additional stores, or to change the backing storage for the default store, you can do so via the --runtime-config-file
flag and the runtime-config.toml
file. See Key Value Store Runtime Configuration for details.
Granting Key Value Store Permissions to Components
By default, a given component of an app will not have access to any key value store. Access must be granted specifically to each component via the component manifest:
[component.example]
# Pass in 1 or more key value stores, based on how many you'd like your component to have access to
key_value_stores = ["<store 1>", "<store 2>"]
For example, a component could be given access to the default store using key_value_stores = ["default"]
.