n8n-nodes-mysql-variables

English | Русский

A custom community node for n8n Community Edition that stores variables
(cookies, API keys, client id/secret and any other values) in MySQL or in
embedded SQLite (no separate database server — chosen in the credential).

Compared to existing solutions:

Storage: SQLite or MySQL

The Storage field in the credential switches the backend:

• SQLite (embedded) — the default. No database server, nothing to set up.
  Data lives in a file inside the n8n data folder; the file path is resolved
  automatically from the Username/Encryption Key (see "Isolation & sharing").
  Built on sql.js (WASM) — it compiles inside the n8n Docker image with no
  native build step. Great when colleagues don't have their own MySQL.
  Limitation: the store is local to that n8n instance (not shared over the
  network across multiple servers).
• MySQL — a central store, shared across multiple n8n instances, with the
  option to give each person their own MySQL login.

The logic (flat key→value, AES encryption, operations) is identical for both backends.

Keep the SQLite file on a mounted volume (~/.n8n), otherwise data won't
survive container recreation.

Features

• Operations: Get, Get All Keys, Set (upsert), Create, Update, Delete, Clear (empty a value).
• Flat key→value: one store = one SQLite file (or one MySQL table). Keys are unique within a store.
• Encryption at rest: values are AES-256-GCM encrypted before they are written; the database holds ciphertext.
• Value types: String and JSON.
• Usable as Tool: the node can be attached to n8n AI agents.

Isolation & sharing (SQLite)

The Encryption Key is the store's access secret, not just an encryption key.
The file path is derived from a hash of the Encryption Key (+ an optional
Username), so you cannot open or list someone else's store by knowing only
their Username — you need the exact key.

The path is resolved automatically. Priority:

1. Username set → n8n-vars-<username>-<hash(key)>.sqlite. Username is just a
   label (you can keep several stores under one key); access is governed by the key.
2. Username empty → n8n-vars-<hash(key)>.sqlite (one store per key).
3. Advanced → Custom File Path → an explicit path (for power users), overrides everything.

To share a store with a team:

• share the credential itself with colleagues (n8n credential sharing), or
• give them the same Username and Encryption Key.

⚠️ This protects access through the UI (guessing another user's Username
is useless without the key). File storage does not protect against someone with
disk access to ~/.n8n — for hard multi-user isolation use n8n credential
sharing and don't grant direct filesystem access. Values are encrypted with the
Encryption Key either way.

Table schema

Created automatically (Auto-create Table = on). SQL to create it manually (MySQL):

