@relatalabs/n8n-nodes-relatasql 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `n8n-nodes-relatasql`.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Dates are npm publish dates.
+
+## [Unreleased]
+
+### Changed
+- The community node is now published under the canonical RelataLabs npm scope as `@relatalabs/n8n-nodes-relatasql`.
+- Wording and formatting of the node description in the package metadata.
+
+## [0.1.7] — 2026-07-07
+
+### Fixed
+- **Create Dump**: backend errors now reach the node with their real reason (the underlying
+  `pg_dump` error) and a support reference. The node requested the response as binary and
+  discarded the JSON error body, so every failure surfaced as the same generic message.
+
+## [0.1.6] — 2026-07-07
+
+### Changed
+- **Create Dump**: 2-hour HTTP timeout for large databases, and an explicit message when a
+  dump exceeds the limit instead of a silent cut-off.
+
+## [0.1.5] — 2026-07-03
+
+### Changed
+- The credential now defaults to the official cloud API (`https://api.relatasql.com`).
+  Self-hosting became the case you override explicitly instead of the default.
+
+## [0.1.4] — 2026-06-18
+
+### Changed
+- **Create Dump**: failure messages rewritten for the person reading them in n8n, rather than
+  passing through internal wording.
+
+## [0.1.3] — 2026-06-18
+
+### Changed
+- **Create Dump**: clearer error messages when a dump cannot be produced.
+
+## [0.1.2] — 2026-06-15
+
+### Added
+- **Database → Create Dump** operation: produces a gzip-compressed `.sql.gz` as binary data,
+  ready to hand to Google Drive, Dropbox, S3 or any other node in the workflow.
+
+## [0.1.1] — 2026-06-15
+
+### Changed
+- RelataSQL brand icons for the node and its credential.
+
+## [0.1.0] — 2026-06-15
+
+### Added
+- First public release of the community node: run SQL and inspect schemas across the database
+  connections of your RelataSQL workspace, authenticated with your API key.
+- This is a database-infrastructure integration only: it deliberately ships **no AI/LLM
+  features**.
+
+[Unreleased]: https://github.com/RelataSQL/n8n-nodes-relatasql/compare/v0.1.7...HEAD
+[0.1.7]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.7
+[0.1.6]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.6
+[0.1.5]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.5
+[0.1.4]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.4
+[0.1.3]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.3
+[0.1.2]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.2
+[0.1.1]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.1
+[0.1.0]: https://www.npmjs.com/package/n8n-nodes-relatasql/v/0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RelataSQL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# n8n-nodes-relatasql
+
+Official [n8n](https://n8n.io) community node for **[RelataSQL](https://relatasql.com)** — run SQL, inspect
+schemas, and govern writes across your RelataSQL database connections, straight from your automations.
+
+This node is a pure **database-infrastructure** integration. It deliberately does **not** include any AI/LLM
+operation: use n8n's native AI nodes (with your own key) to generate SQL or logic, then hand it to this node to
+execute safely against your databases. That keeps token costs on your side and avoids runaway-loop billing.
+
+## Installation
+
+In n8n: **Settings → Community Nodes → Install** and enter `@relatalabs/n8n-nodes-relatasql`.
+
+Self-hosted/manual: build this package (`npm install && npm run build`) and place/link it under your n8n custom
+extensions folder (`~/.n8n/custom`) or set `N8N_CUSTOM_EXTENSIONS` to its path.
+
+## Credentials
+
+Create a **RelataSQL API** credential:
+
+- **Base URL** — RelataSQL API base URL. Defaults to the official cloud API `https://api.relatasql.com` (no trailing slash).
+- **API Key** — generated in RelataSQL → **Settings → API Keys** (starts with `relata_live_`). Sent as
+  `Authorization: Bearer <key>`.
+
+The credential **Test** lists your connections to verify the key.
+
+## Operations
+
+**Connection**
+- *List* — connections reachable with this API key (also powers the connection dropdown).
+
+**Database** (Postgres + MySQL; queries run read-only)
+- *Execute Query* — run a read-only SQL query and return one item per row.
+- *Sample Rows* — first N rows of a table.
+- *Run in Sandbox* — execute SQL inside a transaction that is always rolled back (safe test).
+- *Create Dump* — run pg_dump/mysqldump and return a compressed `.sql.gz` as **binary**,
+  ready to hand to a Google Drive / Dropbox / S3 / FTP upload node. Scope = structure+data /
+  structure-only / data-only. Requires a paid plan.
+
+**Schema**
+- *Get Tables* / *Get Columns* / *Get Relations* — introspect a connection.
+
+**Write (with approval)** — the governed mutation path
+- *Request Approval* → returns an approval ID.
+- *Check Approval* → poll its status (a human approves it in RelataSQL → Settings → MCP → Approvals).
+- *Execute Approved* → run the approved statement.
+
+**Backup**
+- *List Schedules* — backup schedules reachable with this API key (also powers the schedule dropdown).
+- *Trigger Run* — run a schedule now (fire-and-forget; poll *List Logs* for the result).
+- *List Logs* — recent backup runs (status, size, duration, error).
+
+## Important constraints
+
+- **Enable the connection first.** Programmatic access is gated: in RelataSQL go to **Settings → MCP** and enable
+  access for each connection (choose an *indefinite* grant for unattended n8n flows). Otherwise calls fail with a
+  clear "connection not enabled for API access" error.
+- **Read vs write.** *Execute Query* is read-only by design. Mutations go through the **Write (with approval)**
+  flow, which requires a human approval in the RelataSQL UI.
+- **PostgreSQL only** for query/schema in this version. MySQL/MSSQL execution is coming on the backend.
+
+## Example: back up a database to Google Drive
+
+`RelataSQL: Create Dump` (pick the connection) → `Google Drive: Upload` (binary field `data`). Add a
+Schedule Trigger in front for a nightly backup to your own Drive — no intermediate storage needed.
+
+## Example: move data between databases
+
+`Execute Query` on connection A (read) → transform in n8n → `Request Write` on connection B → approve in
+RelataSQL → `Execute Approved`.
+
+## License
+
+[MIT](LICENSE)

package/dist/credentials/RelataSqlApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, Icon, INodeProperties } from 'n8n-workflow';
+export declare class RelataSqlApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: Icon;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/RelataSqlApi.credentials.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelataSqlApi = void 0;
+class RelataSqlApi {
+    constructor() {
+        this.name = 'relataSqlApi';
+        this.displayName = 'RelataSQL API';
+        this.icon = 'file:relatasql.png';
+        this.documentationUrl = 'https://github.com/RelataSQL/n8n-nodes-relatasql';
+        this.properties = [
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.relatasql.com',
+                required: true,
+                placeholder: 'https://api.relatasql.com',
+                description: 'RelataSQL API base URL (no trailing slash). Keep the default cloud API URL.',
+            },
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'A RelataSQL API key from Settings → API Keys (starts with "relata_live_").',
+            },
+        ];
+        // Injected on every request the node makes.
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        // Validates the key by listing connections (cheap, API-key-gated).
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/mcp/connections',
+            },
+        };
+    }
+}
+exports.RelataSqlApi = RelataSqlApi;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/nodes/RelataSql/GenericFunctions.d.ts

