⚡ DB-Agent (dbagent-cli)

The Privacy-First AI Database Copilot, Schema Graph Introspector & Post-Commit Recovery Engine
Author: Santhosh Gupta | 100% Free, Standalone, Works 100% Offline (Ollama) or with Cloud AI (Claude 3.7 / GPT-4o / DeepSeek / Gemini / Groq).

🌟 What is DB-Agent?

DB-Agent is an enterprise-ready, privacy-first database AI copilot that translates plain English into dialect-precise SQL, explores schemas on-demand (<30ms), enforces strict multi-tier safety guardrails, and captures pre-write snapshots allowing you to safely rollback database modifications days or weeks after COMMIT.

"Show me the top 10 customers by order value"
                      ↓
           [ DB-Agent CLI Engine ]
   (Targeted Schema Sub-Graph + AST Safety)
                      ↓
  SELECT c.customer_id, c.first_name, SUM(o.total_amount) AS total_spend
  FROM customers c
  JOIN orders o ON c.customer_id = o.customer_id
  GROUP BY c.customer_id, c.first_name
  ORDER BY total_spend DESC LIMIT 10;
                      ↓
            ⚡ Executed in 0.4s
  ┌─────────────┬────────────┬─────────────┐
  │ customer_id │ first_name │ total_spend │
  ├─────────────┼────────────┼─────────────┤
  │ 1           │ Alice      │ $3,450.00   │
  │ 3           │ Claire     │ $2,198.50   │
  └─────────────┴────────────┴─────────────┘

🚀 5-Second Instant Trial (Zero Setup Required)

Want to test DB-Agent without configuring a database or API keys?

# 1. Install DB-Agent
pip install "dbagent-cli[all]"

# 2. Launch built-in demo e-commerce database with interactive AI copilot
db-agent demo

⚡ 3-Minute Quickstart

1. Install

pip install --upgrade "dbagent-cli[all]"

2. Configure AI Backend (1-Click Setup)

db-agent setup

Choose from 8 built-in providers:

• Local Ollama (100% private, 100% offline with qwen2.5-coder, llama3.3, deepseek-r1)
• Google Gemini (gemini-3.6-flash, gemini-2.5-flash)
• Anthropic Claude (claude-3-7-sonnet-20250219, claude-3-5-sonnet)
• OpenAI ChatGPT (gpt-4o, gpt-4.5-preview, o3-mini)
• DeepSeek AI (deepseek-chat V3, deepseek-reasoner R1)
• Mistral AI (codestral-latest, mistral-large-latest)
• Groq (llama-3.3-70b-versatile)
• OpenRouter (meta-llama/llama-3.3-70b-instruct)

3. Connect Your Database

# Interactive guided connection
db-agent connect

# Or connect directly with an alias
db-agent connect postgresql://user:password@localhost:5432/app_db --alias prod_db

4. Ask Plain English Questions

# One-off query:
db-agent ask "count active users grouped by country" --db prod_db

# CI/CD machine-readable JSON export:
db-agent ask "count orders by status" --db prod_db --format json

# Interactive Claude-Style Shell with live streaming & prompt queuing:
db-agent chat --db prod_db

📊 Database Compatibility Matrix

🪟 Interactive Viewing & Data Grid Suite

When querying wide enterprise tables with 20 to 60+ columns, DB-Agent provides 5 flexible viewing tools:

🛡️ 5 Operational Safety Tiers

⏪ Long-Term Post-Commit Recovery Engine

Unlike standard database transactions that only protect uncommitted sessions, DB-Agent captures pre-write row snapshots before modifying data:

User: "Update inactive customers to ACTIVE where created_at > '2025-01-01'"
AI:   Modifying 42 rows. Capturing pre-write snapshot...
      ✓ Change committed successfully (Change ID: CS-20260831-001)

... 10 days later ...

User: db-agent rollback CS-20260831-001 --db my_db
AI:   Checking concurrency conflicts... No conflicting writes detected.
      ✓ Restored 42 rows to their exact original state.

⚡ Performance Benchmarks (db-agent benchmark)

Reproducible benchmark metrics measured on standard hardware:

Benchmark Category                   Latency / Metric        Rating
─────────────────────────────────────────────────────────────────────────────
Cold Schema Scan (6 tables)          12.4 ms                 ⚡ Ultra Fast (<50ms)
Cached Schema Load                   0.08 ms                 ⚡ Sub-Millisecond
Schema Cache Speedup                 155x faster             🚀 Verified
BFS Multi-Hop Join Routing (3 hops)  0.15 ms                 ⚡ Sub-Millisecond
Query Result Cache Hit               0.02 ms                 ⚡ Instant
Process Memory Footprint             28.4 MB                 🟢 Lightweight

Run benchmarks locally:

db-agent benchmark

🔌 Plugin & Extensibility Architecture

Extend DB-Agent with custom database connectors or AI providers via standard Python entry points:

# my_connector.py
from dbagent.connectors.base import BaseConnector

class ClickHouseConnector(BaseConnector):
    # Implement test_connection, inspect_schema, execute_query
    pass

In your package pyproject.toml:

[project.entry-points."dbagent.connectors"]
clickhouse = "my_package:ClickHouseConnector"

📖 CLI Command Reference

🔒 Privacy & Security First

• Zero Credentials Sent to AI: DB hostnames, usernames, passwords, and data rows never leave your machine. Only schema DDL is sent to the LLM.
• 100% Offline with Ollama: Run completely air-gapped with local LLMs.
• Sensitive Data Masking: Automatic regex masking of emails (a***@b.com), passwords (**********), and cards.
• Append-Only Audit Logs: Records all queries and execution durations in ~/.dbagent/audit.jsonl.

📄 License & Community

• License: MIT License
• Author: Santhosh Gupta
• Documentation & Recipes: examples/
• Contributing: CONTRIBUTING.md
• Security Policy: SECURITY.md
• Privacy Policy: PRIVACY.md