Description

n8n-nodes-duckdb-quack

DuckDB is an in-process SQL OLAP database management system. It runs embedded directly within the host application — no separate server process needed — and supports the full SQL standard with advanced analytical functions, windowing, and direct querying of Parquet, CSV, and JSON files. Often described as “SQLite for analytics,” it is designed for high-performance analytical workloads on datasets ranging from megabytes to hundreds of gigabytes.

Quack is DuckDB’s native remote-access protocol, built on HTTP/2 with gRPC streaming. It allows a DuckDB server to expose in-memory databases over the network, enabling multiple clients to query, write, and manage data through a high-performance binary protocol. Quack is currently in beta (DuckDB v1.5.3+) and is evolving rapidly — the protocol and function names are subject to change until the stable release in DuckDB v2.0.

> ⚠️ Work in Progress — this community node is provided “as is.” APIs, features, and behavior may change. We welcome feedback and contributions.

This node has been tested on the following configurations:

| Platform | n8n Installation | DuckDB Runtime |
|———-|—————–|—————-|
| Hostinger | Coolify (n8n standard image) | Docker container |
| Windows 11 | npm (local install) | WSL2 (DuckDB CLI) |

> No other configurations have been evaluated at this time.

Installation

This node has been successfully tested on a standard Hostinger server running n8n via Coolify with n8n’s regular image (docker.n8n.io/n8nio/n8n).

However, the @duckdb/node-api native module requires glibc. If your deployment uses an Alpine/musl-based image, switch to the Debian-based variant:

1. In your n8n Docker compose, use the Debian image:

   image: docker.n8n.io/n8nio/n8n:latest-debian
   

2. Install via Settings → Community Nodes → enter n8n-nodes-duckdb-quack

Environment

Requires DuckDB ≥ v1.5.3. The @duckdb/node-api native module requires glibc (not Alpine/musl). The Debian-based n8n image is mandatory.

Windows: Upgrading the package

Windows locks loaded native DLLs — upgrading the @duckdb/node-api native module while n8n is running will fail. If this happens, the node may appear as corrupted in the UI.

To recover: delete the corrupted node from Settings → Community Nodes, then reinstall it while n8n is stopped.

> Strongly recommended: test and develop this node on a Unix machine (Linux/macOS). Docker (n8nio/n8n:latest-debian) is the most reliable environment. Windows is supported but native module upgrades are fragile.

Credentials

Local Mode (File / In-Memory)

| Field | Description |
|——-|————-|
| Connection Mode | Local File / In-Memory RAM |
| File Path | :memory: for volatile scratchpads, or an absolute path (e.g., /data/analytics.db) |
| Auto-Install Extensions | Optional comma-separated list (e.g., spatial, fts). Core extension httpfs is loaded automatically. |

Multiple credentials pointing to the same file path share a single DuckDB instance.

Remote Mode (Quack Protocol)

| Field | Description |
|——-|————-|
| Connection Mode | Remote Quack Server (HTTP/2 Protocol) |
| Remote Server URI | Quack server address (e.g., quack:localhost:9494, quack:192.168.1.50:9494) |
| Authentication Token | Server token (minimum 4 characters) |
| Disable SSL Encryption | Check for plain HTTP connections (localhost or trusted private subnets). Non-local URIs default to HTTPS. |
| Auto-Install Extensions | Optional comma-separated list |

> Note: Quack is currently in beta (DuckDB v1.5.3+). The protocol and function names are subject to change until DuckDB v2.0 (September 2026).

Operations

Table Resource

| Operation | Description | Local | Remote |
|———–|————-|——-|——–|
| List Columns | Inspect column names, types, and definitions | ✅ | ✅ |
| List Tables | Fetch all tables in the current catalog | ✅ | ✅ |
| Read Table | Stream records (JSON or Parquet output) | ✅ | ✅ |
| Write / Append Rows | Insert data (Append or Overwrite modes) | ✅ | ✅ |
| Update Rows | Modify records using SQL WHERE clause and SET column-value pairs | ✅ | ✅ |
| Delete Rows | Remove records matching a SQL WHERE condition (required safety guard) | ✅ | ✅ |

Remote write operations use batch SQL INSERT to avoid appender chunk limits over HTTP.

Query Resource

| Operation | Description | Local | Remote |
|———–|————-|——-|——–|
| Select (Custom SQL) | Execute arbitrary SQL queries | ✅ | ✅ |
| Stateless Quack Query | Single round-trip query bypassing ATTACH | — | ✅ |
| Persist Memory to Disk | Save in-memory database to a .db file | ✅ | — |