@@ -0,0 +1,49 @@
+import type { IDataObject, IExecuteFunctions, IHttpRequestMethods, ILoadOptionsFunctions } from 'n8n-workflow';
+export interface RelataConnection {
+    id: string;
+    name: string;
+    engine: string;
+    host: string;
+    port: number;
+    databaseName: string;
+    workspaceId: string;
+    workspaceName?: string;
+    mcpAccessStatus: 'ACTIVE' | 'INACTIVE' | 'EXPIRED' | 'INDEFINITE';
+    mcpGrantedUntil: string | null;
+}
+export interface RelataColumn {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    isPrimaryKey?: boolean;
+}
+export interface RelataTable {
+    schema: string;
+    name: string;
+    columns: RelataColumn[];
+}
+export interface RelataSchema {
+    connectionId: string;
+    tables: RelataTable[];
+}
+export interface RelataQueryResult {
+    columns: string[];
+    rows: unknown[][];
+    rowCount: number;
+    truncated?: boolean;
+}
+type RequestContext = IExecuteFunctions | ILoadOptionsFunctions;
+/**
+ * Single entry point for every call to the RelataSQL backend. Resolves the
+ * credential's base URL, lets n8n inject the Bearer auth header, and maps
+ * backend errors (notably the JIT access gate) to actionable messages.
+ */
+export declare function relataApiRequest(this: RequestContext, method: IHttpRequestMethods, path: string, body?: IDataObject): Promise<any>;
+/** Turns the backend's columnar result into row objects n8n can map. */
+export declare function rowsToObjects(columns: string[], rows: unknown[][]): IDataObject[];
+/** Splits a "schema.table" dropdown value into its parts. */
+export declare function splitQualifiedTable(value: string): {
+    schema: string;
+    table: string;
+};
+export {};

