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.

The Agent YAML

Create a file called agent.yaml inside a sql-databases/ directory:

name: Database Analyst
description: Query a SQL database and summarize results in plain English
instructions: |
  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.
steps:
  - name: Explore Schema
    content: |
      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
  - name: Analyze Key Data
    content: |
      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
  - name: Report
    content: |
      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
connectors:
  - connection_name: My Database
    connection_type: postgresql

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

Windows

# Run the agent
oe-runtime-win.exe sql-databases/agent.yaml --config sql-databases/oe-config.json

macOS

# Make executable (first time only)
chmod +x oe-runtime-macos

# Run the agent
oe-runtime-macos sql-databases/agent.yaml --config sql-databases/oe-config.json

Linux

# Make executable (first time only)
chmod +x oe-runtime-linux

# Run the agent
oe-runtime-linux sql-databases/agent.yaml --config sql-databases/oe-config.json

Running as an API Server

Add --serve to start OE Runtime as an HTTP server on port 3333:

oe-runtime-win.exe --serve --config sql-databases/oe-config.json

Then send a request:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -d '{"yaml": "sql-databases/agent.yaml", "params": {}}'

Or import the Postman collection (download above) to test all endpoints visually.

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.