Database Agent

An interactive AI agent that answers natural-language questions about a database. It talks to your data through the Metabase API using tool calling, runs read-only SQL, streams its reasoning, and can render the results as charts in a side canvas. The LLM runs locally via Ollama (no API cost).

React (Vite)  ──►  Node/Express agent  ──►  Ollama (local LLM)
                          │
                          └──►  Metabase API  ──►  PostgreSQL (warehouse)

Prerequisites

• Docker + Docker Compose
• Node.js 20+ and npm
• Ollama running locally with a tool-calling model pulled, e.g.:

  ollama pull qwen3.5:9b

  Ollama typically runs as a service on http://localhost:11434. Verify with ollama list.

Running the project

1. Start the infrastructure (Docker Compose)

This brings up three containers: Metabase, its app database, and the data warehouse (PostgreSQL seeded with e-commerce dummy data).

docker compose up -d

Service	URL / Port	Purpose
metabase	http://localhost:3033	Metabase UI + API
data-db	localhost:5433	Warehouse the agent queries (e-commerce)
metabase-db	internal	Metabase's own metadata database

Give Metabase ~1 minute on first boot. The warehouse is auto-seeded from init-scripts/ on its first start.

2. Set up Metabase (one time)

1. Open http://localhost:3033 and create the admin account.

2. Connect the warehouse: Add a database → PostgreSQL, using:

   Field	Value
   Host	data-db
   Port	5432
   Database	datawarehouse
   Username	datauser
   Password	data_password

   Use host data-db / port 5432 (the container network), not localhost:5433.

3. Create an API key: Settings → Admin → Settings → Authentication → API Keys → Create API Key. Copy the key (starts with mb_).

3. Configure environment variables

Create a .env file in the project root:

METABASE_URL=http://localhost:3033
METABASE_API_KEY=mb_your_key_here
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=qwen3.5:9b
PORT=3001

4. Install dependencies and run

npm install
npm run dev

npm run dev runs both the agent server and the web client together:

• Agent server (Express) on http://localhost:3001
• Web client (Vite) on http://localhost:5173 — open this in your browser

The Vite dev server proxies /api/* to the agent server, so just use the client URL.

Using the app

1. The launchpad checks that Ollama and Metabase are reachable, then lets you pick a database.
2. Ask questions in natural language (e.g. "Show monthly revenue as a chart").
3. The agent discovers tables, runs SQL, streams its reasoning, and answers — rendering a chart in the side canvas when useful.
4. Chats are saved per database as sessions (sidebar): create, switch, and delete sessions; history survives reload.
5. Switch the model anytime from the header (any installed Ollama model, or type a custom name).

Stopping

# Stop containers, keep data
docker compose down

# Stop and wipe all data (including seeded warehouse + Metabase setup)
docker compose down -v

Stop the dev server with Ctrl+C.