⚡ 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.2.tar.gz (50.1 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.2-py3-none-any.whl (51.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: dbagent_cli-0.2.2.tar.gz
  • Upload date:
  • Size: 50.1 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.2.tar.gz
Algorithm Hash digest
SHA256 baf028fa7917e47acc4314b0d07dd148adda415a4fc028d25397405b686cd872
MD5 3ac800aabca393ce009e9e00b44f96b7
BLAKE2b-256 02bf3b585b2858fa1e324fce08a4b6616e25c06a37732274b209952fdca3004a

See more details on using hashes here.

File details

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

File metadata

  • Download URL: dbagent_cli-0.2.2-py3-none-any.whl
  • Upload date:
  • Size: 51.8 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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 dad649936aed8aa857cda703909d4e06a6bddc3ece717e31b7666b859fb8ee81
MD5 23624ff5b0a3979619b80f3c49f46172
BLAKE2b-256 96b589488e04141b25d1de27d016f2f90f368568a4b1b8b80696804b6f3ff69e

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

This release

0.2.2 This release

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