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 (Generation Counters): Ao executar comandos de mutação permitidos, o nó detecta automaticamente a tabela afetada e incrementa sua versão no Redis em $O(1)$, imune a race conditions.

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 Versionamento por Tabela: Chaves determinísticas compactas contendo o fingerprint de versão das tabelas (<prefix>:<schema>:<table>:<sha256>), eliminando race conditions de leituras atrasadas.
• Invalidação Atômica em Mutações: Operações de escrita (Insert, Update, Upsert, Delete e Execute Query com mutação) invalidam automaticamente o cache das tabelas afetadas via incremento atômico de versão (INCR), com retry automático e erro explícito em falha no Redis.
• 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

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

2. Nó Redgres Tiered Chat Memory

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

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