Merge pull request #209 from kate-goldenring/kv-provider-limits

kv: document the limits and requirements of each kv provider

Author: kate-goldenring

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 = "<cosmos-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:

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.