NATS KV icon

NATS KV

Interact with NATS JetStream Key-Value Store - manage buckets and keys
Join our community

Actions8

Overview

This node interacts with the NATS JetStream Key-Value (KV) Store, specifically managing KV buckets and keys within those buckets. The "Bucket - Create" operation allows users to create a new KV bucket with customizable configuration options such as description, history retention, size limits, replication, storage backend, and TTL for keys.

Common scenarios where this node is beneficial include:

  • Setting up isolated namespaces (buckets) for storing application state or user preferences.
  • Creating fault-tolerant and scalable key-value stores with configurable replication.
  • Managing data lifecycle by setting TTLs and size constraints on stored keys and buckets.

Practical example:

  • A workflow that creates a new bucket named "user-preferences" with a description, keeps only the latest value per key, stores data on disk, and sets a TTL of 1 day for each key.

Properties

Name Meaning
Bucket Name Name of the KV bucket to create. Must contain only alphanumeric characters, dashes, and underscores.
Configuration Collection of optional settings for the bucket:
  Description Text description of the KV bucket (e.g., "User preferences bucket").
  History Per Key Number of historical values to keep per key. Set to 1 to keep only the latest value.
  Max Size (Bytes) Maximum total size of the bucket in bytes. Use -1 for unlimited size.
  Max Value Size (Bytes) Maximum size allowed for a single value in bytes. Use -1 for unlimited size.
  Replicas Number of replicas for the bucket to improve fault tolerance. Higher numbers mean better redundancy.
  Storage Type Storage backend type for the bucket. Options:
• File — store data on disk
• Memory — store data in memory
  TTL (Seconds) Time-to-live in seconds for keys in the bucket. Keys older than this are automatically deleted by the server. Use 0 for no TTL.

Output

The output JSON contains the result of the bucket creation operation. This typically includes metadata about the created bucket such as its name, configuration details, and status confirmation from the NATS JetStream server.

No binary data output is produced by this operation.

Example output structure (conceptual):

{
  "bucket": "my-bucket",
  "description": "User preferences bucket",
  "history": 1,
  "max_bytes": -1,
  "max_value_size": -1,
  "replicas": 1,
  "storage": "file",
  "ttl": 86400,
  "status": "created"
}

Dependencies

  • Requires an active connection to a NATS JetStream server.
  • Needs an API authentication token or API key credential configured in n8n to connect securely to the NATS server.
  • Uses the nats client library bundled internally.
  • No additional external services are required beyond the NATS JetStream environment.

Troubleshooting

  • Invalid bucket name error: Bucket names must only contain alphanumeric characters, dashes, and underscores. Ensure the bucket name follows these rules.
  • Unknown bucket operation: If an unsupported operation is specified, the node will throw an error. Verify the operation name is correct and supported.
  • Connection errors: Failure to connect to the NATS server may occur if credentials are invalid or the server is unreachable. Check network connectivity and credential correctness.
  • Quota exceeded or size limit errors: If the bucket or value size exceeds configured limits, the server may reject the creation. Adjust the max size or max value size accordingly.
  • Permission denied: Insufficient permissions on the NATS server can cause failures. Ensure the API key has rights to create buckets.

If the node is set to continue on failure, errors for individual items will be returned in the output with detailed messages.

Links and References

Discussion