package/dist/nodes/RelataSql/GenericFunctions.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relataApiRequest = relataApiRequest;
+exports.rowsToObjects = rowsToObjects;
+exports.splitQualifiedTable = splitQualifiedTable;
+const n8n_workflow_1 = require("n8n-workflow");
+/**
+ * Single entry point for every call to the RelataSQL backend. Resolves the
+ * credential's base URL, lets n8n inject the Bearer auth header, and maps
+ * backend errors (notably the JIT access gate) to actionable messages.
+ */
+async function relataApiRequest(method, path, body) {
+    var _a;
+    const credentials = await this.getCredentials('relataSqlApi');
+    const baseUrl = String((_a = credentials.baseUrl) !== null && _a !== void 0 ? _a : '').replace(/\/+$/, '');
+    if (!baseUrl) {
+        throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'RelataSQL "Base URL" is not set in the credential.');
+    }
+    const options = {
+        method,
+        url: `${baseUrl}${path}`,
+        headers: { Accept: 'application/json' },
+        json: true,
+    };
+    if (body !== undefined) {
+        options.body = body;
+    }
+    try {
+        return await this.helpers.httpRequestWithAuthentication.call(this, 'relataSqlApi', options);
+    }
+    catch (error) {
+        throw mapRelataError(this, error);
+    }
+}
+function extractMessage(error) {
+    var _a;
+    const parts = [];
+    if (typeof (error === null || error === void 0 ? void 0 : error.message) === 'string')
+        parts.push(error.message);
+    const resp = error === null || error === void 0 ? void 0 : error.response;
+    if (resp) {
+        const b = (_a = resp.body) !== null && _a !== void 0 ? _a : resp.data;
+        if (typeof b === 'string')
+            parts.push(b);
+        else if (b && typeof b === 'object') {
+            if (typeof b.message === 'string')
+                parts.push(b.message);
+            else
+                parts.push(JSON.stringify(b));
+        }
+    }
+    if (typeof (error === null || error === void 0 ? void 0 : error.description) === 'string')
+        parts.push(error.description);
+    return parts.join(' | ');
+}
+function mapRelataError(ctx, error) {
+    const node = ctx.getNode();
+    const text = extractMessage(error);
+    if (text.includes('JIT_ACCESS_REQUIRED')) {
+        return new n8n_workflow_1.NodeOperationError(node, 'This RelataSQL connection is not enabled for programmatic (API key) access.', {
+            description: 'Open RelataSQL → Settings → MCP and enable access for this connection (pick an indefinite grant for unattended n8n flows), then retry.',
+        });
+    }
+    if (text.includes('only supports Postgres') || text.includes('NotImplemented')) {
+        return new n8n_workflow_1.NodeOperationError(node, 'RelataSQL currently supports only PostgreSQL connections for this operation.', {
+            description: 'MySQL/MSSQL execution is not yet available on the RelataSQL backend.',
+        });
+    }
+    if (error instanceof n8n_workflow_1.NodeOperationError || error instanceof n8n_workflow_1.NodeApiError) {
+        return error;
+    }
+    return new n8n_workflow_1.NodeApiError(node, error);
+}
+/** Turns the backend's columnar result into row objects n8n can map. */
+function rowsToObjects(columns, rows) {
+    return rows.map((row) => {
+        const obj = {};
+        columns.forEach((col, i) => {
+            obj[col] = row[i];
+        });
+        return obj;
+    });
+}
+/** Splits a "schema.table" dropdown value into its parts. */
+function splitQualifiedTable(value) {
+    const idx = value.indexOf('.');
+    if (idx < 0)
+        return { schema: 'public', table: value };
+    return { schema: value.slice(0, idx), table: value.slice(idx + 1) };
+}

package/dist/nodes/RelataSql/RelataSql.node.d.ts

