@topcs/node-red-contrib-surrealdb 0.1.0

Node-RED nodes for SurrealDB (query + live queries)

npm install @topcs/node-red-contrib-surrealdb

node-red-contrib-surrealdb

Node-RED nodes to interact with SurrealDB, including a Live Query node.

Features:

• Config node for connection and authentication
• Query node for arbitrary SurrealQL (with variables)
• Live query node (table or custom LIVE SELECT) that emits change events

Install

From your Node-RED user directory:

npm install node-red-contrib-surrealdb

This package depends on surrealdb.

Nodes

• surrealdb-config – connection to SurrealDB. For live queries, use a WebSocket RPC URL like ws://127.0.0.1:8000/rpc and set Namespace/Database.
• surrealdb-query – run any SurrealQL. Put the query in the node or set msg.query. Optional variables from msg.vars.
• surrealdb-live – subscribe to live updates.
  • Mode "Table": subscribes via db.live(table, cb) and emits { action, payload }.
  • Mode "Custom": executes a LIVE SELECT ... statement and keeps the subscription id.
  • Control with msg.action of start, stop, or restart. Enable Autostart to subscribe on deploy.

Example

1. Add a surrealdb-config node pointing to ws://localhost:8000/rpc, set NS/DB and user/password.
2. Add SurrealDB live in Table mode with table person and connect to a Debug node.
3. Create/update/delete rows in person; events will stream into Node-RED.

Notes

• Live queries require a WebSocket RPC endpoint and a SurrealDB server version that supports live queries.
• The library API may differ slightly between versions of surrealdb. If you see connection or live() errors, update surrealdb to the latest version.

Query Variables

You can bind variables into SurrealQL using $name placeholders in the query. The Query node reads variables from a message field (default msg.vars). This avoids string concatenation and prevents injection.

• Configure

  • In the Query node, set Variables → “From msg” and Msg field → vars (default).
  • Use $varName in your SurrealQL where you want the bound value.

• SELECT example

  • Query: SELECT * FROM person WHERE age >= $min AND city = $city.
  • Inject msg:
    • msg.vars = { min: 21, city: "Rome" }

• CREATE with CONTENT

  • Query: CREATE person CONTENT $data.
  • Inject msg:
    • msg.vars = { data: { name: "Ada", age: 31 } }

• UPDATE/MERGE example

  • Query: UPDATE person:john MERGE $patch.
  • Inject msg:
    • msg.vars = { patch: { age: 33 } }

• Using msg.query

  • You can override the node’s Query field by setting msg.query at runtime and still pass msg.vars for variables.

• Notes

  • Variable names are case-sensitive and must match the $placeholder in the query.
  • Variables can be primitives, arrays, or objects (used with CONTENT/MERGE).
  • Variables cannot replace identifiers (e.g., table or field names). For dynamic table/record operations, prefer the Record node.

Local Development (no publish)

Develop and run this module locally in Node-RED without publishing to npm.

• Prerequisites

  • Install dependencies in this repo: npm install
  • Have Node-RED installed (globally or via npx). Example: npm install -g node-red

• Option 1: npm link (recommended)

  1. In this repo: npm link
  2. In your Node-RED user dir (usually ~/.node-red): npm link node-red-contrib-surrealdb
  3. Start Node-RED (verbose helps during dev): node-red -v
  4. After code changes, restart Node-RED to reload nodes.
  5. To unlink: in ~/.node-red run npm unlink node-red-contrib-surrealdb, then in this repo run npm unlink.

• Option 2: Local path install

  1. In this repo: npm install
  2. In ~/.node-red: npm install /absolute/path/to/node-red-contrib-surrealdb
  3. Start or restart Node-RED. Re-run step 2 after changes (or switch to Option 1 for faster iteration).

• Tips

  • Ensure the SurrealDB connection URL uses ws:// or wss:// and points to /rpc for live queries.
  • Use Node-RED debug logs: run with -v and check the console for node status and errors.

Example Flow

An importable example for testing the Live node is provided at examples/live-query-basic.json.

• Import

  • In Node-RED, menu → Import → select file → choose examples/live-query-basic.json.
  • Open the SurrealDB Live Demo tab.
  • Double-click the connection node and set URL/NS/DB and credentials.
  • The SurrealDB live node subscribes to table person with Autostart enabled.
  • Use the Start/Stop inject nodes to control the subscription if needed.

• Test

  • Create/update/delete records in the person table (e.g., from SurrealQL console or another flow).
  • Watch events appear in the Live Out Debug node. Messages contain msg.action and msg.payload.