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.
ImportantAs 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
SELECT
queries with WHERE
, ORDER BY
, GROUP BY
, and other clausesv0.214.0
or later recommended).2.0.0
or later recommended).n8n-nodes-surrealdb
and click InstallNoteTo use this node as a tool in AI workflows, you must set the environment variable
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
.
In order to use SurrealDB in n8n, you need to configure the SurrealDB node.
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 |
For most operations, you can override the namespace and database settings from your credentials:
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 |
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 |
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 |
ImportantDue 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.
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.
You can configure the connection pool through the “Connection Pooling” options in any node operation:
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 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:
SurrealDB supports rich data types that map well to n8n’s JSON handling:
table:id
The SurrealDB node includes a comprehensive error handling and recovery system that automatically manages common database issues:
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 |
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" } } }
Different operation types use different error handling strategies:
For detailed information about the error handling system, see Error Handling Documentation.