@@ -0,0 +1,12 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class RelataSql implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getConnections(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTables(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getSchedules(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/RelataSql/RelataSql.node.js

@@ -0,0 +1,679 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelataSql = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const GenericFunctions_1 = require("./GenericFunctions");
+class RelataSql {
+    constructor() {
+        this.description = {
+            displayName: 'RelataSQL',
+            name: 'relataSql',
+            icon: 'file:relatasql.png',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
+            description: 'Run SQL, inspect schemas, and govern writes across your RelataSQL database connections',
+            defaults: { name: 'RelataSQL' },
+            usableAsTool: true,
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [{ name: 'relataSqlApi', required: true }],
+            properties: [
+                // ── Resource ────────────────────────────────────────────────
+                {
+                    displayName: 'Resource',
+                    name: 'resource',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        { name: 'Backup', value: 'backups' },
+                        { name: 'Connection', value: 'connection' },
+                        { name: 'Database', value: 'database' },
+                        { name: 'Schema', value: 'schema' },
+                        { name: 'Write (With Approval)', value: 'write' },
+                    ],
+                    default: 'database',
+                },
+                // ── Operations: Connection ──────────────────────────────────
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ['connection'] } },
+                    options: [
+                        {
+                            name: 'List',
+                            value: 'list',
+                            action: 'List database connections',
+                            description: 'List the database connections reachable with this API key',
+                        },
+                    ],
+                    default: 'list',
+                },
+                // ── Operations: Database ────────────────────────────────────
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ['database'] } },
+                    options: [
+                        {
+                            name: 'Create Dump',
+                            value: 'createDump',
+                            action: 'Create a compressed SQL dump',
+                            description: 'Run pg_dump/mysqldump and return a .sql.gz binary file (e.g. to upload to Google Drive)',
+                        },
+                        {
+                            name: 'Execute Query',
+                            value: 'executeQuery',
+                            action: 'Execute a read-only SQL query',
+                            description: 'Run a read-only SQL query (BEGIN READ ONLY) and return rows',
+                        },
+                        {
+                            name: 'Sample Rows',
+                            value: 'sampleRows',
+                            action: 'Sample rows from a table',
+                            description: 'Return the first N rows of a table',
+                        },
+                        {
+                            name: 'Run in Sandbox',
+                            value: 'sandbox',
+                            action: 'Run SQL in a rolled-back sandbox',
+                            description: 'Execute SQL inside a transaction that is always rolled back (safe test)',
+                        },
+                    ],
+                    default: 'executeQuery',
+                },
+                // ── Operations: Schema ──────────────────────────────────────
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ['schema'] } },
+                    options: [
+                        {
+                            name: 'Get Tables',
+                            value: 'getTables',
+                            action: 'Get tables',
+                            description: 'List tables (and column counts) for a connection',
+                        },
+                        {
+                            name: 'Get Columns',
+                            value: 'getColumns',
+                            action: 'Get columns of a table',
+                            description: 'List the columns of a single table',
+                        },
+                        {
+                            name: 'Get Relations',
+                            value: 'getRelations',
+                            action: 'Get foreign key relations',
+                            description: 'List foreign-key relationships for a connection',
+                        },
+                    ],
+                    default: 'getTables',
+                },
+                // ── Operations: Write ───────────────────────────────────────
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ['write'] } },
+                    options: [
+                        {
+                            name: 'Request Approval',
+                            value: 'requestApproval',
+                            action: 'Request approval for a write',
+                            description: 'Submit a write statement for human approval in RelataSQL',
+                        },
+                        {
+                            name: 'Check Approval',
+                            value: 'checkApproval',
+                            action: 'Check approval status',
+                            description: 'Get the current status of a write approval',
+                        },
+                        {
+                            name: 'Execute Approved',
+                            value: 'executeApproved',
+                            action: 'Execute an approved write',
+                            description: 'Execute a write that has been approved in RelataSQL',
+                        },
+                    ],
+                    default: 'requestApproval',
+                },
+                // ── Operations: Backups ─────────────────────────────────────
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ['backups'] } },
+                    options: [
+                        {
+                            name: 'List Schedules',
+                            value: 'listSchedules',
+                            action: 'List backup schedules',
+                            description: 'List the backup schedules reachable with this API key',
+                        },
+                        {
+                            name: 'Trigger Run',
+                            value: 'triggerRun',
+                            action: 'Trigger a backup run now',
+                            description: 'Manually run a backup schedule immediately',
+                        },
+                        {
+                            name: 'List Logs',
+                            value: 'listLogs',
+                            action: 'List recent backup runs',
+                            description: 'List recent backup run logs',
+                        },
+                    ],
+                    default: 'listSchedules',
+                },
+                // ── scheduleId (backups → triggerRun) ───────────────────────
+                {
+                    displayName: 'Schedule Name or ID',
+                    name: 'scheduleId',
+                    type: 'options',
+                    typeOptions: { loadOptionsMethod: 'getSchedules' },
+                    required: true,
+                    default: '',
+                    description: 'The backup schedule to run. Choose from the list, or specify an ID using an expression.',
+                    displayOptions: { show: { resource: ['backups'], operation: ['triggerRun'] } },
+                },
+                // ── connectionId (database / schema) ────────────────────────
+                {
+                    displayName: 'Connection Name or ID',
+                    name: 'connectionId',
+                    type: 'options',
+                    typeOptions: { loadOptionsMethod: 'getConnections' },
+                    required: true,
+                    default: '',
+                    description: 'The RelataSQL connection to target. Choose from the list, or specify an ID using an expression.',
+                    displayOptions: { show: { resource: ['database', 'schema'] } },
+                },
+                // ── connectionId (write → requestApproval) ──────────────────
+                {
+                    displayName: 'Connection Name or ID',
+                    name: 'connectionId',
+                    type: 'options',
+                    typeOptions: { loadOptionsMethod: 'getConnections' },
+                    required: true,
+                    default: '',
+                    description: 'The RelataSQL connection to target. Choose from the list, or specify an ID using an expression.',
+                    displayOptions: { show: { resource: ['write'], operation: ['requestApproval'] } },
+                },
+                // ── SQL query (executeQuery / sandbox / requestApproval) ────
+                {
+                    displayName: 'SQL Query',
+                    name: 'sqlQuery',
+                    type: 'string',
+                    typeOptions: { rows: 6 },
+                    default: '',
+                    required: true,
+                    placeholder: 'SELECT * FROM users LIMIT 100',
+                    description: 'The SQL statement to run',
+                    displayOptions: {
+                        show: {
+                            resource: ['database', 'write'],
+                            operation: ['executeQuery', 'sandbox', 'requestApproval'],
+                        },
+                    },
+                },
+                // ── Table (sampleRows / getColumns) ─────────────────────────
+                {
+                    displayName: 'Table Name or ID',
+                    name: 'table',
+                    type: 'options',
+                    typeOptions: {
+                        loadOptionsMethod: 'getTables',
+                        loadOptionsDependsOn: ['connectionId'],
+                    },
+                    required: true,
+                    default: '',
+                    description: 'The table to use (shown as schema.table). Choose from the list, or specify using an expression.',
+                    displayOptions: {
+                        show: { resource: ['database', 'schema'], operation: ['sampleRows', 'getColumns'] },
+                    },
+                },
+                {
+                    displayName: 'Limit',
+                    name: 'limit',
+                    type: 'number',
+                    typeOptions: { minValue: 1, maxValue: 50 },
+                    default: 10,
+                    description: 'Max number of rows to sample',
+                    displayOptions: { show: { resource: ['database'], operation: ['sampleRows'] } },
+                },
+                // ── Create Dump options ─────────────────────────────────────
+                {
+                    displayName: 'Scope',
+                    name: 'scope',
+                    type: 'options',
+                    options: [
+                        { name: 'Structure + Data', value: 'structure-and-data' },
+                        { name: 'Structure Only', value: 'structure-only' },
+                        { name: 'Data Only', value: 'data-only' },
+                    ],
+                    default: 'structure-and-data',
+                    description: 'What to include in the dump',
+                    displayOptions: { show: { resource: ['database'], operation: ['createDump'] } },
+                },
+                {
+                    displayName: 'Put Output File in Field',
+                    name: 'binaryPropertyName',
+                    type: 'string',
+                    default: 'data',
+                    required: true,
+                    hint: 'The name of the output binary field to write the .sql.gz file to',
+                    displayOptions: { show: { resource: ['database'], operation: ['createDump'] } },
+                },
+                // ── Justification (sandbox / requestApproval) ───────────────
+                {
+                    displayName: 'Justification',
+                    name: 'justification',
+                    type: 'string',
+                    default: '',
+                    required: true,
+                    placeholder: 'Why this statement runs',
+                    description: 'A short reason recorded for audit/approval',
+                    displayOptions: {
+                        show: { resource: ['database', 'write'], operation: ['sandbox', 'requestApproval'] },
+                    },
+                },
+                {
+                    displayName: 'Operation Summary',
+                    name: 'operationSummary',
+                    type: 'string',
+                    default: '',
+                    description: 'Optional human-readable summary of the write',
+                    displayOptions: { show: { resource: ['write'], operation: ['requestApproval'] } },
+                },
+                // ── Approval ID (checkApproval / executeApproved) ───────────
+                {
+                    displayName: 'Approval ID',
+                    name: 'approvalId',
+                    type: 'string',
+                    default: '',
+                    required: true,
+                    description: 'The ID returned by "Request Approval"',
+                    displayOptions: {
+                        show: { resource: ['write'], operation: ['checkApproval', 'executeApproved'] },
+                    },
+                },
+            ],
+        };
+        this.methods = {
+            loadOptions: {
+                async getConnections() {
+                    const connections = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', '/mcp/connections'));
+                    return (connections !== null && connections !== void 0 ? connections : []).map((c) => ({
+                        name: `${c.name} (${c.engine} · ${c.databaseName})`,
+                        value: c.id,
+                        description: `${c.host}:${c.port} — MCP access: ${c.mcpAccessStatus}`,
+                    }));
+                },
+                async getTables() {
+                    var _a;
+                    const connectionId = this.getCurrentNodeParameter('connectionId');
+                    if (!connectionId)
+                        return [];
+                    const schema = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', `/mcp/connections/${encodeURIComponent(connectionId)}/schema`));
+                    return ((_a = schema.tables) !== null && _a !== void 0 ? _a : []).map((t) => ({
+                        name: `${t.schema}.${t.name}`,
+                        value: `${t.schema}.${t.name}`,
+                    }));
+                },
+                async getSchedules() {
+                    const schedules = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', '/mcp/backups/schedules'));
+                    return (schedules !== null && schedules !== void 0 ? schedules : []).map((s) => ({
+                        name: `${s.name} (${s.cron})${s.enabled ? '' : ' — disabled'}`,
+                        value: s.id,
+                    }));
+                },
+            },
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const resource = this.getNodeParameter('resource', 0);
+        const operation = this.getNodeParameter('operation', 0);
+        for (let i = 0; i < items.length; i++) {
+            try {
+                if (resource === 'database' && operation === 'createDump') {
+                    returnData.push(await createDumpItem.call(this, i));
+                    continue;
+                }
+                const out = await runOperation.call(this, resource, operation, i);
+                for (const json of out) {
+                    returnData.push({ json, pairedItem: { item: i } });
+                }
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: { error: error.message },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.RelataSql = RelataSql;
+async function runOperation(resource, operation, i) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (resource === 'connection' && operation === 'list') {
+        const connections = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', '/mcp/connections'));
+        return (connections !== null && connections !== void 0 ? connections : []);
+    }
+    if (resource === 'database') {
+        const connectionId = this.getNodeParameter('connectionId', i);
+        const cid = encodeURIComponent(connectionId);
+        if (operation === 'executeQuery') {
+            const sql = this.getNodeParameter('sqlQuery', i);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/connections/${cid}/query`, { sql }));
+            return resultToItems(res);
+        }
+        if (operation === 'sampleRows') {
+            const tableValue = this.getNodeParameter('table', i);
+            const limit = this.getNodeParameter('limit', i);
+            const { schema, table } = (0, GenericFunctions_1.splitQualifiedTable)(tableValue);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/connections/${cid}/sample-rows`, { schema, table, limit }));
+            return resultToItems(res);
+        }
+        if (operation === 'sandbox') {
+            const sql = this.getNodeParameter('sqlQuery', i);
+            const justification = this.getNodeParameter('justification', i);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/connections/${cid}/sandbox`, { sql, justification }));
+            return [
+                {
+                    ok: res.ok,
+                    rolledBack: res.rolledBack,
+                    rowCount: res.rowCount,
+                    rows: (0, GenericFunctions_1.rowsToObjects)((_a = res.columns) !== null && _a !== void 0 ? _a : [], (_b = res.rows) !== null && _b !== void 0 ? _b : []),
+                    error: (_c = res.error) !== null && _c !== void 0 ? _c : null,
+                },
+            ];
+        }
+    }
+    if (resource === 'schema') {
+        const connectionId = this.getNodeParameter('connectionId', i);
+        const cid = encodeURIComponent(connectionId);
+        if (operation === 'getTables') {
+            const schema = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', `/mcp/connections/${cid}/schema`));
+            return ((_d = schema.tables) !== null && _d !== void 0 ? _d : []).map((t) => {
+                var _a, _b;
+                return ({
+                    schema: t.schema,
+                    name: t.name,
+                    columnCount: (_b = (_a = t.columns) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0,
+                });
+            });
+        }
+        if (operation === 'getColumns') {
+            const tableValue = this.getNodeParameter('table', i);
+            const { schema: schemaName, table } = (0, GenericFunctions_1.splitQualifiedTable)(tableValue);
+            const schema = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', `/mcp/connections/${cid}/schema`));
+            const match = ((_e = schema.tables) !== null && _e !== void 0 ? _e : []).find((t) => t.schema === schemaName && t.name === table);
+            return ((_f = match === null || match === void 0 ? void 0 : match.columns) !== null && _f !== void 0 ? _f : []).map((c) => ({ ...c }));
+        }
+        if (operation === 'getRelations') {
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', `/mcp/connections/${cid}/relations`));
+            return ((_g = res.relations) !== null && _g !== void 0 ? _g : []);
+        }
+    }
+    if (resource === 'write') {
+        if (operation === 'requestApproval') {
+            const connectionId = this.getNodeParameter('connectionId', i);
+            const sql = this.getNodeParameter('sqlQuery', i);
+            const justification = this.getNodeParameter('justification', i);
+            const operationSummary = this.getNodeParameter('operationSummary', i, '');
+            const body = { sql, justification };
+            if (operationSummary)
+                body.operationSummary = operationSummary;
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/connections/${encodeURIComponent(connectionId)}/write-approvals`, body));
+            return [res];
+        }
+        if (operation === 'checkApproval') {
+            const approvalId = this.getNodeParameter('approvalId', i);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', `/mcp/write-approvals/${encodeURIComponent(approvalId)}`));
+            return [res];
+        }
+        if (operation === 'executeApproved') {
+            const approvalId = this.getNodeParameter('approvalId', i);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/write-approvals/${encodeURIComponent(approvalId)}/execute`));
+            return resultToItems(res);
+        }
+    }
+    if (resource === 'backups') {
+        if (operation === 'listSchedules') {
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', '/mcp/backups/schedules'));
+            return res !== null && res !== void 0 ? res : [];
+        }
+        if (operation === 'triggerRun') {
+            const scheduleId = this.getNodeParameter('scheduleId', i);
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'POST', `/mcp/backups/schedules/${encodeURIComponent(scheduleId)}/run`));
+            return [res];
+        }
+        if (operation === 'listLogs') {
+            const res = (await GenericFunctions_1.relataApiRequest.call(this, 'GET', '/mcp/backups/logs'));
+            return res !== null && res !== void 0 ? res : [];
+        }
+    }
+    throw new Error(`Unsupported operation "${operation}" for resource "${resource}"`);
+}
+/**
+ * Database → Create Dump: POST the dump request, receive the gzipped binary,
+ * and emit it as an n8n binary item (ready for a Google Drive / S3 / FTP node).
+ */
+async function createDumpItem(i) {
+    var _a, _b, _c, _d;
+    const connectionId = this.getNodeParameter('connectionId', i);
+    const scope = this.getNodeParameter('scope', i, 'structure-and-data');
+    const binaryProperty = this.getNodeParameter('binaryPropertyName', i, 'data');
+    const allowedScopes = ['structure-and-data', 'structure-only', 'data-only'];
+    if (!allowedScopes.includes(scope)) {
+        throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Invalid scope "${scope}". Use one of: ${allowedScopes.join(', ')}.`);
+    }
+    const credentials = await this.getCredentials('relataSqlApi');
+    const baseUrl = String((_a = credentials.baseUrl) !== null && _a !== void 0 ? _a : '').replace(/\/+$/, '');
+    let response;
+    try {
+        response = (await this.helpers.httpRequestWithAuthentication.call(this, 'relataSqlApi', {
+            method: 'POST',
+            url: `${baseUrl}/mcp/connections/${encodeURIComponent(connectionId)}/dump`,
+            body: JSON.stringify({ scope }),
+            headers: { 'Content-Type': 'application/json' },
+            json: false,
+            encoding: 'arraybuffer',
+            returnFullResponse: true,
+            // Don't throw on 4xx/5xx: with arraybuffer encoding n8n discards the
+            // error body, so we'd lose the backend's real reason (code, detail,
+            // support reference). We inspect the status ourselves below.
+            ignoreHttpStatusErrors: true,
+            // A large database can take many minutes to dump. Wait up to 2h so the
+            // node never gives up before the backend's own dump timeout
+            // (DUMP_TIMEOUT_MS, default 2h). A reverse proxy in front of RelataSQL
+            // must allow an equally long read/idle timeout.
+            timeout: 2 * 60 * 60 * 1000,
+        }));
+    }
+    catch (error) {
+        // Transport-level failure (timeout, connection reset) — still throws.
+        throw mapDumpError(this, error);
+    }
+    // HTTP error status: the (arraybuffer) body holds the JSON error; hand the
+    // whole thing to mapDumpError so it surfaces the backend's real reason.
+    const status = Number((_b = response.statusCode) !== null && _b !== void 0 ? _b : 200);
+    if (status >= 400) {
+        throw mapDumpError(this, {
+            statusCode: status,
+            response: { statusCode: status, body: response.body },
+        });
+    }
+    const raw = response.body;
+    let buffer;
+    if (Buffer.isBuffer(raw)) {
+        buffer = raw;
+    }
+    else if (raw instanceof Uint8Array || raw instanceof ArrayBuffer) {
+        buffer = Buffer.from(raw);
+    }
+    else {
+        throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'RelataSQL returned an empty or unexpected dump response.');
+    }
+    const disposition = String((_d = (_c = response.headers) === null || _c === void 0 ? void 0 : _c['content-disposition']) !== null && _d !== void 0 ? _d : '');
+    const m = /filename="?([^"]+)"?/.exec(disposition);
+    const fileName = m ? m[1] : `${connectionId}.sql.gz`;
+    const binaryData = await this.helpers.prepareBinaryData(buffer, fileName, 'application/gzip');
+    return {
+        json: { fileName, mimeType: 'application/gzip', sizeBytes: buffer.length },
+        binary: { [binaryProperty]: binaryData },
+        pairedItem: { item: i },
+    };
+}
+function extractDumpErrorDetails(error) {
+    var _a, _b, _c, _d;
+    const parts = [];
+    let detail;
+    const statusCode = [
+        error === null || error === void 0 ? void 0 : error.statusCode,
+        error === null || error === void 0 ? void 0 : error.status,
+        error === null || error === void 0 ? void 0 : error.httpCode,
+        (_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.statusCode,
+        (_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.status,
+    ].find((value) => typeof value === 'number');
+    const addObject = (value) => {
+        for (const key of ['code', 'message', 'error', 'description', 'detail']) {
+            const part = value[key];
+            if (typeof part === 'string') {
+                parts.push(part);
+                // The backend's `detail` carries the real dump-tool error.
+                if (key === 'detail' && part.trim())
+                    detail = part.trim();
+            }
+            else if (Array.isArray(part))
+                parts.push(part.join(', '));
+        }
+        try {
+            parts.push(JSON.stringify(value));
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    const addBody = (body) => {
+        if (!body)
+            return;
+        try {
+            if (Buffer.isBuffer(body)) {
+                addBody(body.toString('utf8'));
+            }
+            else if (body instanceof ArrayBuffer) {
+                addBody(Buffer.from(body).toString('utf8'));
+            }
+            else if (body instanceof Uint8Array) {
+                addBody(Buffer.from(body).toString('utf8'));
+            }
+            else if (typeof body === 'string') {
+                parts.push(body);
+                try {
+                    const parsed = JSON.parse(body);
+                    if (parsed && typeof parsed === 'object') {
+                        addObject(parsed);
+                    }
+                }
+                catch {
+                    /* body was plain text */
+                }
+            }
+            else if (typeof body === 'object') {
+                addObject(body);
+            }
+        }
+        catch {
+            /* ignore malformed error bodies */
+        }
+    };
+    addBody(error === null || error === void 0 ? void 0 : error.message);
+    addBody(error === null || error === void 0 ? void 0 : error.description);
+    addBody((_c = error === null || error === void 0 ? void 0 : error.response) === null || _c === void 0 ? void 0 : _c.body);
+    addBody((_d = error === null || error === void 0 ? void 0 : error.response) === null || _d === void 0 ? void 0 : _d.data);
+    addBody(error === null || error === void 0 ? void 0 : error.error);
+    return { text: parts.join(' | '), statusCode, detail };
+}
+/** Pulls the backend's support reference (dump-<uuid>) out of an error body. */
+function extractSupportReference(text) {
+    var _a;
+    const m = (_a = /"supportReference"\s*:\s*"([^"]+)"/.exec(text)) !== null && _a !== void 0 ? _a : /(dump-[0-9a-fA-F-]{8,})/.exec(text);
+    return m === null || m === void 0 ? void 0 : m[1];
+}
+function mapDumpError(ctx, error) {
+    const { text, statusCode, detail } = extractDumpErrorDetails(error);
+    const lower = text.toLowerCase();
+    const ref = extractSupportReference(text);
+    const refHint = ref ? ` Support reference: ${ref}.` : '';
+    const detailHint = detail ? ` Backend error: ${detail}` : '';
+    // Client- or proxy-side timeout: the node/proxy gave up waiting. Distinct
+    // from a backend dump failure so the user knows to raise the time limit
+    // rather than "check the connection".
+    if (statusCode === 504 ||
+        statusCode === 408 ||
+        lower.includes('econnaborted') ||
+        lower.includes('etimedout') ||
+        lower.includes('socket hang up') ||
+        /timeout of \d+ *ms exceeded/.test(lower) ||
+        lower.includes('timed out')) {
+        return new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'The database dump timed out before it finished.', {
+            description: 'The database is large and the export exceeded the time limit. Raise DUMP_TIMEOUT_MS on the RelataSQL backend (and any reverse-proxy read/idle timeout), then retry. For very large databases, consider dumping "Structure only" or splitting the export by table.',
+        });
+    }
+    if (text.includes('JIT_ACCESS_REQUIRED')) {
+        return new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'This RelataSQL connection is not enabled for programmatic (API key) access.', {
+            description: 'Enable MCP access for this connection in RelataSQL → Settings → MCP (pick an indefinite grant for unattended n8n flows), then retry.',
+        });
+    }
+    if (text.includes('DUMP_REQUIRES_PAID_PLAN') ||
+        text.includes('Upgrade to Pro to create database backups from the API') ||
+        text.toLowerCase().includes('create dump requires a paid relatasql plan')) {
+        return new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'Create Dump requires a paid RelataSQL plan.', {
+            description: 'Your current RelataSQL plan does not include automated database dumps. Upgrade to Pro or Team, then retry this workflow.',
+        });
+    }
+    if (statusCode === 403 ||
+        text.toLowerCase().includes('forbidden - perhaps check your credentials')) {
+        return new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'RelataSQL rejected this dump request before the database export started.', {
+            description: 'Check that the selected RelataSQL connection is enabled for API access and that this API key belongs to the same workspace.',
+        });
+    }
+    if (text.includes('DUMP_PROCESS_FAILED') ||
+        statusCode === 500 ||
+        lower.includes('the service failed to process your request')) {
+        return new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'RelataSQL could not create the database dump.', {
+            description: 'Verify the selected connection in RelataSQL and try again. If the database is large, the export may have exceeded the dump time limit — raise DUMP_TIMEOUT_MS on the backend. If it keeps failing, contact RelataSQL support with the support reference and this n8n execution time.' +
+                detailHint +
+                refHint,
+        });
+    }
+    return new n8n_workflow_1.NodeOperationError(ctx.getNode(), (text.trim() || 'Create Dump failed') + detailHint + refHint);
+}
+/** Maps a columnar query result to row objects; never returns zero items. */
+function resultToItems(res) {
+    var _a, _b, _c, _d;
+    const rows = (0, GenericFunctions_1.rowsToObjects)((_a = res.columns) !== null && _a !== void 0 ? _a : [], (_b = res.rows) !== null && _b !== void 0 ? _b : []);
+    if (rows.length === 0) {
+        return [{ rowCount: (_c = res.rowCount) !== null && _c !== void 0 ? _c : 0, truncated: (_d = res.truncated) !== null && _d !== void 0 ? _d : false }];
+    }
+    if (res.truncated) {
+        rows[rows.length - 1] = { ...rows[rows.length - 1], _truncated: true };
+    }
+    return rows;
+}

