sqldbagent 0.1.2

Service-first database intelligence platform for safe inspection and agent-ready exports

sqldbagent

Safe database intelligence for agents, operators, and automation.

sqldbagent is a service-first platform for understanding relational databases through normalized metadata, durable artifacts, guarded querying, and agent-ready surfaces. It starts with Postgres and MSSQL, uses SQLite as a lightweight smoke/E2E target, and keeps the shared service layer authoritative across every interface.

Why This Exists

Most database tooling gives you one of two extremes:

• a thin SQL shell with no meaningful safety boundary
• a one-off schema export with no reusable runtime context

sqldbagent is trying to sit in the middle:

• inspect and normalize database structure once
• store snapshots, profiles, docs, diagrams, prompts, and retrieval indexes durably
• let CLI workflows, dashboards, MCP tools, and LangGraph agents reuse that context
• keep all agent-facing SQL behind an explicit read-only safety layer

Core Shape

The architecture rule is:

Normalized Metadata Core In The Middle, Dialect Enrichers On The Edges

That means:

• shared models for databases, schemas, tables, views, columns, relationships, profiles, and snapshots
• Postgres and MSSQL adapters for dialect-specific introspection and execution details
• thin surfaces on top: CLI, dashboard, MCP, LangChain, and LangGraph

Current Capabilities

• datasource config and engine factories through Pydantic Settings and .env
• normalized inspection of servers, schemas, tables, and views
• profiling with row counts, distinct/null stats, samples, storage hints, and entity heuristics
• guarded sync and async SQL execution
• snapshot persistence with per-datasource and per-schema storage
• snapshot diffing, docs export, Mermaid ER export, and prompt export
• prompt-enhancement artifacts that merge DB-aware guidance with saved user context
• Qdrant-backed retrieval over stored snapshot documents
• LangChain tools and LangGraph agent builders with middleware, checkpointing, and optional LangSmith tracing
• FastMCP server surface
• Streamlit dashboard chat surface with chat, schema diagram, prompt review, and saved-thread reuse over the same persisted agent stack

Install

With PDM:

pdm install -G :all

With pip:

pip install "sqldbagent[cli,postgres,langchain,langgraph,mcp,dashboard,docs,test]"

Local Demo

Bring up the local integration stack and migrate the demo database:

make up
make demo-migrate

Run the common workflow:

pdm run sqldbagent inspect tables postgres_demo --schema public
pdm run sqldbagent snapshot create postgres_demo public
pdm run sqldbagent prompt export postgres_demo public
make langgraph-dev-demo
make dashboard-demo

The dashboard includes:

• a persisted chat tab over the guarded agent stack
• snapshot-aware example questions to help start a useful conversation quickly
• a schema tab that renders the latest stored Mermaid ER diagram
• a prompt tab for reviewing the base/effective prompt, saving prompt context, and regenerating DB-aware prompt guidance
• a threads tab plus sidebar selector for reopening saved conversations

Agent Stack

sqldbagent uses LangChain v1's create_agent(...) surface on top of LangGraph runtime primitives.

• state is seeded from stored snapshots
• middleware owns prompt injection, stored prompt-enhancement merging, tool handling, summarization, HITL, and limits
• Postgres checkpointing is the durable thread path
• the dashboard uses a session-scoped memory saver when Postgres checkpointing is not enabled
• LangSmith tracing is optional and .env-driven

langgraph.json points at the local project root and .env, so langgraph dev uses the same package and tracing configuration as the rest of the repo.

Useful LangGraph make targets:

• make langgraph-dev for the local API server with repo defaults
• make langgraph-dev-demo to run the API server against postgres_demo
• make langgraph-debug to wait for a debugger client before startup
• make langgraph-up for the Dockerized LangGraph API server
• make langgraph-build to build the LangGraph API image
• make langgraph-test for the runtime and checkpoint integration tests

Documentation

Public docs live at sqldbagent.readthedocs.io, internal repo memory lives in docs/_internal, and the main contributor rules live in AGENTS.md.

Useful entrypoints:

• Getting Started
• Configuration
• Agent Stack
• Publishing

Build docs locally:

make docs
make docs-live

Development

trunk check --fix
make test
make test-integration
make test-e2e

Publishing

make build
make publish-check
make publish-testpypi
make publish-pypi

The repo also includes GitHub Actions workflows for CI, docs builds, and trusted-publisher PyPI releases on version tags.