Skip to main content
NATS is an open source messaging system for cloud native applications. It provides a lightweight publish-subscribe architecture for high performance messaging. NATS JetStream is a streaming data platform built on top of NATS. It enables real-time and historical access to streams of data via durable subscriptions and consumer groups.

​
Prerequisites

Before sinking data from RisingWave to NATS or NATS JetStream, please ensure the following:
  • The RisingWave cluster is running.
  • A NATS or NATS JetStream server is running and accessible from your RisingWave cluster.
  • Create a NATS subject that you want to sink data to.
  • You have the permission to publish data to the NATS subject.

​
Syntax

To sink data from RisingWave to a NATS subject, create a sink using the syntax below: 
CREATE SINK [ IF NOT EXISTS ] sink_name
[FROM sink_from | AS select_query]
WITH (
   connector='nats',
   server_url='<your nats server>:<port>', [ <another_server_url_if_available>, ...]
   subject='<your subject>',

 -- optional parameters
   allow_create_stream='<true|false>',
   connect_mode=<connect_mode>
   username='<your user name>',
   password='<your password>'
   jwt='<your jwt>',
   nkey='<your nkey>',
   type='<sink data type>'
);
After the sink is created, RisingWave will continuously sink data to the NATS subject in append-only mode.
The NATS sink connector in RisingWave provides at-least-once delivery semantics. Events may be redelivered in case of failures.
Stream creation securityStarting in v2.5, RisingWave does not create NATS streams automatically by default (allow_create_stream = false). This prevents accidental stream creation in production environments due to typos or misconfigurations.To enable automatic stream creation, set allow_create_stream = 'true'. Only enable this in development environments or when you specifically want RisingWave to manage stream creation.
According to the NATS documentation, stream names must adhere to subject naming rules as well as be friendly to the file system. Here are the recommended guidelines for stream names:
  • Use alphanumeric values.
  • Avoid spaces, tabs, periods (.), greater than (>) or asterisks (*).
  • Do not include path separators (forward slash or backward slash).
  • Keep the name length limited to 32 characters as the JetStream storage directories include the account, stream name, and consumer name.
  • Avoid using reserved file names like NUL or LPT1.
  • Be cautious of case sensitivity in file systems. To prevent collisions, ensure that stream or account names do not clash due to case differences. For example, Foo and foo would collide on Windows or macOS systems.

​
Parameters

FieldNotes
server_urlRequired. URLs of the NATS server, in the format of address:port. If multiple addresses are specified, use commas to separate them.
subjectRequired. NATS subject that you want to sink data to.
allow_create_streamOptional. Whether to allow RisingWave to create the NATS stream if it doesn’t exist. Default: false (changed in v2.5). When false, RisingWave will return an error if the specified stream doesn’t exist. When true, RisingWave will create the stream if it doesn’t exist. For production environments, it’s recommended to keep this as false to prevent accidental stream creation.
connect_modeRequired. Authentication mode for the connection. Allowed values:
  • plain: No authentication;
  • user_and_password: Use user name and password for authentication. For this option, username and password must be specified;
  • credential: Use JSON Web Token (JWT) and NKeys for authentication. For this option, jwt and nkey must be specified.
jwt and nkeyJWT and NKEY for authentication. For details, see JWT and NKeys.
username and passwordConditional. The client user name and password. Required when connect_mode is user_and_password.
typeRequired. Sink data type. Its value should be append-only.
⌘I