SQLiteStorage

The SQLite Storage operation interacts with an embedded SQLite database to execute custom SQL queries. It supports dynamic input binding for parameterized queries and provides flexible output mapping, allowing query results to be returned either as individual columns or as a structured table (an array of rows).

Inputs

Port	Type	Required	Description
> (Gate)	Any	No	When connected, a false or Nil value stops the path. See Gate Inputs.
In [2—21]	User-configurable	No	Flexible inputs bound to SQL placeholders ?2..?21. Port labels are user-editable; the index is what matters for binding. Up to 20 connectable inputs. Accepted MessagePack types per port are set in the Node’s Settings panel — see Setting Port Types.

Outputs

Port	Type	Default	Description
Out [1—20]	User-configurable	Nil	In Single Row mode, each column maps to Output #1..#N. In Table mode, the result set, up to extras.sqlite.maxRows rows, goes to Output #1 as an array of rows. Accepted MessagePack types per port are set in the Node’s Settings panel.

Properties

Name	Type	Default	Description
Init SQL	TextBox (multi-line)	""	SQL executed once in the constructor. Use for schema setup (e.g., CREATE TABLE IF NOT EXISTS ...).
SQL	TextBox (multi-line)	""	The SQL query executed at runtime. Positional placeholders ?2..?21 bind to inputs. ?1 is reserved (always Nil).
Output Mode	Combo	Single Row (columns to outputs)	How results map to outputs. Options: Single Row (columns to outputs) or Table (rows array to Output 1).
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

State on Reload

The SQLite database itself is the persistent state. The operation does not separately persist outputs across restarts — each execution reads from and writes to the database independently.

Placeholder indexing

SQL placeholders start at ?2 (for Input #2). ?1 is reserved and always bound to Nil. The gate input (Input #1) never binds to SQL placeholders.

---

How It Works

1. Gate check — If a Gate Input is connected, evaluate it. A false or Nil value stops the execution path; outputs keep their previous values.

2. Init SQL (constructor only) — If provided, the Init SQL runs once when the operation is constructed.

3. SQL preparation & input binding — The SQL property is prepared and values from connected inputs (Input #2 to #21) are bound to their corresponding placeholders (?2 to ?21).

4. Query execution — The prepared SQL is executed against the internal SQLite database.

5. Result processing — In Single Row mode, columns from the first row map to Output #1..#N (further rows are traced). In Table mode, the result set goes to Output #1 as an array of arrays. Table mode reads at most extras.sqlite.maxRows rows (see Configuration); past it the output holds the first of them and the Node reports a Warning.

6. Error handling — On SQL failure, the Node fails and the On Error verb resolves the failure.

---

Examples

Data format

All inputs and outputs use MessagePack internally. The examples below show values in JSON notation for readability.

Insert

SQL: INSERT INTO users (name, age) VALUES (?2, ?3);

Output Mode: Single Row

Input	Value
> (Gate)	true
Input #2	"Alice"
Input #3	30

A new row is inserted. No data is returned to outputs.

Update

SQL: UPDATE users SET age = ?2 WHERE name = ?3;

Output Mode: Single Row

Input	Value
Input #2	31
Input #3	"Alice"

The age of user “Alice” is updated to 31.

Select Single Row

SQL: SELECT name, age FROM users WHERE id = ?2;

Output Mode: Single Row

Input	Value
Input #2	1

Output #1: "Alice"   Output #2: 30

Select Table

SQL: SELECT name, age FROM users;

Output Mode: Table

Output #1: [["Alice", 30], ["Bob", 25]]

The result set, up to extras.sqlite.maxRows rows, is returned as a single nested array.

Gate Block

SQL: SELECT * FROM some_table;

Gate: false

The gate is closed. No SQL is executed, outputs retain their previous values, and the execution path stops at this Node.

---

Use Cases

• Storing and retrieving configuration data
• Logging events or sensor readings
• Implementing local databases for offline applications
• Managing application-specific data without a remote server

---

Notes

• Always use parameterized queries (?2, ?3, etc.) to prevent SQL injection.
• The Output Mode property is key: use Table for consolidated result sets and Single Row for mapping columns to distinct outputs.
• In Single Row mode, if the query returns more than one row, the first is used and a trace says so.
• The SQLite database file is managed internally by the system.

---

Error Handling

SQLite Storage can hit these errors: a SQL execution failure (syntax error, constraint violation, locked database, etc.).

It triggers the On Error verb you picked. See the Error Handling guide for the common On Error model; SQLite Storage’s options are:

Verb	What it does
Stop this branch (default)	This Node and its dependents stop; the Outputs keep their values and read as a failed update. Nodes that do not depend on this one still run.
Continue with the last value	Dependents run on the values the Outputs already hold, not stamped as new; it reads as a failed update.
Continue with the fallback	Dependents run on each Output’s per-output Fallback, stamped as this run’s value; it reads as a failed update. The Editor refuses a Task where a Fallback is unset.

A statement that did not run produced nothing to write, so the Operation itself writes no Output on this run: whatever a dependent reads is what the verb resolved.

An empty result set in Single Row mode — or a row with fewer columns than configured outputs — is not an error. The affected outputs are written with Nil; the operation completes successfully.

Gate closure is not an error — a closed Gate stops the Path and consults no verb.