From 31c4ce97cfc2160daae452b12395304adb6148c0 Mon Sep 17 00:00:00 2001 From: Kate Goldenring Date: Thu, 30 Apr 2026 11:13:57 -0700 Subject: [PATCH] kv: document the limits and requirements of each kv provider Signed-off-by: Kate Goldenring Update content/v4/dynamic-configuration.md Co-authored-by: MacKenzie Adam Signed-off-by: Kate Goldenring --- content/v4/dynamic-configuration.md | 37 +++++++++++++++++++++++++++++ content/v4/kv-store-api-guide.md | 14 +++++------ 2 files changed, 44 insertions(+), 7 deletions(-) diff --git a/content/v4/dynamic-configuration.md b/content/v4/dynamic-configuration.md index 309f8fcd..cc2a765a 100644 --- a/content/v4/dynamic-configuration.md +++ b/content/v4/dynamic-configuration.md @@ -266,6 +266,15 @@ Spin creates the path and file if they don't already exist. > If, during development, you need to examine keys and values, you can open the file using `sqlite3` or another SQLite tools. However, the file format is subject to change, and you should not rely on it. +#### Limits and Requirements + +* Key size: Up to 256 bytes (UTF-8 encoded) +* Value size: Up to 1 MB +* Capacity: 1024 key value tuples +* Reads per second: unlimited +* Writes per second: unlimited +* Global replication: none + ### Redis Key Value Store Provider To use a Redis store as a backend for Spin's key-value store, set the type to `redis` and provide the URL of the Redis host: @@ -276,6 +285,15 @@ type = "redis" url = "redis://localhost" ``` +#### Limits and Requirements + +* Key size: Key/value pair size cannot exceed 128 MB +* Value size: Key/value pair size cannot exceed 128 MB +* Capacity: Unlimited key-value tuples +* Reads per second: Determined by Redis server configuration +* Writes per second: Determined by Redis server configuration +* Global replication: Depends on Redis deployment (single instance = no; Redis Cluster/Sentinel = yes) + ### Azure CosmosDB Key Value Store Provider To use an Azure CosmosDB database as a backend for Spin's key-value store, set the type to `azure_cosmos` and specify your database account details: @@ -291,6 +309,16 @@ container = "" > Note: The CosmosDB container must be created with the default partition key, `/id`. +#### Limits and Requirements + +* Key size: Up to 255 characters (Cosmos DB document id limit) +* Value size: Up to ~400 KB per item total (Cosmos DB hard limit; not validated in Spin code) +* Key syntax: Keys must NOT contain: /, \, ?, # +* Capacity: Unlimited +* Reads per second: Determined by provisioned RU/s on the Cosmos DB container +* Writes per second: Determined by provisioned RU/s on the Cosmos DB container +* Global replication: Yes (Cosmos DB supports multi-region replication) + ### AWS DynamoDB Key Value Store Provider To use an Amazon Web Services DynamoDB database as a backend for Spin's key-value store, set the type to `aws_dynamo` and specify your database account details: @@ -309,6 +337,15 @@ By default, the DynamoDB backend uses eventually consistent reads. The `consiste > Note: The DynamoDB table must be created with the partition key `PK`. It must have no sort key (so that the partition key is the primary key). +#### Limits and Requirements + +* Key size: Up to 2048 bytes +* Value size: Up to 400 KB per item +* Capacity: Unlimited +* Reads per second: Determined by DynamoDB table capacity mode (provisioned or on-demand) +* Writes per second: Determined by DynamoDB table capacity mode +* Global replication: Depends on deployment + ### Multiple and Non-Default Key-Value Stores Whilst a single default store may be sufficient for certain application use cases, each Spin application can be configured to support multiple stores of any `type`, as shown in the `runtime-config.toml` file below: diff --git a/content/v4/kv-store-api-guide.md b/content/v4/kv-store-api-guide.md index 0d7e8f45..e80c0752 100644 --- a/content/v4/kv-store-api-guide.md +++ b/content/v4/kv-store-api-guide.md @@ -16,13 +16,7 @@ Spin provides an interface for you to persist data in a key value store managed ## 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: +The Spin SDK surfaces the Spin key value store interface to your language. The set of operations is common across all SDKs: | Operation | Parameters | Returns | Behavior | |------------|------------|---------|----------| @@ -201,6 +195,12 @@ func example() error { {{ blockEnd }} +## Key Value Store Limits + +The key/value size limits and syntactic requirements of a key value store depends on which [key value store provider](./dynamic-configuration#key-value-store-runtime-configuration) your app uses. The Spin command line currently supports a [default local SQLite provider]((./dynamic-configuration#file-key-value-store-provider)), a Redis KV provider, an Azure Cosmos DB backed provider, and an AWS Dynamo DB provider. See the [key value store runtime configuration](./dynamic-configuration#key-value-store-runtime-configuration) documentation for more information about the limits and requirements of each provider. + +When you deploy your application, bear in mind that your deployment platform may have a KV provider with different characteristics from your local one! + ## 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](./dynamic-configuration#key-value-store-runtime-configuration) for details.