CREATE TABLE IF NOT EXISTS `n8n_variables` (
  `key`        VARCHAR(190) NOT NULL,
  `value`      LONGTEXT NULL,
  `type`       VARCHAR(20) NOT NULL DEFAULT 'string',
  `encrypted`  TINYINT(1) NOT NULL DEFAULT 1,
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

With MySQL, isolation is done via a separate table (Table Name) or a separate database per credential.

Install

Recommended — via the Community Nodes UI

Settings → Community nodes → Install a community node, then enter:

n8n-nodes-mysql-variables

Requires N8N_COMMUNITY_PACKAGES_ENABLED=true (default on self-hosted). To use
the node as a tool for AI agents, also set N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true.

Build from source

npm install
npm run build      # -> dist/

Manual install (Docker, self-hosted)

Option A — local custom folder (quick, no npm publish)

# 1. Build and pack
npm install && npm run build
npm pack            # -> n8n-nodes-mysql-variables-<version>.tgz

# 2. Install into the custom folder that is mounted into the container
mkdir -p ~/n8n-data/custom
cd ~/n8n-data/custom
npm init -y
npm install /full/path/n8n-nodes-mysql-variables-<version>.tgz   # pulls in mysql2

# 3. Start n8n with ~/n8n-data mounted at /home/node/.n8n
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom \
  -e N8N_COMMUNITY_PACKAGES_ENABLED=true \
  -v ~/n8n-data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

n8n picks up the node from ~/.n8n/custom automatically. After a restart it
appears in the palette as MySQL Variables.

Option B — custom Docker image (for production)

FROM docker.n8n.io/n8nio/n8n:latest
USER root
COPY . /opt/n8n-nodes-mysql-variables
RUN cd /opt/n8n-nodes-mysql-variables && npm install && npm run build \
 && mkdir -p /opt/custom && cd /opt/custom && npm init -y \
 && npm install /opt/n8n-nodes-mysql-variables
ENV N8N_CUSTOM_EXTENSIONS=/opt/custom
USER node

docker build -t n8n-with-vars .
docker run -it --rm -p 5678:5678 -v ~/n8n-data:/home/node/.n8n n8n-with-vars

docker-compose (example)

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
    volumes:
      - ./n8n-data:/home/node/.n8n

Credential setup

In n8n, create a MySQL Variables API credential:

Docker + MySQL: inside the n8n container localhost points to the container
itself. Use the MySQL container/service name (shared docker network) or
host.docker.internal for a database on the host machine. This is the cause of
the connect ECONNREFUSED ::1:3306 error.

Using it in expressions

// read a variable value from the MySQL Variables node
{{ $('MySQL Variables').item.json.value }}

Typical pattern: a MySQL Variables (Get) node at the start of the workflow →
the value is then used in HTTP Request / other nodes via the expression above.

Operations

License

MIT

🇷🇺 Русский (Russian)

English | Русский

Кастомная community-нода для n8n Community Edition, которая хранит переменные
(куки, API-ключи, client id/secret и любые другие значения) в MySQL или во
встроенной SQLite (без отдельного сервера БД — выбирается в credential).

В отличие от готовых решений:

Хранилище: SQLite или MySQL

Поле Storage в credential переключает бэкенд:

• SQLite (embedded) — по умолчанию. Никакого сервера БД, ничего настраивать не надо.
  Данные лежат в файле внутри папки данных n8n; путь к файлу подбирается автоматически
  по Username/ключу (см. «Изоляция и шеринг»). Реализовано на sql.js (WASM) — собирается
  в Docker-образе n8n без нативной компиляции. Подходит, когда у коллег нет своей MySQL.
  Ограничение: store локален для этого инстанса n8n (не шарится по сети между серверами).
• MySQL — централизованное хранилище, общее для нескольких инстансов n8n, с возможностью
  дать каждому свой MySQL-логин.

Логика (плоский key→value, AES-шифрование, операции) одинакова для обоих бэкендов.

SQLite-файл держи на смонтированном volume (~/.n8n), иначе данные не переживут пересоздание контейнера.

Возможности

• Операции: Get, Get All Keys, Set (upsert), Create, Update, Delete, Clear (обнулить значение).
• Плоский key→value: один store = один файл SQLite (или одна таблица MySQL). Ключ уникален в рамках store.
• Шифрование at rest: значения шифруются AES-256-GCM перед записью; в БД лежит шифротекст.
• Типы значений: String и JSON.
• Usable as Tool: ноду можно подключать к AI-агентам n8n.

Изоляция и шеринг (SQLite)

Encryption Key — это секрет доступа к стору, а не только ключ шифрования. Путь к файлу
выводится из хеша Encryption Key (+ опционального Username), поэтому открыть или просмотреть
чужой стор, зная только его Username, нельзя — нужен точный ключ.

Путь подбирается автоматически. Приоритет:

1. Username задан → n8n-vars-<username>-<хеш(ключ)>.sqlite. Username — просто метка
   (можно держать несколько сторов на один ключ); доступ решает ключ.
2. Username пуст → n8n-vars-<хеш(ключ)>.sqlite (один стор на ключ).
3. Advanced → Custom File Path → явный путь (для профи), перекрывает всё.

Расшарить store на команду:

• расшарить сам credential коллегам (Credential sharing в n8n), или
• сообщить им одинаковый Username и Encryption Key.

⚠️ Это защищает доступ через UI (подбор чужого Username без ключа бесполезен).
Файловое хранилище не защищает от того, у кого есть доступ к диску ~/.n8n — для жёсткой
многопользовательской изоляции используй credential sharing n8n и не давай прямой доступ к ФС.
Значения в любом случае зашифрованы Encryption Key.

Схема таблицы

Создаётся автоматически (Auto-create Table = on). SQL для ручного создания (MySQL):

CREATE TABLE IF NOT EXISTS `n8n_variables` (
  `key`        VARCHAR(190) NOT NULL,
  `value`      LONGTEXT NULL,
  `type`       VARCHAR(20) NOT NULL DEFAULT 'string',
  `encrypted`  TINYINT(1) NOT NULL DEFAULT 1,
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

При MySQL изоляция делается через отдельную таблицу (Table Name) или отдельную БД на credential.

Установка

Рекомендованный способ — через UI Community Nodes

Settings → Community nodes → Install a community node, затем впиши:

n8n-nodes-mysql-variables

Нужен N8N_COMMUNITY_PACKAGES_ENABLED=true (по умолчанию включён на self-hosted). Чтобы
использовать ноду как tool в AI-агентах, добавь ещё N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true.

Сборка из исходников

npm install
npm run build      # -> dist/

Ручная установка (Docker, self-hosted)

Вариант A — локальная папка custom (быстро, без публикации в npm):

# 1. Собрать и упаковать
npm install && npm run build
npm pack            # -> n8n-nodes-mysql-variables-<version>.tgz

# 2. Поставить в папку custom, которая монтируется в контейнер
mkdir -p ~/n8n-data/custom
cd ~/n8n-data/custom
npm init -y
npm install /full/path/n8n-nodes-mysql-variables-<version>.tgz   # подтянет mysql2

# 3. Запустить n8n, смонтировав ~/n8n-data в /home/node/.n8n
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom \
  -e N8N_COMMUNITY_PACKAGES_ENABLED=true \
  -v ~/n8n-data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

После рестарта нода появится в палитре как MySQL Variables.

Вариант B — свой Docker-образ (для прода):

FROM docker.n8n.io/n8nio/n8n:latest
USER root
COPY . /opt/n8n-nodes-mysql-variables
RUN cd /opt/n8n-nodes-mysql-variables && npm install && npm run build \
 && mkdir -p /opt/custom && cd /opt/custom && npm init -y \
 && npm install /opt/n8n-nodes-mysql-variables
ENV N8N_CUSTOM_EXTENSIONS=/opt/custom
USER node

Настройка credential

В n8n создай credential MySQL Variables API:

Docker + MySQL: localhost внутри контейнера n8n указывает на сам контейнер.
Используй имя сервиса/контейнера MySQL (общая docker-сеть) либо host.docker.internal
для базы на хост-машине. Это причина ошибки connect ECONNREFUSED ::1:3306.

Использование в выражениях

// получить значение переменной из ноды MySQL Variables
{{ $('MySQL Variables').item.json.value }}

Типичный паттерн: нода MySQL Variables (Get) в начале workflow → дальше значение
используется в HTTP Request / прочих нодах через выражение выше.

Операции

Лицензия

MIT