How to Run an AI SQL Database Agent with OE Runtime

Query your PostgreSQL database in plain English. OE Runtime connects directly to your database, explores the schema, runs safe SELECT queries, and explains the results in plain language — no SQL knowledge required.

What You Need

• Node.js 18+ installed, or the OE Runtime binary from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• A PostgreSQL database with connection details (host, port, database name, user, password)
• A text editor — nothing else

Create the Project Folder

Create a folder called sql-databases/ and add these two files:

The Skill Files

Create SKILL.md inside a sql-databases/ directory. This is the portable skill — it follows the agentskills.io format and runs unchanged on Claude, Cursor, Windsurf, or OE Runtime:

---
name: sql-databases
description: Query a SQL database and summarize results in plain English
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are a database analyst with read access to a SQL database.
Run SELECT queries to explore the schema and answer data questions.
Always explain results clearly in plain English.
Do not run INSERT, UPDATE, DELETE, or DROP statements.
Complete all steps fully before writing your report.

## Step 1: Explore Schema
Run the following queries one at a time:
1. List all tables in the database
2. For each table, fetch the column names and data types
3. Count the rows in each table

## Step 2: Analyze Key Data
From the largest table found:
- Fetch the 5 most recently created rows (use created_at or id DESC if available)
- Calculate row counts grouped by any status or category column if one exists
- Identify any columns with NULL values and count how many rows are affected

## Step 3: Report
Produce a database summary in plain English:
- Tables found and their row counts
- Schema of the largest table (column names and types)
- Sample of 5 recent records
- Data quality observations (nulls, unexpected values)
- Suggested queries for further analysis

Create agent.yaml in the same directory to wire the skill to your connector:

name: Database Analyst
description: Query a SQL database and summarize results in plain English
connectors:
  - connection_name: My Database
    connection_type: postgresql
skills:
  - path: ./
    trigger_type: auto

The Config File

Create oe-config.json in the same directory:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "My Database",
      "connection_type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "mydb",
      "user": "postgres",
      "password": "YOUR_DB_PASSWORD"
    }
  ]
}

Replace host, database, user, and password with your PostgreSQL connection details. For cloud databases like Supabase, Neon, or RDS, use the provided connection string values. Always use a read-only database user when running analytical queries.

Download OE Runtime

Run the Agent

From the parent folder containing your skill directory:

1 npx recommended

npx -y @openenthrium/oe-runtime@latest ./sql-databases

2 Windows

oe-runtime-win.exe ./sql-databases

3 macOS

chmod +x oe-runtime-macos
./oe-runtime-macos ./sql-databases

First run blocked? System Settings → Privacy & Security → Allow Anyway.

4 Linux

chmod +x oe-runtime-linux
./oe-runtime-linux ./sql-databases

5 API Server integration

Add a "server" block to oe-config.json, then start with --serve:

{
  "llm": { ... },
  "server": { "enabled": true, "port": 3333, "apiKey": "your-secret-key" },
  "connectors": [ ... ]
}

npx -y @openenthrium/oe-runtime@latest --serve --config oe-config.json

Run with inline YAML:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"yaml": "...", "params": {}}'

Or run from a file on the server:

curl -X POST http://localhost:3333/run-file \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"file": "/path/to/agent.yaml", "params": {}}'

Use Cases

• Self-service analytics for non-technical teams — Let product managers, marketers, and operations staff query the database in plain English without writing SQL. The agent translates their questions into safe SELECT queries, runs them, and returns formatted results — democratising data access without compromising security.
• Database schema discovery — Automatically document the full schema of an unfamiliar database including table names, column types, and row counts. This is invaluable when inheriting a legacy system or joining a new team with an undocumented data model.
• Data quality auditing — Identify tables with NULL values, empty strings, or unexpected patterns across large datasets without writing complex queries manually. The agent surfaces data quality issues and quantifies how many rows are affected so your engineering team can prioritise fixes.
• Sales and revenue reporting — Query your CRM or e-commerce database to answer questions like "what was our revenue last month by product category" or "which customers haven't ordered in 90 days". The agent produces formatted reports from live data without requiring a dashboard or BI tool.
• Customer success and support analytics — Surface metrics like ticket volume by category, average resolution time, and open ticket counts directly from your support database. The agent can identify customers with multiple open tickets or long wait times who need immediate attention.
• Finance and accounting queries — Pull transaction summaries, invoice statuses, payment timings, and account balances from your financial database for reporting or reconciliation. The read-only restriction means finance teams can explore the data safely without risk of accidental modifications.
• Performance investigation — Query application databases during incident investigations to count error events, identify patterns in failed transactions, or trace specific user journeys through the data. The agent lets engineers ask investigative questions in plain language rather than writing ad hoc SQL under pressure.
• Compliance and audit preparation — Extract the specific data sets required for regulatory audits — user activity logs, consent records, data retention evidence — from your database with targeted queries. The agent produces structured outputs that can be shared directly with auditors.