⚡ DB-Agent

Enterprise AI Database Copilot & Autonomous Data Agent (CLI)
Author: Santhosh Gupta | 100% Free, Standalone, Works Offline (Ollama) or with Cloud AI (Gemini / Groq / OpenRouter).

PyPI Version Python Version License: MIT

🌟 What is DB-Agent?

DB-Agent is a production-grade AI Database Agent and Copilot. It empowers developers, DBAs, data analysts, and non-technical users to inspect schemas, discover complex multi-hop table relationships, generate and optimize SQL, execute queries with enterprise safety guardrails, and visualize data directly in the terminal.

🚀 2-Minute Quickstart

Step 1: Install from PyPI

pip install "dbagent-cli[all]"

Step 2: 1-Click AI Setup

db-agent setup

Choose between:

  1. Local Offline AI (Ollama): Zero API keys, 100% private, runs entirely on your machine.
  2. Free Cloud AI (Gemini / Groq / OpenRouter): Ultra-fast cloud processing.
  3. Database Tools Only: Standard DB introspection and CLI tools without AI.

Step 3: Connect Database & Save Alias

db-agent connect postgresql://user:password@localhost:5432/mydb --alias my_db

(Supports PostgreSQL, MySQL, SQLite, SQL Server, Oracle, DuckDB, and MongoDB).

Step 4: Ask Plain English Questions or Launch Chat!

# 1. Ask a question and get instant live results table + ASCII charts
db-agent ask "list top 10 users" --db my_db

# 2. Or start the interactive AI copilot shell
db-agent chat --db my_db

🛡️ Key Enterprise Features

1. 🧠 Relationship Graph & Smart Multi-Hop JOINs

Automatically discovers multi-hop join paths between disconnected tables without guessing arbitrary joins.

# Find shortest relationship path between two tables:
db-agent path users events --db my_db

# Explain join cardinality (1:1, 1:N) and recommended join syntax:
db-agent explain-join customers orders --db my_db

2. ⚡ Persistent Schema Cache & Change Detection

Never runs expensive full database scans on every query. Local cache (~/.dbagent/cache/) detects schema diffs:

db-agent refresh-schema --db my_db
db-agent schema-status --db my_db

3. 🔒 Safety Modes & Production Protection

Five operational safety modes enforce strict boundaries before SQL execution:

  • SAFE: Only SELECT, SHOW, DESCRIBE, EXPLAIN, WITH allowed. All writes and DDL are strictly blocked.
  • READ_ONLY: Enforced on PRODUCTION environments with 5s timeouts and row caps.
  • CONFIRM: Reads auto-execute; write and DDL operations require interactive confirmation.
  • SANDBOX: Writes executed inside uncommitted transactions with before/after diff preview.
  • ADMIN: Full administrative access with audit tracking.

4. ⏪ Change Sets & Snapshot Rollback

Before executing modifying queries, DB-Agent captures a recovery snapshot and creates an auditable ChangeSet:

db-agent changes
db-agent changes-show CS-20260828-001
db-agent rollback CS-20260828-001 --db my_db

5. 🏥 Database Doctor & Query Optimizer

Run comprehensive health checks on connectivity, latency, unindexed foreign keys, and slow queries:

# Database health diagnostics:
db-agent doctor --db my_db

# EXPLAIN plan analysis & index recommendations:
db-agent optimize "SELECT * FROM events WHERE camera_id = 42" --db my_db

6. 📚 Business Semantic Dictionary & Query Templates

Teach DB-Agent your domain-specific metrics and definitions:

# Define a business metric:
db-agent define offline_camera "A camera with no heartbeat for > 2 minutes" --sql "last_heartbeat < NOW() - INTERVAL '2 mins'"

# List all definitions:
db-agent definitions

# Manage trusted SQL templates:
db-agent template list

7. 🎭 Sensitive Data Masking & RBAC

Automatically classifies columns into PII, Secrets, and Financial data, masking confidential values in outputs (s***@gmail.com, **********, ****-****-****-1234).

8. 📊 Automatic Visualization Detector

Detects when query results represent time series, category distributions, or single metrics, and renders ASCII/Unicode charts directly in your terminal.

📖 Complete CLI Command Reference

