⚡ DB-Agent

Universal Database AI CLI — Ask in plain English, get database results instantly.
Author: Santhosh Gupta | 100% Free, Standalone, and works Offline (Ollama) or with Free Cloud AI (Gemini / Groq).

PyPI Version Python Version License: MIT

🚀 2-Minute Quickstart

Step 1: Install from PyPI

Open your terminal (PowerShell, Command Prompt, or Bash) and run:

pip install "dbagent-cli[all]"

Step 2: Run 1-Click AI Setup

db-agent setup

The interactive wizard gives you 3 options:

  1. Local Offline AI (Ollama): Automatically downloads and installs local Ollama and the qwen2.5-coder model. Zero API keys, 100% private, works offline.
  2. Free Cloud AI (Gemini / Groq): Enter your free API key for instant cloud processing.
  3. Normal Database CLI: Use standard database tools (connect, scan, raw SQL) without AI.

Step 3: Connect Your Database & Save an 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 Questions in Plain English!

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

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

📖 Complete Command Reference

Command How to Use When to Use
ask db-agent ask "show top 10 users" --db my_db Primary query tool. Translates English to SQL, executes automatically, and shows live results.
chat db-agent chat --db my_db Interactive terminal shell. Type questions, inspect tables, and switch models on the fly.
connect db-agent connect <url> --alias my_db Save connection. Validates credentials in < 0.1s and saves an alias name.
scan db-agent scan --db my_db --export db.md Schema catalog. Discovers tables, columns, relations, indexes, and exports to Markdown/JSON.
use db-agent use gemini Switch AI provider. Switch default AI between ollama, gemini, groq, and openrouter.
run db-agent run "SELECT * FROM users" --db my_db Direct SQL execution. Run raw SQL directly with formatted table output.
generate db-agent generate "ETL pipeline" --db my_db -o etl.py Code generation. Export SQL, Alembic migrations, Python ETL, or FastAPI REST APIs to files.
setup db-agent setup AI setup wizard. 1-click installer for local Ollama or cloud provider configuration.
config db-agent config Settings wizard. Configure API keys, default models, and database profiles.
profiles db-agent profiles Saved databases. List all configured database aliases and connection URLs.
models db-agent models Engine health check. Check Online/Offline status of local and cloud models.
guide db-agent guide In-terminal reference. Display interactive command cheatsheet.

💬 Interactive Chat Shell (db-agent chat)

Launch the interactive REPL with db-agent chat --db <alias>.

Inside the chat session, you can ask questions in plain English or use built-in : commands:

db-agent> list top 10 users with email and created_time from ivis_users
┌─────┬──────────────────────────┬─────────────────────────────┐
│ id  │ email                    │ created_time                │
├─────┼──────────────────────────┼─────────────────────────────┤
│ 101 │ john.doe@example.com     │ 2026-08-28 17:30:00+00:00   │
│ 102 │ jane.smith@example.com   │ 2026-08-28 17:15:00+00:00   │
└─────┴──────────────────────────┴─────────────────────────────┘

In-Chat Special Commands:

  • :help — Show all in-chat commands.
  • :tables — List all tables in the connected database.
  • :table <name> — Inspect table columns, primary keys, data types, and sample rows.
  • :fk <name> — View all mapped foreign keys and related tables (incoming and outgoing).
  • :provider <name> — Switch AI provider on the fly (ollama, gemini, groq, openrouter).
  • :model <name> — Switch active model name on the fly (e.g. :model gemini-3.6-flash).
  • :models — View active AI engine and available models.
  • :explain — View the SQL query and table matches generated for your last question.
  • :history — View the history of queries executed in this session.
  • :auto / :noauto — Toggle automatic execution of read queries.
  • :run — Re-execute the last generated SQL query.
  • :export <file> — Save the last generated SQL to a file.
  • :exit — Exit the chat session.

🔌 Supported Databases & Connection Examples

DB-Agent supports all major relational and NoSQL databases:

Database Connection URL Format
PostgreSQL postgresql://user:pass@localhost:5432/dbname
MySQL / MariaDB mysql+pymysql://user:pass@localhost:3306/dbname
SQLite sqlite:///path/to/database.db or just database.db
Microsoft SQL Server mssql+pyodbc://user:pass@server/dbname?driver=ODBC+Driver+17+for+SQL+Server
Oracle oracle+cx_oracle://user:pass@localhost:1521/?service_name=ORCLPDB1
DuckDB duckdb:///path/to/analytics.duckdb
MongoDB mongodb://user:pass@localhost:27017/dbname

🤖 Supported AI Providers (100% Free Options)

Provider Type API Key Needed? Speed Setup
Ollama Local & Offline No (Zero keys) Fast (Local GPU/CPU) db-agent setup
Google Gemini Cloud (Free Tier) Free key at aistudio.google.com Very Fast db-agent config
Groq Cloud (Free Tier) Free key at console.groq.com Ultra-Fast db-agent config
OpenRouter Cloud (Free Models) Free key at openrouter.ai Standard db-agent config

Switch Providers Anytime:

# Switch to Google Gemini
db-agent use gemini

# Switch to local Ollama (Offline)
db-agent use ollama

# Switch to Groq
db-agent use groq

🛡️ Safety & Auto-Execution Rules

  • Read Queries (SELECT, SHOW, EXPLAIN): Automatically executed for high productivity.
  • Write/DDL Queries (INSERT, UPDATE, DELETE, DROP, ALTER): DB-Agent detects destructive statements and prompts you for explicit confirmation before running. Pass --force to bypass confirmation if desired.

📄 License

MIT License © 2026 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.2.1.tar.gz (49.2 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.2.1-py3-none-any.whl (50.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: dbagent_cli-0.2.1.tar.gz
  • Upload date:
  • Size: 49.2 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.2.1.tar.gz
Algorithm Hash digest
SHA256 163276f7209c66d1bd7aa0ac3744c855bbdacb26cb253dc2f372ba3e67232e31
MD5 e453ee0b2dc0bd5008b614b230d4bec9
BLAKE2b-256 36d85aa763b233d333befaae100bd31085de6ebc82678487811c763d721925ec

See more details on using hashes here.

File details

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

File metadata

  • Download URL: dbagent_cli-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 50.9 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.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 63d1e8103b8108b251bd63ee3d0ac22e7a0d7197a28dc1430b12e7bf8f7918c0
MD5 09e9244e7161518798896f9d550ae053
BLAKE2b-256 146aa17a0ccf0d5d66c25e37aa915bdd07bebb0712799cfd69c418a01643359d

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

0.3.4

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

This release

0.2.1 This release

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