Key/Value Store Walkthrough

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
Copied!
Which should output something like:
1
Connection Information:
2
3
Client ID: 6
4
Client IP: 127.0.0.1
5
RTT: 64.996µs
6
Headers Supported: true
7
Maximum Payload: 1.0 MiB
8
Connected URL: nats://127.0.0.1:4222
9
Connected Address: 127.0.0.1:4222
10
Connected Server ID: ND2XVDA4Q363JOIFKJTPZW3ZKZCANH7NJI4EJMFSSPTRXDBFG4M4C34K
11
12
JetStream Account Information:
13
14
Memory: 0 B of Unlimited
15
Storage: 0 B of Unlimited
16
Streams: 0 of Unlimited
17
Consumers: 0 of Unlimited
Copied!
If you see the below instead then JetStream is not enabled
1
JetStream Account Information:
2
3
JetStream is not supported in this account
Copied!

Creating a KV bucket

Just like you have to create streams before you can use them, you need to first create a 'KV bucket' using nats kv add <KV Bucket Name>:
1
nats kv add my_kv
Copied!
which should output:
1
my_kv Key-Value Store Status
2
3
Bucket Name: my_kv
4
History Kept: 1
5
Maximum Bucket Size: unlimited
6
Maximum Value Size: unlimited
7
Bucket Location: unknown
8
Values Stored: 0
9
Backing Store Name: KV_my_kv
Copied!

Storing a value

Now that we have a bucket, we can use it to 'put' (store) values at keys:
1
nats kv put my_kv Key1 Value1
Copied!
which should return Value1

Getting a value

Now that we have value stored at key "Key1" we can retrieve that value with a 'get':
1
nats kv get my_kv Key1
Copied!
which should output
1
my_kv > Key1 created @ 12 Oct 21 20:08 UTC
2
3
Value1
Copied!

Deleting a value

You can always delete a Key/Value entry by using nats kv del my_kv Key1

Watching a K/V Store

A functionality (normally not provided by Key/Value stores) is available with the NATS KV Store is the ability to 'watch' a bucket (or a particular key in that bucket) and receive real-time updates to changes in the store.
For example run nats kv watch my_kv: this will start a watcher on the bucket we have just created earlier. If you followed this walkthrough the last operation that happened on the key is that it was deleted. Because by default the KV bucket is set with a history size of one (i.e. it keeps only the last change) and the last operation on the bucket was a delete of the value associated with the key "Key1" that is the only thing that get received by the watcher:
1
nats kv watch my_kv
Copied!
which should output
1
[2021-10-12 13:15:03] DEL my_kv > Key1
Copied!
Keep that nats kv watch running and in another window do another 'put'
1
nats kv put my_kv Key1 Value2
Copied!
As soon as that command is run you will see that put event received by the watcher:
1
[2021-10-12 13:25:14] PUT my_kv > Key1: Value2
Copied!

Cleaning up

Once you are finished playing, you can easily delete the KV bucket and release the resource associated with it by using:
1
nats kv rm my_kv
Copied!
Last modified 10d ago