Command How to Use Purpose
ask db-agent ask "list top 10 users" --db my_db Natural language to SQL -> executes & renders table.
chat db-agent chat --db my_db Interactive terminal copilot with multi-turn context.
doctor db-agent doctor --db my_db Comprehensive database and AI health diagnostic check.
path db-agent path users events --db my_db Shortest multi-hop foreign key join path discovery.
explain-join db-agent explain-join customers orders Explains join relationship, cardinality, and syntax.
optimize db-agent optimize "<SQL>" --db my_db Analyzes EXPLAIN plan and recommends indexes.
scan db-agent scan --db my_db --export db.md Full database schema introspection & Markdown export.
refresh-schema db-agent refresh-schema --db my_db Refreshes schema cache and reports detected diffs.
schema-status db-agent schema-status --db my_db Displays schema cache age, version, and health.
changes db-agent changes Lists recorded write ChangeSets.
changes-show db-agent changes-show CS-20260828-001 Shows before/after snapshot of a ChangeSet.
rollback db-agent rollback CS-20260828-001 Generates and executes inverse rollback SQL.
define db-agent define revenue "SUM(order.amount)" Saves a business definition into the semantic layer.
definitions db-agent definitions Lists all defined business terminology.
template db-agent template list Manages reusable, parameterized query templates.
audit db-agent audit Displays recent query execution audit log.
connect db-agent connect <url> --alias my_db Tests connection and saves profile alias.
use db-agent use gemini Switches default AI provider.
run db-agent run "SELECT * FROM users" --db my_db Executes raw SQL query with Rich table output.
generate db-agent generate "ETL script" --db my_db -o etl.py Generates Python ETL, Alembic migrations, or APIs.
setup db-agent setup 1-Click setup wizard for local or cloud AI.
config db-agent config Interactive AI API keys and preferences wizard.
profiles db-agent profiles Lists all saved database connection profiles.
models db-agent models Status of local Ollama models and cloud AI providers.
guide db-agent guide Displays full interactive command cheatsheet.

💬 In-Chat REPL Commands (db-agent chat)

Inside the interactive chat shell, you can use built-in colon commands:

  • :doctor — Run database health diagnostics.
  • :path <t1> <t2> — Discover shortest join path between tables.
  • :join <t1> <t2> — Explain join cardinality and recommended join syntax.
  • :mode <SAFE|CONFIRM|SANDBOX|ADMIN> — Switch safety mode mid-session.
  • :changes — List recent write ChangeSets.
  • :tables — List all database tables.
  • :table <name> — Inspect columns, types, primary keys, and sample data.
  • :fk <name> — View incoming and outgoing foreign keys.
  • :provider <name> — Switch AI provider (ollama, gemini, groq, openrouter).
  • :model <name> — Switch active model name on the fly.
  • :explain — Show generated SQL and query analysis for the last turn.
  • :history — View query history for the session.
  • :auto / :noauto — Toggle automatic execution of read queries.
  • :run — Re-execute the last generated SQL query.
  • :clear — Clear multi-turn conversational context.
  • :export <file> — Save the last generated SQL to a file.
  • :exit — Exit chat session.

📄 License

MIT License. Built with ❤️ by Santhosh Gupta.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.11.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for santhoshgupta from gravatar.com santhoshgupta

Credits

Author: Santhosh Gupta

Requires

Python >=3.9

Provides Extra

all dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dbagent_cli-0.3.4.tar.gz (94.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

dbagent_cli-0.3.4-py3-none-any.whl (99.1 kB view details)

Uploaded Python 3

File details

Details for the file dbagent_cli-0.3.4.tar.gz.

File metadata

  • Download URL: dbagent_cli-0.3.4.tar.gz
  • Upload date:
  • Size: 94.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.11.0

File hashes

Hashes for dbagent_cli-0.3.4.tar.gz
Algorithm Hash digest
SHA256 c1bd23dd532603d7c13e54529639df4f48f1d4b545e64faff353a9496ccf15b7
MD5 efcc653f16d074d4636b24921bb76334
BLAKE2b-256 aa8cfe971578779ce7462d5ccb97188ebf14166bec2a27c1533f3eebf9d605e3

See more details on using hashes here.

File details

Details for the file dbagent_cli-0.3.4-py3-none-any.whl.

File metadata

  • Download URL: dbagent_cli-0.3.4-py3-none-any.whl
  • Upload date:
  • Size: 99.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.11.0

File hashes

Hashes for dbagent_cli-0.3.4-py3-none-any.whl
Algorithm Hash digest
SHA256 6088c30900b750b43f082f9959ac6d68d89df54cd71ade8e4a2eed971a30e17b
MD5 4a2f3f776c0b5efd5f5ccca4f956e5da
BLAKE2b-256 5a9b2b710307089cb20ceb097fd52e386ac95de124436f44ce36d027bcbb3f2f

See more details on using hashes here.

Release history Release notifications | RSS feed

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.9

2 files

0.8.8

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

This release

0.3.4 This release

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page