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.

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

1. You need a self-hosted n8n instance (v0.214.0 or later recommended).

2. You need access to a SurrealDB instance (2.0.0 or later recommended).

Installation Steps

1. Open your n8n instance

2. Go to Settings > Community Nodes

3. Click Install

4. Enter n8n-nodes-surrealdb and click Install

5. Restart your n8n instance if prompted

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:

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.

Node-Level Namespace and Database Overrides

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

1. In the node configuration, expand the Options section

2. Enter values in the Namespace and/or Database fields

3. These values will take precedence over the credential settings for that specific operation

4. You will be required to provide a namespace when using Namespace authentication

5. 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.

Understanding SurrealDB and n8n Integration

Connection Protocol

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:

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.

Resources

• n8n Community Nodes Documentation

• SurrealDB Documentation

• SurrealQL Reference