From 6eacfa9424ade7fc127b7e535a1ab2eda5fa7174 Mon Sep 17 00:00:00 2001 From: Bernd Verst Date: Tue, 20 Jul 2021 09:28:35 -0700 Subject: [PATCH] Document State Store Support for TTL (#1626) * Document Support for TTL support in state stores * Fix table * State Store TTL concept page * add links to column headers * Update daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md Co-authored-by: Aaron Crawfis * Update daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md Co-authored-by: Aaron Crawfis * Update daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md Co-authored-by: Aaron Crawfis * Update daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md Co-authored-by: Aaron Crawfis Co-authored-by: Aaron Crawfis --- .../state-management/state-store-ttl.md | 101 ++++++++++++++++++ .../supported-state-stores/_index.md | 54 +++++----- 2 files changed, 128 insertions(+), 27 deletions(-) create mode 100644 daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md new file mode 100644 index 000000000..ddadfb8dd --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-store-ttl.md @@ -0,0 +1,101 @@ +--- +type: docs +title: "State Time-to-Live (TTL)" +linkTitle: "State TTL" +weight: 500 +description: "Manage state with time-to-live." +--- + +## Introduction + +Dapr enables per state set request time-to-live (TTL). This means that applications can set time-to-live per state stored, and these states cannot be retrieved after expiration. + +Only a subset of Dapr [state store components]({{< ref supported-state-stores >}}) are compatible with state TTL. For supported state stores simply set the `ttlInSeconds` metadata when publishing a message. Other state stores will ignore this value. + +Some state stores can specify a default expiration on a per-table/container basis. Please refer to the official documentation of these state stores to utilize this feature of desired. Dapr support per-state TTLs for supported state stores. + +## Native state TTL support + +When state time-to-live has native support in the state store component, Dapr simply forwards the time-to-live configuration without adding any extra logic, keeping predictable behavior. This is helpful when the expired state is handled differently by the component. +When a TTL is not specified the default behavior of the state store is retained. + +## Persisting state (ignoring an existing TTL) + +To explictly persist a state (ignoring any TTLs set for the key), specify a `ttlInSeconds` value of `-1`. + +## Supported components + +Please refer to the TTL column in the tables at [state store components]({{< ref supported-state-stores >}}). + +## Example + +State TTL can be set in the metadata as part of the state store set request: + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK" "PHP SDK">}} + +{{% codetab %}} + +```bash +curl -X POST -H "Content-Type: application/json" -d '[{ "key": "key1", "value": "value1", "metadata": { "ttlInSeconds": "120" } }]' http://localhost:3500/v1.0/state/statestore +``` + +{{% /codetab %}} + +{{% codetab %}} + +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{"key": "key1", "value": "value1", "metadata": {"ttlInSeconds": "120"}}]' -Uri 'http://localhost:3500/v1.0/state/statestore' +``` + +{{% /codetab %}} + +{{% codetab %}} + +```python +from dapr.clients import DaprClient + +with DaprClient() as d: + d.save_state( + store_name="statestore", + key="myFirstKey", + value="myFirstValue", + metadata=( + ('ttlInSeconds', '120') + ) + ) + print("State has been stored") + +``` + +{{% /codetab %}} + +{{% codetab %}} + +Save the following in `state-example.php`: + +```php +run(function(\Dapr\State\StateManager $stateManager, \Psr\Log\LoggerInterface $logger) { + $stateManager->save_state(store_name: 'statestore', item: new \Dapr\State\StateItem( + key: 'myFirstKey', + value: 'myFirstValue', + metadata: ['ttlInSeconds' => '120'] + )); + $logger->alert('State has been stored'); +}); +``` + +{{% /codetab %}} + +{{< /tabs >}} + +See [this guide]({{< ref state_api.md >}}) for a reference on the state API. + +## Related links + +- Learn [how to use key value pairs to persist a state]({{< ref howto-get-save-state.md >}}) +- List of [state store components]({{< ref supported-state-stores >}}) +- Read the [API reference]({{< ref state_api.md >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md index d66e53865..60547031b 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md @@ -26,38 +26,38 @@ The following stores are supported, at various levels, by the Dapr state managem ### Generic -| Name | CRUD | Transactional | ETag | Actors | Status | Component version | Since | -|----------------------------------------------------------------|------|---------------------|------|------|--------| -------|------| -| [Aerospike]({{< ref setup-aerospike.md >}}) | ✅ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | -| [Apache Cassandra]({{< ref setup-cassandra.md >}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | -| [Cloudstate]({{< ref setup-cloudstate.md >}}) | ✅ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | -| [Couchbase]({{< ref setup-couchbase.md >}}) | ✅ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | -| [Hashicorp Consul]({{< ref setup-consul.md >}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | -| [Hazelcast]({{< ref setup-hazelcast.md >}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | -| [Memcached]({{< ref setup-memcached.md >}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | -| [MongoDB]({{< ref setup-mongodb.md >}}) | ✅ | ✅ | ✅ | ✅ | GA | v1 | 1.0 | -| [MySQL]({{< ref setup-mysql.md >}}) | ✅ | ✅ | ✅ | ✅ | Alpha | v1 | 1.0 | -| [PostgreSQL]({{< ref setup-postgresql.md >}}) | ✅ | ✅ | ✅ | ✅ | Alpha | v1 | 1.0 | -| [Redis]({{< ref setup-redis.md >}}) | ✅ | ✅ | ✅ | ✅ | GA | v1 | 1.0 | -| [RethinkDB]({{< ref setup-rethinkdb.md >}}) | ✅ | ✅ | ✅ | ✅ | Alpha | v1 | 1.0 | -| [Zookeeper]({{< ref setup-zookeeper.md >}}) | ✅ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | +| Name | CRUD | Transactional | ETag | [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | Status | Component version | Since | +|----------------------------------------------------------------|------|---------------------|------|-----|------|--------| -------|------| +| [Aerospike]({{< ref setup-aerospike.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | Alpha | v1 | 1.0 | +| [Apache Cassandra]({{< ref setup-cassandra.md >}}) | ✅ | ❌ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | +| [Cloudstate]({{< ref setup-cloudstate.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | Alpha | v1 | 1.0 | +| [Couchbase]({{< ref setup-couchbase.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | Alpha | v1 | 1.0 | +| [Hashicorp Consul]({{< ref setup-consul.md >}}) | ✅ | ❌ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | +| [Hazelcast]({{< ref setup-hazelcast.md >}}) | ✅ | ❌ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | +| [Memcached]({{< ref setup-memcached.md >}}) | ✅ | ❌ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | +| [MongoDB]({{< ref setup-mongodb.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | GA | v1 | 1.0 | +| [MySQL]({{< ref setup-mysql.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | Alpha | v1 | 1.0 | +| [PostgreSQL]({{< ref setup-postgresql.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | Alpha | v1 | 1.0 | +| [Redis]({{< ref setup-redis.md >}}) | ✅ | ✅ | ✅ | ✅ | ✅ | GA | v1 | 1.0 | +| [RethinkDB]({{< ref setup-rethinkdb.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | Alpha | v1 | 1.0 | +| [Zookeeper]({{< ref setup-zookeeper.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | Alpha | v1 | 1.0 | ### Amazon Web Services (AWS) -| Name | CRUD | Transactional | ETag | Actors | Status | Component version | Since | -|------------------------------------------------------------------|------|---------------------|------|--------|-----|-----|-------| -| [AWS DynamoDB]({{< ref setup-dynamodb.md>}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | +| Name | CRUD | Transactional | ETag | [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | Status | Component version | Since | +|------------------------------------------------------------------|------|---------------------|------|-----|--------|-----|-----|-------| +| [AWS DynamoDB]({{< ref setup-dynamodb.md>}}) | ✅ | ❌ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | ### Google Cloud Platform (GCP) -| Name | CRUD | Transactional | ETag | Actors | Status | Component version | Since | -|------------------------------------------------------------------|------|---------------------|------|--------|-----|-----|-------| -| [GCP Firestore]({{< ref setup-firestore.md >}}) | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | +| Name | CRUD | Transactional | ETag | [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | Status | Component version | Since | +|------------------------------------------------------------------|------|---------------------|------|-----|--------|-----|-----|-------| +| [GCP Firestore]({{< ref setup-firestore.md >}}) | ✅ | ❌ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | ### Microsoft Azure -| Name | CRUD | Transactional | ETag | Actors | Status | Component version | Since | -|------------------------------------------------------------------|------|---------------------|------|--------|-----|-----|-------| -| [Azure Blob Storage]({{< ref setup-azure-blobstorage.md >}}) | ✅ | ❌ | ✅ | ❌ | GA | v1 | 1.0 | -| [Azure CosmosDB]({{< ref setup-azure-cosmosdb.md >}}) | ✅ | ✅ | ✅ | ✅ | GA | v1 | 1.0 | -| [Azure SQL Server]({{< ref setup-sqlserver.md >}}) | ✅ | ✅ | ✅ | ✅ | Alpha | v1 | 1.0 | -| [Azure Table Storage]({{< ref setup-azure-tablestorage.md >}}) | ✅ | ❌ | ✅ | ❌ | Alpha | v1 | 1.0 | +| Name | CRUD | Transactional | ETag | [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | Status | Component version | Since | +|------------------------------------------------------------------|------|---------------------|------|-----|--------|-----|-----|-------| +| [Azure Blob Storage]({{< ref setup-azure-blobstorage.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | GA | v1 | 1.0 | +| [Azure CosmosDB]({{< ref setup-azure-cosmosdb.md >}}) | ✅ | ✅ | ✅ | ✅ | ✅ | GA | v1 | 1.0 | +| [Azure SQL Server]({{< ref setup-sqlserver.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | Alpha | v1 | 1.0 | +| [Azure Table Storage]({{< ref setup-azure-tablestorage.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | Alpha | v1 | 1.0 |