n8n-nodes-upstash

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact licensing@velobpa.com.

A comprehensive n8n community node for Upstash, the serverless data platform providing Redis, Kafka, QStash, and Vector databases. This node enables workflow automation for database management, Redis operations, Kafka messaging, vector search, and task scheduling through Upstash's Management and Data APIs.

Features

• Redis Database Management: Create, configure, and manage Redis databases with support for global multi-region deployments
• Redis Data Operations: Full CRUD operations including strings, lists, sets, hashes, sorted sets, and pub/sub
• Kafka Clusters: Manage Kafka clusters, topics, credentials, and connectors
• QStash Messaging: Publish messages, create schedules, and manage dead letter queues
• Vector Databases: Create indexes, upsert vectors, and perform similarity searches
• Team & Usage: Manage teams, members, and monitor usage statistics
• Webhook Triggers: Receive QStash callbacks with signature verification

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Search for n8n-nodes-upstash
4. Click Install

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-upstash

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-upstash.git
cd n8n-nodes-upstash

# Install dependencies
npm install

# Build the project
npm run build

# Create symlink to n8n custom nodes directory
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-upstash

# Restart n8n
n8n start

Credentials Setup

The Upstash node requires credentials to authenticate with Upstash APIs.

Required Credentials

Field	Description	Required
Email	Your Upstash account email	Yes
API Key	API key from Upstash Console	Yes

Optional Credentials (for Data Operations)

Field	Description	Required For
Redis REST URL	Database REST endpoint	Redis data operations
Redis REST Token	Database REST token	Redis data operations
QStash Token	QStash API token	QStash operations
QStash Signing Key	Webhook signature verification	QStash triggers
Vector REST URL	Vector index REST endpoint	Vector operations
Vector REST Token	Vector index REST token	Vector operations

Getting Your Credentials

1. Management API (Email + API Key):

   • Log into Upstash Console
   • Navigate to Account settings
   • Find "API Keys" section
   • Copy your API key (or create a new one)

2. Redis REST Credentials:

   • Select your database in Upstash Console
   • Find "REST API" section on database details page
   • Copy UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN

3. QStash Credentials:

   • Go to QStash Console
   • Copy your QStash token from the dashboard
   • For webhook verification, copy the signing key

4. Vector Credentials:

   • Select your vector index in Upstash Console
   • Copy the REST URL and token from the index details

Resources & Operations

Redis Databases (12 operations)

Operation	Description
List	List all Redis databases
Create	Create a new Redis database
Create Global	Create a multi-region global database
Get	Get database details
Delete	Delete a database
Rename	Rename a database
Reset Password	Reset database password
Enable TLS	Enable TLS encryption
Set Eviction	Enable/disable eviction
Set Auto Scaling	Enable/disable auto-scaling
Move to Team	Move database to a team
Get Stats	Get database statistics

Redis Data Operations (33 operations)

Category	Operations
Strings	set, get, del, mset, mget, incr, decr, incrby, decrby
Keys	expire, ttl, exists, keys, scan, type, rename
Lists	lpush, rpush, lpop, rpop, lrange
Sets	sadd, smembers, srem
Hashes	hset, hget, hgetall, hdel
Sorted Sets	zadd, zrange, zrem
Pub/Sub	publish
Custom	executeCommand

Kafka Clusters (7 operations)

Operation	Description
List	List all Kafka clusters
Create	Create a new Kafka cluster
Get	Get cluster details
Delete	Delete a cluster
Rename	Rename a cluster
Reset Password	Reset cluster password
Get Stats	Get cluster statistics

Kafka Topics (6 operations)

Operation	Description
List	List topics in a cluster
Create	Create a new topic
Get	Get topic details
Delete	Delete a topic
Reconfigure	Update topic configuration
Get Stats	Get topic statistics

Kafka Credentials (3 operations)

Operation	Description
List	List credentials for a cluster
Create	Create new credentials
Delete	Delete credentials

Kafka Connectors (6 operations)

Operation	Description
List	List connectors in a cluster
Create	Create a new connector
Get	Get connector details
Delete	Delete a connector
Reconfigure	Update connector configuration
Restart	Restart a connector

QStash Messages (5 operations)

Operation	Description
Publish	Publish a message to a URL
Publish Batch	Publish multiple messages
Get	Get message details
Delete	Delete a scheduled message
Cancel	Cancel a scheduled message

QStash Schedules (6 operations)

Operation	Description
List	List all schedules
Create	Create a new schedule
Get	Get schedule details
Delete	Delete a schedule
Pause	Pause a schedule
Resume	Resume a schedule

QStash Dead Letter Queue (3 operations)

Operation	Description
List	List messages in DLQ
Delete	Delete message from DLQ
Retry	Retry message from DLQ

Vector Indexes (10 operations)

