n8n Data Analyst Agent

A production-ready n8n workflow template that turns any Supabase / Postgres database into a natural-language analytics chatbot. Users ask questions in plain English — the agent writes SQL, runs it safely, and returns answers with charts.

Built as a Tools Agent using LangChain, OpenRouter (Claude Sonnet 4.6 by default), QuickChart for visualizations, and Postgres Chat Memory for persistent conversations.

Part of the n8n-ai-agents catalog — see the catalog for shared architecture principles, security framework, and output conventions every template in the collection follows.

What it does

• Chat interface — hosted n8n chat URL or embeddable widget
• Schema discovery — introspects your database so the agent never hallucinates tables/columns
• Safe SQL execution — read-only queries with an automatic 200-row cap and a truncation flag
• Automatic chart generation — bar / line / pie / doughnut / scatter, rendered via QuickChart.io
• Business-term search — fuzzy search over a human-curated schema_docs table so users can ask about "churn" or "MRR" without knowing the column name
• Persistent memory — follow-up questions work across turns; conversations survive browser refreshes
• Google Sheets export — on explicit user request
• Scheduled briefings — companion workflow runs KPI queries on cron and sends digests
• Extensible scratchpad (think tool) — the agent writes down its plan before complex queries

Architecture

┌─────────────────┐      ┌──────────────────────┐
│  Chat Trigger   │─────▶│  Tools Agent (LC)    │
│  (hosted chat)  │      │  Claude Sonnet 4.6   │
└─────────────────┘      └──┬───────────────────┘
                            │
         ┌──────────────────┼──────────────────────────────┐
         │                  │                              │
         ▼                  ▼                              ▼
  ┌────────────┐     ┌──────────────┐              ┌──────────────┐
  │ Postgres   │     │ 7 Tools      │              │  Memory      │
  │ Chat       │     ├──────────────┤              │  (Postgres)  │
  │ Memory     │     │ list_schema  │              └──────────────┘
  └────────────┘     │ get_table_   │
                     │  definition  │
                     │ run_sql      │─┐     ┌────────────────────┐
                     │ create_chart │─┼────▶│ [Sub] Row-capped   │
                     │ search_docs  │─┤     │ SQL execution      │
                     │ think        │ │     └────────────────────┘
                     │ export_sheets│ │     ┌────────────────────┐
                     └──────────────┘ ├────▶│ [Sub] QuickChart   │
                                      │     │ chart rendering    │
                                      │     └────────────────────┘
                                      │     ┌────────────────────┐
                                      └────▶│ [Sub] Schema docs  │
                                            │ fuzzy search       │
                                            └────────────────────┘

See docs/ARCHITECTURE.md for a deep dive.

Requirements

• n8n ≥ 1.78 (self-hosted or cloud) with access to the LangChain community nodes (included by default)
• Supabase project (free tier works) or any Postgres 14+ instance
• OpenRouter account with credit — get an API key
• Optional: Google account for Sheets export

Quickstart

1. Clone

git clone https://github.com/MinaSaad1/n8n-supabase-data-analyst-agent.git
cd n8n-supabase-data-analyst-agent

2. Prepare your database

Open your Supabase project's SQL Editor and paste:

• sql/01-setup.sql — creates the n8n_readonly role, pg_trgm extension, schema_docs table, and n8n_chat_histories table
• sql/02-demo-data.sql — (optional) seeds a demo_orders table with ~1,200 rows for testing

3. Import the workflows into n8n

In n8n → Workflows → Import from File, in order:

1. workflows/02-sub-run-sql-capped.json
2. workflows/03-sub-generate-chart.json
3. workflows/04-sub-search-schema-docs.json
4. workflows/01-main-agent.json
5. workflows/05-briefing-morning.json — (optional)

After importing the main agent, open each run_sql, create_chart, and search_schema_docs tool node and re-bind it to the matching sub-workflow (the workflow IDs differ per instance).

4. Create credentials

Create these n8n credentials and attach them to the nodes listed:

5. Activate & test

1. Activate all 3 sub-workflows AND the main agent.
2. Open the main agent → click Chat.
3. Ask: "Using demo_orders, show revenue by product category as a bar chart."

Expected flow: get_table_definition → run_sql → create_chart → formatted response with chart image, markdown table, SQL, and insight bullets.

See docs/DEMO_SCRIPT.md for a 12-prompt demo flow.

Configuration

Swap the LLM

Open the main agent → OpenRouter Chat Model node → change the model field. Any tool-calling-capable model on OpenRouter works. Tested with anthropic/claude-sonnet-4.6; try anthropic/claude-sonnet-4.5, openai/gpt-4o, or google/gemini-2.5-pro for alternatives.

Adjust the system prompt

The full behavior (strict markdown tables, mandatory charts, SQL safety, retry rules) lives in the Data Analyst Agent node's systemMessage option. Edit in the n8n UI.

Populate schema docs

To make the agent smarter about your business terminology, insert rows into public.schema_docs:

INSERT INTO public.schema_docs (table_name, column_name, business_description, sample_values) VALUES
  ('demo_orders', 'total_amount', 'Final order value in USD after discount and shipping. Use for revenue/GMV.', '49.50, 1820.00');

Sample seed for the demo table is in sql/01-setup.sql.

Demo data

The repo ships with sql/02-demo-data.sql which seeds a demo_orders table:

• 1,200 orders over 365 days
• 6 product categories, 8 countries (MENA-weighted), 3 channels, 4 payment methods
• Customer segments (New/Returning/VIP — VIPs spend ~40% more)
• Realistic refund rate (~6%) and discount distribution

Perfect for video demos and smoke testing.

Troubleshooting

• "Agent stopped due to max iterations" — Your Postgres Chat Memory has anchored on a broken tool-call pattern. Click the ↺ refresh icon in the chat panel for a new session.
• "Node does not have any credentials set" — You imported the JSON but forgot to bind a credential on one of the sub-workflow nodes. Open the sub-workflow and attach the Postgres credential.
• QuickChart returns a weird image — The agent's chart fields were malformed. Open the last execution of [Sub] Generate Chart from Data and inspect the input.
• Supabase SSL error — Enable "Ignore SSL Issues (Insecure)" in the Postgres credential. Safe for Supabase's pooler cert.
• IPv6 timeout — Supabase's direct host (db.<ref>.supabase.co) is IPv6-only. Switch to the Session Pooler host.

Security

This template is not production-ready for untrusted users as-is. The agent has prompt-only SQL safety, no RLS enforcement, and a public chat URL.

See docs/SECURITY.md for a layered hardening guide covering:

• Authentication on the chat trigger
• Supabase RLS + JWT pass-through
• Read-only Postgres role with statement timeouts
• PII masking via views
• Regex guard + audit logging
• Rate limiting + output filtering

Roadmap

• Built-in RLS / multi-tenancy support via JWT metadata
• Optional pgvector-based semantic schema search
• Streaming tool-call events to the chat UI
• Slack/Teams delivery nodes for the briefing workflow
• One-click Supabase migration for the setup SQL
• Evaluator/critic step for hallucination detection

License

MIT — see LICENSE.

Credits

Built by Mina Saad. Pull requests welcome.

Need this running in your business?

This template is free and MIT, and it is meant to be forked. Getting one into
production against your real data, your credentials and your edge cases is a
different job, and it is the one I do.

I work out what is actually costing a business, then build whatever fixes it: an
AI agent, an automation, or a full application. Handed over so your team owns it.

Book a call · mina-saad.com