package/dist/nodes/RelataSql/relatasql.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
+  <defs>
+    <linearGradient id="rs" x1="8" y1="6" x2="40" y2="42" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#6366F1"/>
+      <stop offset="1" stop-color="#3B82F6"/>
+    </linearGradient>
+  </defs>
+  <ellipse cx="24" cy="12" rx="14" ry="6" fill="url(#rs)"/>
+  <path d="M10 12v10c0 3.31 6.27 6 14 6s14-2.69 14-6V12" fill="url(#rs)" opacity="0.85"/>
+  <path d="M10 22v10c0 3.31 6.27 6 14 6s14-2.69 14-6V22" fill="url(#rs)" opacity="0.7"/>
+  <path d="M27 19l-7 9h5l-2 8 9-11h-6l3-6z" fill="#FFFFFF"/>
+</svg>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@relatalabs/n8n-nodes-relatasql",
+  "version": "0.1.7",
+  "description": "n8n community node for RelataSQL - run SQL, inspect schemas, and govern writes across your database connections using a RelataSQL API key.",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "relatasql",
+    "sql",
+    "postgres",
+    "database"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/RelataSQL/n8n-nodes-relatasql",
+  "author": {
+    "name": "RelataSQL"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RelataSQL/n8n-nodes-relatasql.git"
+  },
+  "engines": {
+    "node": ">=20.15"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc && gulp build:icons",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint nodes credentials package.json",
+    "lintfix": "eslint nodes credentials package.json --fix"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/RelataSqlApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/RelataSql/RelataSql.node.js"
+    ]
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-n8n-nodes-base": "^1.16.0",
+    "gulp": "^4.0.2",
+    "n8n-workflow": "*",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}