n8n

This guide shows how to integrate SurrealDB with n8n, a fair-code licensed workflow automation platform.

The official n8n node for SurrealDB. It provides both action and tool nodes to interact with a SurrealDB database, allowing you to create, read, update, and delete records, as well as execute custom SurrealQL queries. It is available in the n8n Community Nodes repository.

Important
As with all community nodes, this node works only with self-hosted n8n instances, not with n8n Cloud. This node has been tested with SurrealDB v2.x

Features

Dual Node Types: Functions as both an action node and a tool node for AI workflows
Complete CRUD Operations: Create, read, update, and delete SurrealDB records
Custom Queries: Execute any SurrealQL query with full parameter support
Enhanced Query Builder: Visual interface for building SELECT queries with WHERE, ORDER BY, GROUP BY, and other clauses
Table Operations: List fields and explore table structure
Relationship Support: Query and manage record relationships
Native Data Format: Works with SurrealDB’s native data formats
Connection Pooling: Configurable connection pooling for improved performance and resource management
Enhanced Error Handling: Comprehensive error classification, automatic retry logic, and connection recovery
- Intelligent Recovery: Different error handling strategies for different operation types
- Detailed Error Reporting: Rich error context with categorization and severity levels
Pool Monitoring: Built-in pool statistics and performance monitoring

Prerequisites

You need a self-hosted n8n instance (v0.214.0 or later recommended).
You need access to a SurrealDB instance (2.0.0 or later recommended).

Installation Steps

Open your n8n instance
Go to Settings > Community Nodes
Click Install
Enter n8n-nodes-surrealdb and click Install
Restart your n8n instance if prompted

Note
To use this node as a tool in AI workflows, you must set the environment variable N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true.

Configuration

In order to use SurrealDB in n8n, you need to configure the SurrealDB node.

Credentials

To use the SurrealDB node, you need to create credentials with the following properties:

Property	Description
Connection String	The connection string to your SurrealDB instance (must start with `http://` or `https://`). WebSocket connections (`ws://` or `wss://`) are not supported.
Authentication	Choose the authentication scope:
Root	Full access to all namespaces and databases
Namespace	Access limited to a specific namespace
Database	Access limited to a specific database within a namespace
Username	Username for authentication
Password	Password for authentication
Namespace	Target namespace (required for Namespace and Database authentication)
Database	Target database (required for Database authentication)

The authentication type you choose affects how namespace and database information is handled. Depending on the authentication type, you will need to provide different information. See the table below for more details.

Authentication Type	Access Scope	Required Fields	Optional Fields	Override Capability
Root Authentication	All namespaces and databases	None	Namespace, Database	Can override namespace/database at node level
Namespace Authentication	All databases within a specific namespace	Namespace	Database	Can override database at node level
Database Authentication	Specific database within a specific namespace	Namespace, Database	None	Can override both at node level for specific operations

Node-Level Namespace and Database Overrides

For most operations, you can override the namespace and database settings from your credentials:

In the node configuration, expand the Options section
Enter values in the Namespace and/or Database fields
These values will take precedence over the credential settings for that specific operation
You will be required to provide a namespace when using Namespace authentication
You will be required to provide both a namespace and database when using Database authentication

Operations

The SurrealDB node provides a comprehensive set of operations organized by resource type. For anything not covered, you can use the Execute Query operation.

Category	Operation	Description
Record Operations	Create Record	Create a single record in a table
	Get Record	Retrieve a specific record by ID
	Update Record	Update a specific record by ID
	Upsert Record	Create or update a record (insert if not exists, update if exists)
	Delete Record	Delete a specific record by ID
Table Operations	Get All Records	Retrieve all records from a table
	Create Many	Create multiple records in a table
	Get Many	Retrieve multiple records by IDs
	Update All Records	Update all records in a table
	Delete All Records	Delete all records from a table
	Merge All Records	Merge the same data into all records in a table
	Create Table	Define a new table with optional schema
	Delete Table	Remove a table from the database
	Get Table	Retrieve information about a table
Field Operations	List Fields	List all fields defined on a table
	Create Field	Create a new field on a table
	Delete Field	Delete a field from a table
Index Operations	Create Index	Create a new index on a table
Index Operations	Delete Index	Delete an index from a table
Relationship Operations	Create Relationship	Create a relationship between two records
	Delete Relationship	Delete a relationship between records
	Query Relationships	Query relationships between records
Query Operations	Execute Query	Execute a raw SurrealQL query with parameters
Query Operations	Build Select Query	Build SELECT queries using a visual interface with WHERE, ORDER BY, GROUP BY, and other clauses
System Operations	Health Check	Check if the database instance is responsive
	Version	Get the version of the SurrealDB instance
	Get Pool Statistics	Monitor connection pool performance and statistics

