Powered By GitBook
Streams
The first step is to set up storage for our ORDERS related messages, these arrive on a wildcard of subjects all flowing into the same Stream and they are kept for 1 year.

Creating

1
$ nats str add ORDERS
2
? Subjects to consume ORDERS.*
3
? Storage backend file
4
? Retention Policy Limits
5
? Discard Policy Old
6
? Message count limit -1
7
? Message size limit -1
8
? Maximum message age limit 1y
9
? Maximum individual message size [? for help] (-1) -1
10
Stream ORDERS was created
11
12
Information for Stream ORDERS
13
14
Configuration:
15
16
Subjects: ORDERS.*
17
Acknowledgements: true
18
Retention: File - Limits
19
Replicas: 1
20
Maximum Messages: -1
21
Maximum Bytes: -1
22
Maximum Age: 8760h0m0s
23
Maximum Message Size: -1
24
Maximum Consumers: -1
25
26
Statistics:
27
28
Messages: 0
29
Bytes: 0 B
30
FirstSeq: 0
31
LastSeq: 0
32
Active Consumers: 0
Copied!
You can get prompted interactively for missing information as above, or do it all on one command. Pressing ? in the CLI will help you map prompts to CLI options:
1
nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard old --dupe-window="0s" --replicas 1
Copied!
Additionally one can store the configuration in a JSON file, the format of this is the same as $ nats str info ORDERS -j | jq .config:
1
$ nats str add ORDERS --config orders.json
Copied!

Listing

We can confirm our Stream was created:
1
$ nats str ls
2
Streams:
3
4
ORDERS
Copied!

Querying

Information about the configuration of the Stream can be seen, and if you did not specify the Stream like below, it will prompt you based on all known ones:
1
$ nats str info ORDERS
2
Information for Stream ORDERS created 2021-02-27T16:49:36-07:00
3
4
Configuration:
5
6
Subjects: ORDERS.*
7
Acknowledgements: true
8
Retention: File - Limits
9
Replicas: 1
10
Discard Policy: Old
11
Duplicate Window: 2m0s
12
Maximum Messages: unlimited
13
Maximum Bytes: unlimited
14
Maximum Age: 1y0d0h0m0s
15
Maximum Message Size: unlimited
16
Maximum Consumers: unlimited
17
18
State:
19
20
Messages: 0
21
Bytes: 0 B
22
FirstSeq: 0
23
LastSeq: 0
24
Active Consumers: 0
Copied!
Most commands that show data as above support -j to show the results as JSON:
1
$ nats str info ORDERS -j
2
{
3
"config": {
4
"name": "ORDERS",
5
"subjects": [
6
"ORDERS.*"
7
],
8
"retention": "limits",
9
"max_consumers": -1,
10
"max_msgs": -1,
11
"max_bytes": -1,
12
"max_age": 31536000000000000,
13
"max_msg_size": -1,
14
"storage": "file",
15
"discard": "old",
16
"num_replicas": 1,
17
"duplicate_window": 120000000000
18
},
19
"created": "2021-02-27T23:49:36.700424Z",
20
"state": {
21
"messages": 0,
22
"bytes": 0,
23
"first_seq": 0,
24
"first_ts": "0001-01-01T00:00:00Z",
25
"last_seq": 0,
26
"last_ts": "0001-01-01T00:00:00Z",
27
"consumer_count": 0
28
}
29
}
Copied!
This is the general pattern for the entire nats utility as it relates to JetStream - prompting for needed information but every action can be run non-interactively making it usable as a CLI API. All information output like seen above can be turned into JSON using -j.

Copying

A stream can be copied into another, which also allows the configuration of the new one to be adjusted via CLI flags:
1
$ nats str cp ORDERS ARCHIVE --subjects "ORDERS_ARCVHIVE.*" --max-age 2y
2
Stream ORDERS was created
3
4
Information for Stream ORDERS created 2021-02-27T16:52:46-07:00
5
6
Configuration:
7
8
Subjects: ORDERS_ARCHIVE.*
9
Acknowledgements: true
10
Retention: File - Limits
11
Replicas: 1
12
Discard Policy: Old
13
Duplicate Window: 2m0s
14
Maximum Messages: unlimited
15
Maximum Bytes: unlimited
16
Maximum Age: 2y0d0h0m0s
17
Maximum Message Size: unlimited
18
Maximum Consumers: unlimited
19
20
State:
21
22
Messages: 0
23
Bytes: 0 B
24
FirstSeq: 0
25
LastSeq: 0
26
Active Consumers: 0
Copied!

Editing

A stream configuration can be edited, which allows the configuration to be adjusted via CLI flags. Here I have an incorrectly created ORDERS stream that I fix:
1
$ nats str info ORDERS -j | jq .config.subjects
2
[
3
"ORDERS.new"
4
]
5
6
$ nats str edit ORDERS --subjects "ORDERS.*"
7
Stream ORDERS was updated
8
9
Information for Stream ORDERS
10
11
Configuration:
12
13
Subjects: ORDERS.*
14
....
Copied!
Additionally, one can store the configuration in a JSON file, the format of this is the same as $ nats str info ORDERS -j | jq .config:
1
$ nats str edit ORDERS --config orders.json
Copied!

Publishing Into a Stream

Now let's add some messages to our Stream. You can use nats pub to add messages, pass the --wait flag to see the publish ack being returned.
You can publish without waiting for acknowledgement:
1
$ nats pub ORDERS.scratch hello
2
Published [sub1] : 'hello'
Copied!
But if you want to be sure your messages got to JetStream and were persisted you can make a request:
1
$ nats req ORDERS.scratch hello
2
13:45:03 Sending request on [ORDERS.scratch]
3
13:45:03 Received on [_INBOX.M8drJkd8O5otORAo0sMNkg.scHnSafY]: '+OK'
Copied!
Keep checking the status of the Stream while doing this and you'll see its stored messages increase.
1
$ nats str info ORDERS
2
Information for Stream ORDERS
3
...
4
Statistics:
5
6
Messages: 3
7
Bytes: 147 B
8
FirstSeq: 1
9
LastSeq: 3
10
Active Consumers: 0
Copied!
After putting some throwaway data into the Stream, we can purge all the data out - while keeping the Stream active:

Deleting All Data

To delete all data in a stream use purge:
1
$ nats str purge ORDERS -f
2
...
3
State:
4
5
Messages: 0
6
Bytes: 0 B
7
FirstSeq: 1,000,001
8
LastSeq: 1,000,000
9
Active Consumers: 0
Copied!

Deleting A Message

A single message can be securely removed from the stream:
1
$ nats str rmm ORDERS 1 -f
Copied!

Deleting Sets

Finally, for demonstration purposes, you can also delete the whole Stream and recreate it so then we're ready for creating the Consumers:
1
$ nats str rm ORDERS -f
2
$ nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard old --dupe-window="0s" --replicas 1
Copied!
Last modified 5mo ago