Server Resource

| Operation | Description | Local | Remote |
|———–|————-|——-|——–|
| Get Server Info | Retrieve version, uptime, and configuration | — | ✅ |
| List Sessions | Active sessions with IDs and connected databases | — | ✅ |

Usage Examples

Local In-Memory

1. Create a credential: Connection Mode = Local, File Path = :memory:
2. Populate data with Table → Write (Overwrite mode, table name employees)
3. Query with Table → Read or Query → Select (Custom SQL) (SELECT * FROM employees WHERE score > 90)
4. Save with Query → Persist Memory to Disk → /home/user/my_data.db
5. Create a new credential pointing to my_data.db — the data is immediately available

Multiple credentials with :memory: share the same database instance, just like multiple credentials pointing to the same file.

Remote Quack Server

Option 1: WSL2 (recommended for Windows development)

1. In a WSL2 terminal, install DuckDB CLI:

   curl https://install.duckdb.org | sh
   export PATH="$HOME/.duckdb/cli/latest:$PATH"
   

2. Start the server:

   duckdb
   INSTALL quack;
   LOAD quack;
   CREATE TABLE products AS SELECT * FROM (VALUES (1, 'Widget', 9.99), (2, 'Gadget', 24.50)) t(id, name, price);
   CALL quackserve('quack:0.0.0.0:9494', token='mytoken', allowotherhostname:=true);
   

3. WSL2 auto-forwards localhost — use quack:localhost:9494 in n8n with Disable SSL checked

Option 2: Windows (DuckDB CLI)

1. Install the DuckDB CLI:

   winget install DuckDB.cli
   

2. Start an interactive DuckDB session:

   duckdb
   

3. In the DuckDB shell, start the Quack server:

   INSTALL quack;
   LOAD quack;
   CALL quackserve('quack:localhost:9494', token='mytoken', allowotherhostname:=true);
   

4. Keep the terminal open. In n8n, use credential quack:localhost:9494 with Disable SSL checked and token my_token.

Persist Memory to File

1. Build data in :memory: with Write operations
2. Use Query → Persist Memory to Disk with a .db file path
3. The file is created as a fully functional DuckDB database — all tables are copied with their original types
4. The .db file is immediately unlocked after the operation completes and can be opened by other processes
5. Create a new Local credential pointing to that file to access it later

Architecture

Connection Model

| Mode | DuckDB Instance | Caching |
|——|—————-|———|
| Local :memory: | Single shared instance per n8n process | ✅ Keyed by path |
| Local file | Instance per file path | ✅ Keyed by path |
| Remote Quack | :memory: instance per server host | ✅ Keyed by host |

Extensions are loaded once per instance and cached — subsequent executions skip the load step.

Remote Query Strategy

The node uses two approaches for remote Quack queries:

| Approach | Used For | Why |
|———-|———-|—–|
| quack_query() | Reads (List, Read, Select, Stateless) | Single round-trip, no streaming conflicts |
| ATTACH + session | Writes, Persist | Needs multi-statement sessions |

This avoids the “Multiple streaming scans” Quack protocol limitation.

Features

Write Mode: Column Types

Tables created by Write / Append Rows default to VARCHAR. When Write Mode is Overwrite / Recreate, a Column Types option appears:

| Option | Behavior |
|——–|———-|
| VARCHAR | All columns as text — safe, preserves everything |
| Auto-Detect | DuckDB infers: 95 → INTEGER, 95.5 → DOUBLE, "2024-01-15" → DATE, true → BOOLEAN |

Auto-Detect uses CREATE OR REPLACE TABLE ... AS SELECT * FROM (VALUES ...) for server-side type inference.

Multi-Statement SQL

The Select (Custom SQL) operation supports multi-statement blocks — DDL, DML, and PRAGMA execute before the final SELECT:

DROP TABLE IF EXISTS employees;
CREATE TABLE employees (id INTEGER, name VARCHAR);
INSERT INTO employees VALUES (1, 'Alice'), (2, 'Bob');
SELECT * FROM employees ORDER BY id;

Intermediate statement failures (e.g., index already exists) are silently skipped — the final SELECT always runs.

Extension Loading

Core extension httpfs loads automatically. Additional extensions via comma-separated list: spatial, fts, sqlite_scanner. Community repo syntax: gsheets FROM community. DuckDB’s JIT autoload is enabled by default.

License

MIT