Understanding SurrealDB and n8n Integration

Connection Protocol

Important
Due to n8n’s architecture, this node only supports HTTP/HTTPS connections to SurrealDB. WebSocket connections (WS/WSS) are not supported.

Your connection string must start with http:// or https:// (not ws:// or wss://). This means that when configuring your SurrealDB instance, ensure it’s accessible via HTTP/HTTPS.

If you’re using SurrealDB Cloud or another instance that only offers WebSocket connections, you’ll need to set up a self-hosted SurrealDB instance with HTTP enabled. This limitation is due to how n8n handles connections and executes node operations. You can read more about this in the n8n documentation.

This node uses the HTTP/HTTPS protocol exclusively, which means that each operation creates a new connection to SurrealDB, the connection is closed after the operation completes, and no persistent connection is maintained between operations.

Connection Pooling

The SurrealDB node includes comprehensive connection pooling to improve performance and resource management. Connection pooling allows the node to reuse database connections across multiple operations, reducing connection overhead and improving response times.

Pool Configuration Options

You can configure the connection pool through the “Connection Pooling” options in any node operation:

Max Connections (default: 10): Maximum number of connections in the pool
Min Connections (default: 2): Minimum number of connections to keep in the pool
Acquire Timeout (default: 30000ms): Maximum time to wait for a connection from the pool
Health Check Interval (default: 60000ms): Interval between health checks for pool connections
Max Idle Time (default: 300000ms): Maximum time a connection can remain idle before being closed
Retry Attempts (default: 3): Number of retry attempts for failed connection acquisitions
Retry Delay (default: 1000ms): Delay between retry attempts

Pool Monitoring

Use the System > Get Pool Statistics operation to monitor pool performance:

{
  "poolStatistics": {
    "totalConnections": 5,
    "activeConnections": 2,
    "idleConnections": 3,
    "waitingRequests": 0,
    "totalRequests": 150,
    "failedRequests": 2,
    "averageResponseTime": 45,
    "successRate": 99
  },
  "performance": {
    "averageResponseTimeMs": 45,
    "requestsPerSecond": 2,
    "errorRate": 1
  },
  "poolHealth": {
    "utilizationRate": 40,
    "availableConnections": 3,
    "waitingRequests": 0
  }
}

SurrealDB Result Handling

SurrealDB operations often return empty results rather than errors when no matching data is found. This behavior differs from many other databases and can be important to understand when building workflows:

Empty Results vs. Errors: A query for a non-existent record returns an empty result, not an error
Always Output Data: The “Always Output Data” option is particularly useful with SurrealDB to ensure your workflow continues even when no results are found

Working with SurrealDB Data Types

SurrealDB supports rich data types that map well to n8n’s JSON handling:

Records and IDs: SurrealDB record IDs use the format table:id
Relationships: Relationships are first-class citizens in SurrealDB
Arrays and Objects: Nested data structures are fully supported

Error Handling

The SurrealDB node includes a comprehensive error handling and recovery system that automatically manages common database issues:

Automatic Error Classification

The system automatically categorizes errors into different types:

Error Type	Description
Connection Errors	Network issues, timeouts, connection refused
Authentication Errors	Invalid credentials, unauthorized access
Query Errors	Syntax errors, malformed queries
Validation Errors	Invalid data, missing required fields
System Errors	Database server issues, internal errors

Intelligent Retry Logic

Exponential Backoff: Automatic retry with increasing delays
Operation-Specific Retries: Different retry strategies for read vs write operations
Configurable Limits: Adjustable retry counts and delays
Smart Error Filtering: Only retry on recoverable errors

Connection Recovery

Automatic Reconnection: Reconnects to SurrealDB on connection failures
Re-authentication: Automatically re-authenticates after reconnection
Connection Validation: Verifies connection health before retrying operations

Enhanced Error Reporting

When Continue on Fail is enabled, errors include detailed information:

{
  "error": {
    "message": "Connection timeout",
    "category": "TIMEOUT_ERROR",
    "severity": "MEDIUM",
    "retryable": true,
    "context": {
      "operation": "executeQuery",
      "itemIndex": 0,
      "timestamp": "2024-01-15T10:30:00Z",
      "recoveryStrategy": "CONNECTION_RECOVERY"
    }
  }
}

Error Handling Strategies

Different operation types use different error handling strategies:

Read Operations: Faster retries, continue on low/medium errors
Write Operations: More retries, stop on medium+ errors
Critical Operations: Minimal retries, stop on any error
Bulk Operations: Moderate retries, handle rate limiting

For detailed information about the error handling system, see Error Handling Documentation.

On this page

Was this page helpful?

What did you like?

What went wrong?