mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
GitBook: [master] 326 pages and 16 assets modified
This commit is contained in:
Ginger Collison
committed by
gitbook-bot
gitbook-bot
parent
8b7ba5c3bb
commit
fb0d5c8355
@@ -1,116 +0,0 @@
|
||||
# Important Changes
|
||||
|
||||
* [Version `0.10.0`](#version-0100)
|
||||
* [Version `0.9.0`](#version-090)
|
||||
* [Version `0.8.0-beta`](#version-080-beta)
|
||||
* [Version `0.6.0`](#version-060)
|
||||
* [Version `0.5.0`](#version-050)
|
||||
* [Version `0.4.0`](#version-040)
|
||||
|
||||
|
||||
|
||||
## Version `0.10.0`
|
||||
|
||||
The server needs to persist more state for a client connection. Therefore, the Store interface has been changed:
|
||||
|
||||
* Changed `AddClient(clientID, hbInbox string)` to `AddClient(info *spb.ClientInfo)`
|
||||
|
||||
For SQL Stores, the `Clients` table has been altered to add a `proto` column.<br>
|
||||
You can update the SQL table manually or run the provided scripts that create the tables if they don't exists
|
||||
and alter the `Clients` table adding the new column. For instance, with MySQL, you would run something similar to:
|
||||
|
||||
```
|
||||
mysql -u root nss_db < scripts/mysql.db.sql
|
||||
```
|
||||
The above assumes you are in the NATS Streaming Server directory, and the streaming database is called `nss_db`.
|
||||
|
||||
Otherwise, from the mysql CLI, you can run the command:
|
||||
```
|
||||
mysql> alter table Clients add proto blob;
|
||||
Query OK, 0 rows affected (0.05 sec)
|
||||
Records: 0 Duplicates: 0 Warnings: 0
|
||||
```
|
||||
For Postgres, it would be:
|
||||
```
|
||||
nss_db=# alter table Clients add proto bytea;
|
||||
ALTER TABLE
|
||||
```
|
||||
|
||||
If you run the server version with `0.10.0` a database that has not been updated, you would get the following error:
|
||||
```
|
||||
[FTL] STREAM: Failed to start: unable to prepare statement "INSERT INTO Clients (id, hbinbox, proto) VALUES (?, ?, ?)": Error 1054: Unknown column 'proto' in 'field list'
|
||||
```
|
||||
|
||||
## Version `0.9.0`
|
||||
|
||||
Additions to the Store interface to support deletion of channels.
|
||||
|
||||
* Added `Store.GetChannelLimits()` API to return the store limits for a given channel.
|
||||
* Added `Store.DeleteChannel()` API to delete a channel.
|
||||
|
||||
Protocol was added to support replication of deletion of a channel in the cluster.
|
||||
|
||||
## Version `0.8.0-beta`
|
||||
|
||||
The Store interface has been slightly changed to accommodate the clustering feature.
|
||||
|
||||
* Changed `MstStore.Store()` API to accept a `*pb.MsgProto` instead of a byte array. This is because the server is now assigning the sequence number.
|
||||
The store implementation should ignore the call if the given sequence number is below or equal to what has been already stored.
|
||||
* Added `MsgStore.Empty()` API to empty a given channel message store.
|
||||
|
||||
## Version `0.6.0`
|
||||
|
||||
The Store interface has been heavily modified. Some of the responsibilities have been moved into the server
|
||||
resulting on deletion of some Store APIs and removal of `UserData` fields in `Client` and `ChannelStore` (renamed `Channel`) objects.
|
||||
|
||||
>**NOTE:** Although the interface has changed, the file format of the FileStore implementation has not, which means
|
||||
that there is backward/forward compatibility between this and previous releases.
|
||||
|
||||
The Store interface was updated:
|
||||
|
||||
* Added error `ErrAlreadyExists` that `CreateChannel()` should return if channel already exists.
|
||||
* `RecoveredState` has now `Channels` (instead of `Subs`) and is a map of `*RecoveredChannel` keyed by channel name.
|
||||
* `RecoveredChannel` has a pointer to a `Channel` (formely `ChannelStore`) and an array of pointers to `RecoveredSubscription` objects.
|
||||
* `RecoveredSubscription` replaces `RecoveredSubState`.
|
||||
* `Client` no longer stores a `UserData` field.
|
||||
* `Channel` (formerly `ChannelStore`) no longer stores a `UserData` field.
|
||||
* `CreateChannel()` no longer accepts a `userData interface{}` parameter. It returns a `*Channel` and an `error`. If the channel
|
||||
already exists, the error `ErrAlreadyExists` is returned.
|
||||
* `LookupChannel()`, `HasChannel()`, `GetChannels()`, `GetChannelsCount()`, `GetClient()`, `GetClients`, `GetClientsCount()` and `MsgsState()` APIs
|
||||
have all been removed. The server keeps track of clients and channels and therefore does not need those APIs.
|
||||
* `AddClient()` is now simply returning a `*Client` and `error`. It no longer accepts a `userData interface{}` parameter.
|
||||
* `DeleteClient()` now returns an error instead of returning the deleted `*Client`. This will allow the server to
|
||||
report possible errors.
|
||||
|
||||
The SubStore interface was updated:
|
||||
|
||||
* `DeleteSub()` has been modified to return an error. This allows the server to report possible errors during deletion
|
||||
of a subscription.
|
||||
|
||||
The MsgStore interface was updated:
|
||||
|
||||
* `Lookup()`, `FirstSequence()`, `LastSequence()`, `FirstAndLastSequence()`, `GetSequenceFromTimestamp()`, `FirstMsg()` and `LastMsg()`
|
||||
have all been modified to return an error. This is so that implementations that may fail to lookup, get the first sequence, etc...
|
||||
have a way to report the error to the caller.
|
||||
|
||||
## Version `0.5.0`
|
||||
|
||||
The Store interface was updated. There are 2 news APIs:
|
||||
|
||||
* `GetChannels()`: Returns a map of `*ChannelStore`, keyed by channel names.<br>
|
||||
The implementation needs to return a copy to make it safe for the caller to manipulate
|
||||
the map without a risk of concurrent access.
|
||||
* `GetChannelsCount()`: Returns the number of channels currently stored.
|
||||
|
||||
## Version `0.4.0`
|
||||
|
||||
The Store interface was updated. There are 2 news APIs:
|
||||
|
||||
* `Recover()`: The recovery of persistent state was previously done in the constructor of the store implementation.<br>
|
||||
It is now separate and specified with this API. The server will first instantiate the store, in
|
||||
which some initialization or checks can be made.<br>
|
||||
If no error is reported, the server will then proceed with calling `Recover()`, which will returned the recovered state.<br>
|
||||
* `GetExclusiveLock()`: In Fault Tolerance mode, when a server is elected leader, it will attempt to get an exclusive
|
||||
lock to the shared storage before proceeding.<br>
|
||||
|
||||
Check the [Store interface](https://github.com/nats-io/nats-streaming-server/blob/master/stores/store.go) for more information.
|
||||
@@ -1,87 +0,0 @@
|
||||
# NATS Streaming Server Installation
|
||||
|
||||
NATS philosophy is simplicity.
|
||||
|
||||
The best way to get the NATS Streaming Server is to use one of the pre-built release binaries which are available for OSX, Linux (x86-64/ARM), Windows.
|
||||
|
||||
Of course you can build the latest version of the server from the master branch. The master branch will always build and pass tests, but may not work correctly in your environment. First you will need at least Go version 1.11+ installed on your machine to build the NATS Streaming Server.
|
||||
|
||||
Installation is just decompressing a zip file and copying the binary to an appropriate directory; you can also use your favorite package manager.
|
||||
|
||||
## Installing via a Package Manager
|
||||
|
||||
On Mac OS:
|
||||
```
|
||||
> brew install nats-streaming-server
|
||||
```
|
||||
|
||||
Via Docker:
|
||||
```
|
||||
> docker pull nats-streaming
|
||||
```
|
||||
|
||||
## Installing a release build
|
||||
|
||||
You can find the latest release of `nats-streaming-server` [here](https://github.com/nats-io/nats-streaming-server/releases/latest).
|
||||
|
||||
Download the zip file matching your systems architecture, and unzip. For this example, assuming version 0.14.2 of the server, and a Linux AMD64:
|
||||
```
|
||||
> curl -L https://github.com/nats-io/nats-streaming-server/releases/download/v0.14.2/nats-streaming-server-v0.14.2-linux-amd64.zip -o nats-streaming-server.zip
|
||||
|
||||
> unzip nats-streaming-server.zip -d tmp
|
||||
Archive: nats-streaming-server.zip
|
||||
creating: tmp/nats-streaming-server-v0.14.2-linux-amd64/
|
||||
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/README.md
|
||||
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/LICENSE
|
||||
inflating: tmp/nats-streaming-server-v0.14.2-linux-amd64/nats-streaming-server
|
||||
|
||||
> cp tmp/nats-streaming-server-v0.14.2-linux-amd64/nats-streaming-server /usr/local/bin
|
||||
```
|
||||
|
||||
## Installing from the source
|
||||
|
||||
If you have go installed, installing the binary is easy:
|
||||
|
||||
```
|
||||
> go get github.com/nats-io/nats-streaming-server
|
||||
```
|
||||
|
||||
This mechanism will install a build of master, which almost certainly will not be a released version. If you are a developer and want to play with the latest, this is the easiest way of obtaining it.
|
||||
|
||||
You can run the test suite from the `nats-streaming-server` root directory:
|
||||
```
|
||||
go test -v -p=1 ./...
|
||||
```
|
||||
|
||||
Some of the store tests require a SQL server to be running. To skip those, use this command instead:
|
||||
```
|
||||
go test -v -p=1 ./... -sql=false
|
||||
```
|
||||
|
||||
## Testing Your Installation
|
||||
|
||||
To test your installation (provided the executable is visible to your shell):
|
||||
|
||||
```
|
||||
> nats-streaming-server
|
||||
[58061] 2019/05/22 13:56:45.463562 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.14.2
|
||||
[58061] 2019/05/22 13:56:45.463639 [INF] STREAM: ServerID: Avb51sMf9imRPVVwv6Ts0v
|
||||
[58061] 2019/05/22 13:56:45.463657 [INF] STREAM: Go version: go1.11.10
|
||||
[58061] 2019/05/22 13:56:45.463659 [INF] STREAM: Git commit: [not set]
|
||||
[58061] 2019/05/22 13:56:45.464086 [INF] Starting nats-server version 1.4.1
|
||||
[58061] 2019/05/22 13:56:45.464092 [INF] Git commit [not set]
|
||||
[58061] 2019/05/22 13:56:45.464310 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[58061] 2019/05/22 13:56:45.464328 [INF] Server is ready
|
||||
[58061] 2019/05/22 13:56:45.495045 [INF] STREAM: Recovering the state...
|
||||
[58061] 2019/05/22 13:56:45.495055 [INF] STREAM: No recovered state
|
||||
[58061] 2019/05/22 13:56:45.749604 [INF] STREAM: Message store is MEMORY
|
||||
[58061] 2019/05/22 13:56:45.749658 [INF] STREAM: ---------- Store Limits ----------
|
||||
[58061] 2019/05/22 13:56:45.749664 [INF] STREAM: Channels: 100 *
|
||||
[58061] 2019/05/22 13:56:45.749668 [INF] STREAM: --------- Channels Limits --------
|
||||
[58061] 2019/05/22 13:56:45.749671 [INF] STREAM: Subscriptions: 1000 *
|
||||
[58061] 2019/05/22 13:56:45.749675 [INF] STREAM: Messages : 1000000 *
|
||||
[58061] 2019/05/22 13:56:45.749678 [INF] STREAM: Bytes : 976.56 MB *
|
||||
[58061] 2019/05/22 13:56:45.749682 [INF] STREAM: Age : unlimited *
|
||||
[58061] 2019/05/22 13:56:45.749686 [INF] STREAM: Inactivity : unlimited *
|
||||
[58061] 2019/05/22 13:56:45.749690 [INF] STREAM: ----------------------------------
|
||||
```
|
||||
@@ -1,27 +0,0 @@
|
||||
# Process Signaling
|
||||
|
||||
On Unix systems, the NATS Streaming Server responds to the following signals:
|
||||
|
||||
| Signal | Result |
|
||||
| --------------- | ------------------------------------- |
|
||||
| SIGKILL | Kills the process immediately |
|
||||
| SIGINT, SIGTERM | Stops the server gracefully |
|
||||
| SIGUSR1 | Reopens the log file for log rotation |
|
||||
|
||||
The `nats-streaming-server` binary can be used to send these signals to run NATS Streaming Servers using the `-sl` flag:
|
||||
|
||||
```sh
|
||||
# Reopen log file for log rotation
|
||||
nats-streaming-server -sl reopen
|
||||
|
||||
# Stop the server
|
||||
nats-streaming-server -sl quit
|
||||
```
|
||||
|
||||
If there are multiple `nats-streaming-server` processes running, specify a PID:
|
||||
|
||||
```sh
|
||||
nats-streaming-server -sl quit=<pid>
|
||||
```
|
||||
|
||||
See the [Windows Service](#windows-service) section for information on signaling the NATS Streaming Server on Windows.
|
||||
@@ -1,96 +0,0 @@
|
||||
# Getting Started with NATS Streaming
|
||||
|
||||
This tutorial demonstrates NATS Streaming using example [Go NATS Streaming clients](https://github.com/nats-io/stan.go.git).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Set up your Git environment](https://help.github.com/articles/set-up-git/).
|
||||
- [Set up your Go environment](https://golang.org/doc/install).
|
||||
|
||||
## Setup
|
||||
|
||||
Download and install the [NATS Streaming Server](https://github.com/nats-io/nats-streaming-server/releases).
|
||||
|
||||
Clone the following repositories:
|
||||
|
||||
- NATS Streaming Server: `git clone https://github.com/nats-io/nats-streaming-server.git`
|
||||
- NATS Streaming Client: `git clone https://github.com/nats-io/stan.go.git`
|
||||
|
||||
## Start the NATS Streaming Server
|
||||
|
||||
Two options:
|
||||
|
||||
Run the binary that you downloaded, for example: `$ ./nats-streaming-server`
|
||||
|
||||
Or, run from source:
|
||||
|
||||
```sh
|
||||
> cd $GOPATH/src/github.com/nats-io/nats-streaming-server
|
||||
> go run nats-streaming-server.go
|
||||
```
|
||||
|
||||
You should see the following, indicating that the NATS Streaming Server is running:
|
||||
|
||||
```sh
|
||||
> go run nats-streaming-server.go
|
||||
[59232] 2019/05/22 14:24:54.426344 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.14.2
|
||||
[59232] 2019/05/22 14:24:54.426423 [INF] STREAM: ServerID: 3fpvAuXHo3C66Rkd4rmfFX
|
||||
[59232] 2019/05/22 14:24:54.426440 [INF] STREAM: Go version: go1.11.10
|
||||
[59232] 2019/05/22 14:24:54.426442 [INF] STREAM: Git commit: [not set]
|
||||
[59232] 2019/05/22 14:24:54.426932 [INF] Starting nats-server version 1.4.1
|
||||
[59232] 2019/05/22 14:24:54.426937 [INF] Git commit [not set]
|
||||
[59232] 2019/05/22 14:24:54.427104 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[59232] 2019/05/22 14:24:54.427108 [INF] Server is ready
|
||||
[59232] 2019/05/22 14:24:54.457604 [INF] STREAM: Recovering the state...
|
||||
[59232] 2019/05/22 14:24:54.457614 [INF] STREAM: No recovered state
|
||||
[59232] 2019/05/22 14:24:54.711407 [INF] STREAM: Message store is MEMORY
|
||||
[59232] 2019/05/22 14:24:54.711465 [INF] STREAM: ---------- Store Limits ----------
|
||||
[59232] 2019/05/22 14:24:54.711471 [INF] STREAM: Channels: 100 *
|
||||
[59232] 2019/05/22 14:24:54.711474 [INF] STREAM: --------- Channels Limits --------
|
||||
[59232] 2019/05/22 14:24:54.711478 [INF] STREAM: Subscriptions: 1000 *
|
||||
[59232] 2019/05/22 14:24:54.711481 [INF] STREAM: Messages : 1000000 *
|
||||
[59232] 2019/05/22 14:24:54.711485 [INF] STREAM: Bytes : 976.56 MB *
|
||||
[59232] 2019/05/22 14:24:54.711488 [INF] STREAM: Age : unlimited *
|
||||
[59232] 2019/05/22 14:24:54.711492 [INF] STREAM: Inactivity : unlimited *
|
||||
[59232] 2019/05/22 14:24:54.711495 [INF] STREAM: ----------------------------------
|
||||
```
|
||||
|
||||
## Run the publisher client
|
||||
|
||||
Publish several messages. For each publication you should get a result.
|
||||
|
||||
```sh
|
||||
> cd $GOPATH/src/github.com/nats-io/stan.go/examples/stan-pub
|
||||
> go run main.go foo "msg one"
|
||||
Published [foo] : 'msg one'
|
||||
> go run main.go foo "msg two"
|
||||
Published [foo] : 'msg two'
|
||||
> go run main.go foo "msg three"
|
||||
Published [foo] : 'msg three'
|
||||
```
|
||||
|
||||
## Run the subscriber client
|
||||
|
||||
Use the `--all` flag to receive all published messages.
|
||||
|
||||
```sh
|
||||
> cd $GOPATH/src/github.com/nats-io/stan.go/examples/stan-sub
|
||||
> go run main.go --all -c test-cluster -id myID foo
|
||||
Connected to nats://localhost:4222 clusterID: [test-cluster] clientID: [myID]
|
||||
subscribing with DeliverAllAvailable
|
||||
Listening on [foo], clientID=[myID], qgroup=[] durable=[]
|
||||
[#1] Received on [foo]: 'sequence:1 subject:"foo" data:"msg one" timestamp:1465962202884478817 '
|
||||
[#2] Received on [foo]: 'sequence:2 subject:"foo" data:"msg two" timestamp:1465962208545003897 '
|
||||
[#3] Received on [foo]: 'sequence:3 subject:"foo" data:"msg three" timestamp:1465962215567601196
|
||||
```
|
||||
|
||||
## Explore other subscription options
|
||||
|
||||
```sh
|
||||
--seq <seqno> Start at seqno
|
||||
--all Deliver all available messages
|
||||
--last Deliver starting with last published message
|
||||
--since <duration> Deliver messages in last interval (e.g. 1s, 1hr, https://golang.org/pkg/time/#ParseDuration)
|
||||
--durable <name> Durable subscriber name
|
||||
--unsubscribe Unsubscribe the durable on exit
|
||||
```
|
||||
@@ -1,28 +0,0 @@
|
||||
# Windows Service
|
||||
|
||||
The NATS Streaming Server supports running as a Windows service. There is currently no installer and instead users should use `sc.exe` to install the service.
|
||||
|
||||
Here is how to create and start a NATS Streaming Server named `nats-streaming-server`. Note that the server flags should be passed in when creating the service.
|
||||
```sh
|
||||
sc.exe create nats-streaming-server binPath="\"<streaming server path>\nats-streaming-server.exe\" [NATS Streaming flags]"
|
||||
sc.exe start nats-streaming-server
|
||||
```
|
||||
|
||||
You can create several instances, giving it a unique name. For instance, this is how you would create two services, named `nss1` and `nss2`, each one with its own set of parameters.
|
||||
```
|
||||
sc.exe create nss1 binPath="\"c:\nats-io\nats-streaming\nats-streaming-server.exe\" --syslog --syslog_name=nss1 -p 4222"
|
||||
|
||||
sc.exe create nss2 binPath="\"c:\nats-io\nats-streaming\nats-streaming-server.exe\" --syslog --syslog_name=nss2 -p 4223"
|
||||
```
|
||||
By default, when no logfile is specified, the server will use the system log. The default event source name is `NATS-Streaming-Server`. However, you can specify the name you want, which is especially useful when installing more than one service as described above.
|
||||
|
||||
Once the service is running, it can be controlled using `sc.exe` or `nats-streaming-server.exe -sl`:
|
||||
|
||||
```batch
|
||||
REM Stop the server
|
||||
nats-streaming-server.exe -sl quit
|
||||
```
|
||||
The above commands will default to controlling the service named `nats-streaming-server`. If the service has another name, it can be specified like this:
|
||||
```batch
|
||||
nats-streaming-server.exe -sl quit=<service name>
|
||||
```
|
||||
Reference in New Issue
Block a user