Key/Value Store Walkthrough

The Key/Value Store is a JetStream feature, so we need to verify it is enabled by

  1. nats account info

which may return

  1. JetStream Account Information:
  2. JetStream is not supported in this account

In this case, you should enable JetStream.

Prerequisite: enabling JetStream

If you are running a local nats-server stop it and restart it with JetStream enabled using nats-server -js (if that’s not already done)

You can then check that JetStream is enabled by using

  1. nats account info
  1. Connection Information:
  2. Client ID: 6
  3. Client IP: 127.0.0.1
  4. RTT: 64.996µs
  5. Headers Supported: true
  6. Maximum Payload: 1.0 MiB
  7. Connected URL: nats://127.0.0.1:4222
  8. Connected Address: 127.0.0.1:4222
  9. Connected Server ID: ND2XVDA4Q363JOIFKJTPZW3ZKZCANH7NJI4EJMFSSPTRXDBFG4M4C34K
  10. JetStream Account Information:
  11. Memory: 0 B of Unlimited
  12. Storage: 0 B of Unlimited
  13. Streams: 0 of Unlimited
  14. Consumers: 0 of Unlimited

Creating a KV bucket

A ‘KV bucket’ is like a stream; you need to create it before using it, as in nats kv add <KV Bucket Name>:

  1. nats kv add my-kv
  1. my_kv Key-Value Store Status
  2. Bucket Name: my-kv
  3. History Kept: 1
  4. Values Stored: 0
  5. Compressed: false
  6. Backing Store Kind: JetStream
  7. Bucket Size: 0 B
  8. Maximum Bucket Size: unlimited
  9. Maximum Value Size: unlimited
  10. Maximum Age: unlimited
  11. JetStream Stream: KV_my-kv
  12. Storage: File

Storing a value

Now that we have a bucket, we can assign, or ‘put’, a value to a specific key:

  1. nats kv put my-kv Key1 Value1

which should return the key’s value Value1

Getting a value

We can fetch, or ‘get’, the value for a key “Key1”:

  1. nats kv get my-kv Key1
  1. my-kv > Key1 created @ 12 Oct 21 20:08 UTC
  2. Value1

Deleting a value

You can always delete a key and its value by using

  1. nats kv del my-kv Key1

It is harmless to delete a non-existent key (check this!!).

Atomic operations

K/V Stores can also be used in concurrent design patterns, such as semaphores, by using atomic ‘create’ and ‘update’ operations.

E.g. a client wanting exclusive use of a file can lock it by creating a key, whose value is the file name, with create and deleting this key after completing use of that file. A client can increase the reslience against failure by using a timeout for the bucket containing this key. The client can use update with a revision number to keep the bucket alive.

Updates can also be used for more fine-grained concurrency control, sometimes known as optimistic locking, where multiple clients can try a task, but only one can successfully complete it.

Create (aka exclusive locking)

Create a lock/semaphore with the create operation.

  1. nats kv create my-sem Semaphore1 Value1

Only one create can succeed. First come, first serve. All concurrent attempts will result in an error until the key is deleted

  1. nats kv create my-sem Semaphore1 Value1
  2. nats: error: nats: wrong last sequence: 1: key exists

Update with CAS (aka optimistic locking)

We can also atomically update, sometimes known as a CAS (compare and swap) operation, a key with an additional parameter revision

  1. nats kv update my-sem Semaphore1 Value2 13

A second attempt with the same revision 13, will fail

  1. nats kv update my-sem Semaphore1 Value2 13
  2. nats: error: nats: wrong last sequence: 14

Watching a K/V Store

An unusual functionality of a K/V Store is being able to ‘watch’ a bucket, or a specific key in that bucket, and receive real-time updates to changes in the store.

For the example above, run nats kv watch my-kv. This will start a watcher on the bucket we have just created earlier. By default, the KV bucket has a history size of one, and so it only remembers the last change. In our case, the watcher should see a delete of the value associated with the key “Key1”:

  1. nats kv watch my-kv
  1. [2021-10-12 13:15:03] DEL my-kv > Key1

If we now concurrently change the value of ‘my-kv’ by

  1. nats kv put my-kv Key1 Value2

The watcher will see that change:

  1. [2021-10-12 13:25:14] PUT my-kv > Key1: Value2

Cleaning up

When you are finished using a bucket, you can delete the bucket, and its resources, by using the rm operator:

  1. nats kv rm my-kv