n8n-nodes-redgres

Pacote de nós comunitários de alta performance para n8n que combina PostgreSQL / Supabase (persistência relacional durável) com Redis (L1 cache em microssegundos com TTL e invalidação atômica).

O pacote disponibiliza três nós complementares:

1. Redgres (redgres): Nó de banco de dados completo com as mesmas telas, operações (Select, Insert, Update, Upsert, Delete, Execute Query) e seletores dinâmicos (From List) do nó oficial do Postgres, com camada inteligente de cache em Redis e compatibilidade com AI Agents (usableAsTool: true).
2. Redgres Tool (redgresTool): Ferramenta nativa para AI Agents (NodeConnectionTypes.AiTool / usableAsTool: true) executarem queries SQL geradas pelo LLM ($fromAI()) com L1 Redis Cache, chaves SHA-256 e proteção opcional Somente Leitura (Read-Only Safe Mode).
3. Redgres Tiered Chat Memory (redgresChatMemory): Nó de memória conversacional em duas camadas para agentes de IA do n8n (NodeConnectionTypes.AiMemory).

Features

1. Nó Redgres Tool (Para AI Agents / LLMs)

• Integração Nativa com AI Agent: Projetado especificamente para conectar na porta Tools do AI Agent via usableAsTool: true.
• Preenchimento Dinâmico com $fromAI(): O campo SQL vem pré-configurado com a expressão {{ $fromAI('query', ...) }} para o LLM injetar a query calculada a partir da pergunta do usuário.
• Cache-Aside L1 Ultrarrápido (<2ms): Resultados de consultas SELECT são cacheados no Redis usando hash SHA-256 da consulta e parâmetros. O AI Agent obtém respostas imediatas sem onerar o banco de produção.
• Proteção Read-Only (Safe Mode): Opção para bloquear qualquer comando de escrita ou DDL (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE), prevenindo alucinações destrutivas do LLM.
• Invalidação Inteligente por Tabela: Ao executar comandos de mutação permitidos, o nó detecta a tabela afetada e limpa automaticamente seu conjunto de chaves no Redis via Tag Sets.

2. Nó Redgres (Postgres + Redis Cache Tradicional)

• Interface Nativamente Idêntica ao Postgres do n8n: Seletor visual de Schema e Tabela (From List), filtros com operadores (=, !=, LIKE, >, <, IS NULL), ordenação (Sort), limite (Limit) e colunas de retorno (Output Columns).
• Cache-Aside com Hash SHA-256: Chaves de tamanho compacto e seguro baseadas no hash da consulta e valores (<prefix>:<schema>:<table>:<sha256>), impedindo chaves gigantescas e eliminando colisões.
• Invalidação Atômica em Mutações: Operações de escrita (Insert, Update, Upsert, Delete) invalidam automaticamente o cache das tabelas afetadas via Tag Sets em $O(1)$ sem utilizar comandos pesados como KEYS *.
• Controles de Cache Transparentes: Parâmetros de TTL em segundos, prefixo customizado, bypass/forçar atualização e opção de injetar metadados de status de cache (_cached: true/false).
• Suporte a Tool: Também possui usableAsTool: true para fluxos de agente que preferem usar o nó completo com seletores de tabela.

3. Nó Redgres Tiered Chat Memory (AI Memory)

• Cache-Aside com Reaquecimento Automático: Consulta o Redis L1 em microssegundos; em caso de cache miss ou expiração, recupera do PostgreSQL L2 e reaquece o Redis transparentemente.
• Vínculo Automático de Turno / Execução (run_id): Gera e associa automaticamente um UUID único para cada rodada de conversa.
• Schema Dinâmico e Colunas Customizadas: Suporta campos relacionais (user_id, agent_id, tenant_id) e objetos JSONB (metadata).
• Janela de Contexto Deslizante: Mantém as últimas $k$ interações completas sem truncar perguntas e respostas para o modelo.
• Retenção Desacoplada no PostgreSQL: Permite manter um histórico durável e auditável de tamanho independente da janela do LLM (ex: $k=5$ para o agente e 100 interações salvas no banco).
• Pooling Seguro com SHA-256: Pools singleton compartilhados de pg.Pool e ioredis para evitar exaustão de conexões.

Tech Stack

