SurrealDB
SurrealDB Docs Logo

Enter a search query

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

  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
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:

PropertyDescription
Connection StringThe connection string to your SurrealDB instance (must start with http:// or https://). WebSocket connections (ws:// or wss://) are not supported.
AuthenticationChoose the authentication scope:
RootFull access to all namespaces and databases
NamespaceAccess limited to a specific namespace
DatabaseAccess limited to a specific database within a namespace
UsernameUsername for authentication
PasswordPassword for authentication
NamespaceTarget namespace (required for Namespace and Database authentication)
DatabaseTarget 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 TypeAccess ScopeRequired FieldsOptional FieldsOverride Capability
Root AuthenticationAll namespaces and databasesNoneNamespace, DatabaseCan override namespace/database at node level
Namespace AuthenticationAll databases within a specific namespaceNamespaceDatabaseCan override database at node level
Database AuthenticationSpecific database within a specific namespaceNamespace, DatabaseNoneCan 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:

  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.

CategoryOperationDescription
Record OperationsCreate RecordCreate a single record in a table
Get RecordRetrieve a specific record by ID
Update RecordUpdate a specific record by ID
Upsert RecordCreate or update a record (insert if not exists, update if exists)
Delete RecordDelete a specific record by ID
Table OperationsGet All RecordsRetrieve all records from a table
Create ManyCreate multiple records in a table
Get ManyRetrieve multiple records by IDs
Update All RecordsUpdate all records in a table
Delete All RecordsDelete all records from a table
Merge All RecordsMerge the same data into all records in a table
Create TableDefine a new table with optional schema
Delete TableRemove a table from the database
Get TableRetrieve information about a table
Field OperationsList FieldsList all fields defined on a table
Create FieldCreate a new field on a table
Delete FieldDelete a field from a table
Index OperationsCreate IndexCreate a new index on a table
Delete IndexDelete an index from a table
Relationship OperationsCreate RelationshipCreate a relationship between two records
Delete RelationshipDelete a relationship between records
Query RelationshipsQuery relationships between records
Query OperationsExecute QueryExecute a raw SurrealQL query with parameters
Build Select QueryBuild SELECT queries using a visual interface with WHERE, ORDER BY, GROUP BY, and other clauses
System OperationsHealth CheckCheck if the database instance is responsive
VersionGet the version of the SurrealDB instance
Get Pool StatisticsMonitor 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 TypeDescription
Connection ErrorsNetwork issues, timeouts, connection refused
Authentication ErrorsInvalid credentials, unauthorized access
Query ErrorsSyntax errors, malformed queries
Validation ErrorsInvalid data, missing required fields
System ErrorsDatabase 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.

Resources

Edit this page on GitHub