Overview
This node interacts with the NATS JetStream Key-Value (KV) store, specifically allowing management of KV buckets and keys within those buckets. The "Bucket - Create" operation enables users to create a new KV bucket with customizable configuration options such as description, history retention, size limits, replication factor, storage backend, and time-to-live settings.
Common scenarios for this node include:
- Setting up a new KV bucket to store application state or user preferences.
- Configuring buckets with specific fault tolerance and storage requirements.
- Managing data lifecycle by setting TTLs to automatically expire old keys.
Practical example:
- Creating a bucket named
user-preferencesthat stores user settings in memory with a history of 5 versions per key and a TTL of 24 hours.
Properties
| Name | Meaning |
|---|---|
| Bucket Name | The name of the KV bucket to create. Must contain only alphanumeric characters, dashes, and underscores. |
| Configuration | A collection of optional settings to customize the bucket: |
| Description | Text description of the bucket's purpose (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 increase redundancy. |
| Storage Type | Storage backend type for the bucket. Options: File (store on disk), Memory (store in memory). |
| TTL (Milliseconds) | Time-to-live for keys in milliseconds. Keys older than this are automatically deleted. Set to 0 for no TTL. |
| Marker TTL (Milliseconds) | Enables limit markers with a TTL to notify watchers of changes. Set to 0 to disable. |
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.
No binary data output is involved in this operation.
Example output structure (conceptual):
{
"bucket": "my-bucket",
"description": "User preferences bucket",
"history": 1,
"max_bytes": -1,
"maxValueSize": -1,
"replicas": 1,
"storage": "file",
"ttl": 0,
"markerTTL": 0,
"status": "created"
}
Dependencies
- Requires a valid connection to a NATS JetStream server with appropriate permissions to manage KV buckets.
- Needs an API authentication credential configured in n8n to connect securely to the NATS server.
- Uses the bundled NATS client library for communication.
Troubleshooting
- Invalid bucket name error: Bucket names must only contain alphanumeric characters, dashes, and underscores. Ensure the 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.
- Connection issues: Failure to connect to the NATS server may occur due to incorrect credentials or network problems. Check API key validity and server accessibility.
- Quota exceeded or size limits: If the bucket exceeds configured max size or value size limits, creation or updates may fail. Adjust configuration accordingly.
- Permission denied: Insufficient permissions on the NATS server can cause errors. Confirm the API key has rights to create buckets.
To resolve errors, review the error messages provided by the node, verify input parameters, and ensure the NATS server is reachable and properly configured.