| Camada | Tecnologia | |---|---| | Plataforma / Runtime | n8n Community Node (n8n-workflow, n8n-core) | | Framework de IA | LangChain (@langchain/core, langchain) | | L1 Cache | Redis (ioredis) | | L2 Relacional | PostgreSQL / Supabase (pg) | | Linguagem / Build | TypeScript (ES2022 / CommonJS), Gulp | | Testes | Jest (ts-jest) |

Como Funciona no n8n

Conectando ao AI Agent

Você pode conectar tanto a memória quanto as ferramentas do Redgres ao nó AI Agent:

flowchart LR
    Trigger["💬 Chat Trigger / Webhook"] --> Agent["🤖 AI Agent"]
    Model["🧠 Chat Model (OpenAI, Gemini, Anthropic)"] -->|Model| Agent
    Memory["⚡ Redgres Chat Memory"] -->|Memory| Agent
    Tool["🛠️ Redgres Tool"] -->|Tool| Agent

Configuração dos Nós

1. Nó Redgres Tool

| Campo | Padrão | Descrição | |---|---|---| | Tool Description | "Use this tool to execute SQL queries..." | Contexto repassado ao LLM para saber quando acionar a ferramenta. | | SQL Query | ={{ $fromAI('query', ...) }} | Expressão onde o LLM injeta a query a ser executada no PostgreSQL. | | Query Parameters | "" (vazio) | Parâmetros opcionais para placeholders $1, $2. | | TTL do Cache | 300 (5 minutos) | Tempo de vida no Redis para consultas SELECT. | | Somente Leitura (Read-Only) | false | Se ativado, rejeita comandos INSERT, UPDATE, DELETE, DROP, etc. | | Bypass Cache | false | Força consulta direta ao PostgreSQL sem usar cache. | | Incluir Metadados | false | Adiciona _cached: true/false e _cachedAt no JSON de retorno. |

2. Nó Redgres Tiered Chat Memory

| Campo | Obrigatório | Padrão | Descrição | |---|---|---|---| | Session ID / Conversa ID | ✅ | ={{ $json.sessionId || $json.conversa_id }} | Identificador único da sessão ou usuário. | | Agente | ✅ | "" (vazio) | Identificador do agente (ex: analista_dados). | | Janela de Contexto (k) | ❌ | 10 | Quantidade de interações recentes entregues ao modelo (0 para todo o histórico). | | Limitar Mensagens no PostgreSQL | ❌ | true | Se ativado, limita o histórico armazenado no PostgreSQL conforme a quantidade definida. | | Quantidade Salva no PostgreSQL | ❌ | 100 | Quantidade de interações (turnos) completas mantidas no PostgreSQL (desacoplado do $k$). | | Redis TTL (Segundos) | ❌ | 86400 (24h) | Tempo de vida das conversas no Redis. |

Quick Start

Pré-requisitos

• Node.js >= 20
• n8n >= 1.0.0
• Instância de PostgreSQL (ou Supabase) e Redis em execução

Instalação no n8n (Community Nodes)

Instale diretamente pela interface do n8n em Settings > Community Nodes > Install a community node:

n8n-nodes-redgres

Instalação Manual (Docker / Self-Hosted)

# 1. No diretório do projeto, compile o pacote:
npm install
npm run build
npm pack

# 2. No container ou servidor do n8n:
npm install --omit=peer /caminho/para/n8n-nodes-redgres-0.7.0.tgz

Após a instalação, reinicie o n8n para carregar os nós.

Credenciais no n8n

O nó utiliza as credenciais nativas do ecossistema n8n:

1. PostgreSQL Credential:
   • Host, Porta (5432 ou 6543 no Supabase Pooler), Database, Usuário e Senha.
   • Ative SSL e marque Allow Unauthorized Certs caso utilize provedores cloud como Supabase ou Neon.
2. Redis Credential:
   • Host, Porta (6379), Senha, Database (0) e configurações de TLS se aplicável.

Scripts Disponíveis

| Comando | Descrição | |---|---| | npm run build | Compila o código TypeScript e copia assets estáticos (.svg) via Gulp | | npm run dev | Inicia o compilador TypeScript em modo watch | | npm test | Executa a suite de testes unitários com Jest | | npm run deploy | Executa o script PowerShell de build e deploy no container n8n |

Arquitetura e Engenharia

Para uma documentação aprofundada sobre queries SQL executadas, diagramas de sequência, ciclo de vida e gerenciamento de pools, consulte o ARCHITECTURE.md.

License

MIT © Caio Santos