Operation	Description
List	List all vector indexes
Create	Create a new index
Get	Get index details
Delete	Delete an index
Get Stats	Get index statistics
Upsert	Insert or update vectors
Query	Query similar vectors
Delete Vectors	Delete vectors by ID
Fetch	Fetch vectors by ID
Reset	Reset (clear) index

Teams (5 operations)

Operation	Description
List	List teams
Get	Get team details
List Members	List team members
Add Member	Add member to team
Remove Member	Remove member from team

Usage & Billing (3 operations)

Operation	Description
Get Daily Stats	Get daily usage statistics
Get Monthly Stats	Get monthly usage statistics
Get Billing	Get billing information

Trigger Node

The Upstash Trigger node receives QStash webhook callbacks.

Events

Event	Description
Message Delivered	Triggered when a message is successfully delivered
Message Failed	Triggered when message delivery fails
Message DLQ	Triggered when a message is moved to dead letter queue
All Events	Receive all QStash webhook events

Configuration

1. Add the Upstash Trigger node to your workflow
2. Configure your Upstash credentials
3. Enable Verify Signature for security
4. Copy the webhook URL from n8n
5. Configure your QStash messages to callback to this URL

Usage Examples

Create and Use a Redis Database

// 1. Create a Redis database
{
  "resource": "redisDatabase",
  "operation": "create",
  "name": "my-cache",
  "region": "us-east-1",
  "tls": true
}

// 2. Store data
{
  "resource": "redisData",
  "operation": "set",
  "key": "user:123",
  "value": "{\"name\": \"John\", \"email\": \"john@example.com\"}",
  "ttl": 3600
}

// 3. Retrieve data
{
  "resource": "redisData",
  "operation": "get",
  "key": "user:123"
}

Schedule a Message with QStash

// Create a recurring schedule
{
  "resource": "qstashSchedule",
  "operation": "create",
  "destination": "https://api.example.com/process",
  "cron": "0 9 * * *",
  "body": "{\"type\": \"daily-report\"}",
  "retries": 3
}

Vector Similarity Search

// 1. Create an index
{
  "resource": "vectorIndex",
  "operation": "create",
  "indexName": "embeddings",
  "dimension": 1536,
  "metric": "cosine"
}

// 2. Upsert vectors
{
  "resource": "vectorIndex",
  "operation": "upsert",
  "indexName": "embeddings",
  "vectors": [
    {
      "id": "doc-1",
      "vector": [0.1, 0.2, ...],
      "metadata": {"title": "Document 1"}
    }
  ]
}

// 3. Query similar vectors
{
  "resource": "vectorIndex",
  "operation": "query",
  "indexName": "embeddings",
  "vector": [0.1, 0.2, ...],
  "topK": 10,
  "includeMetadata": true
}

Upstash Concepts

Serverless Architecture

Upstash provides serverless data services with pay-per-request pricing. Databases scale automatically and you only pay for what you use.

Global Databases

Redis databases can be deployed globally with read replicas in multiple regions for low-latency access worldwide.

REST APIs

All Upstash services offer HTTP-based REST APIs, making them accessible from serverless functions and edge computing environments where TCP connections aren't available.

QStash

QStash is a message queue and scheduler service that guarantees at-least-once delivery with automatic retries and dead letter queues.

Regions

Redis Regions

Region	Location
us-east-1	N. Virginia, USA
us-west-1	N. California, USA
us-west-2	Oregon, USA
eu-west-1	Ireland
eu-central-1	Frankfurt, Germany
ap-southeast-1	Singapore
ap-southeast-2	Sydney, Australia
ap-northeast-1	Tokyo, Japan
sa-east-1	São Paulo, Brazil

Kafka Regions

Region	Location
us-east-1	N. Virginia, USA
eu-west-1	Ireland
ap-southeast-1	Singapore

Error Handling

The node handles common Upstash API errors:

Status Code	Description	Handling
400	Bad Request	Check parameters
401	Unauthorized	Verify credentials
404	Not Found	Resource doesn't exist
429	Too Many Requests	Implement backoff
500	Server Error	Retry operation

Enable Continue On Fail in n8n to handle errors gracefully in workflows.

Security Best Practices

1. Use Environment Variables: Store credentials in environment variables, not in workflows
2. Enable TLS: Always enable TLS for Redis databases
3. Verify Signatures: Enable webhook signature verification for QStash triggers
4. Scope Credentials: Use topic-scoped Kafka credentials with minimal permissions
5. Read-Only Tokens: Use read-only Redis tokens when write access isn't needed

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Watch mode for development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: licensing@velobpa.com

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code:

• Passes all tests (npm test)
• Passes linting (npm run lint)
• Includes appropriate documentation
• Follows the existing code style

Support

• Documentation: Upstash Docs
• Issues: GitHub Issues
• n8n Community: n8n Community Forum

Acknowledgments

• Upstash for the excellent serverless data platform
• n8n for the powerful workflow automation platform
• The n8n community for inspiration and support