Metadata-Version: 2.4
Name: dbst
Version: 0.1.6
Summary: Lakehouse SQL tool — query runner, analyzer, and local web UI
Project-URL: Homepage, https://github.com/telmen87/dbst-sql-tool
Project-URL: Repository, https://github.com/telmen87/dbst-sql-tool
Project-URL: Issues, https://github.com/telmen87/dbst-sql-tool/issues
Author: telmen87
License: MIT
License-File: LICENSE
Keywords: cli,databricks,lakebase,postgres,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: databricks-sdk>=0.30.0
Requires-Dist: databricks-sql-connector>=2.9.0
Requires-Dist: fastapi>=0.110
Requires-Dist: jinja2>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pywinpty>=2.0; sys_platform == 'win32'
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.5
Requires-Dist: sqlglot>=20.0
Requires-Dist: tabulate>=0.9
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: agent
Requires-Dist: mcp<2.0.0,>=1.6.0; extra == 'agent'
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic>=0.25; extra == 'llm'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo.svg" width="72" height="72" alt="dbst logo">

  # dbst — Lakehouse SQL Tool

  Open-source CLI + local web UI for Databricks SQL warehouses.

  [![CI](https://github.com/telmen87/dbst-sql-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/telmen87/dbst-sql-tool/actions/workflows/ci.yml)
  [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
  [![License: MIT](https://img.shields.io/github/license/telmen87/dbst-sql-tool)](LICENSE)
</div>

## Features

- Run queries against a Databricks SQL warehouse
- Analyze queries for anti-patterns (SELECT *, cartesian joins, etc.), optionally with Claude AI suggestions (`--llm` flag)
- Local web UI: schema browser, query history, execution plan viewer
- Bring-your-own-CLI AI terminal in the web UI — spawns your own AI CLI (defaults to `claude` if on PATH) in a real terminal, with one-click "Optimize", "Fix with AI", and "Explain Plan with AI" buttons that hand it the query/error/plan and apply the result back into your tab
- MCP server (`dbst mcp`) so any MCP-aware AI CLI can browse your schema, run and analyze queries, and read/edit what's open in the web UI
- Multiple connection profiles

## Install

```bash
pip install dbst

# Claude-API-based --llm suggestions on `dbst analyze run`:
pip install 'dbst[llm]'

# MCP server (`dbst mcp`):
pip install 'dbst[agent]'
```

## Quickstart

```bash
# Add a profile (interactive prompts for host/token/etc.)
dbst profile add --name prod

# Run a query
dbst query run "SELECT * FROM my_table LIMIT 10" --profile prod

# Analyze a query
dbst analyze run "SELECT * FROM a JOIN b"

# Analyze with Claude AI suggestions (needs `pip install 'dbst[llm]'`)
dbst analyze run query.sql --llm

# Launch web UI
dbst ui --profile prod
```

## AI assistant

The web UI's AI panel (the ⌘ button) isn't a built-in chat — it spawns your
own AI CLI in a real terminal (`ai_terminal_command` in `config.yaml`, else
`claude` on PATH, else your shell). Three buttons send it a ready-made prompt
and apply the result back into your query tab:

- **Optimize** — reads the active query, its plan, and its lint findings; rewrites and reruns it.
- **Fix with AI** (appears on a failed query) — sends the exact error for a corrected rewrite.
- **Explain Plan with AI** — sends the raw execution plan for a plain-English breakdown.

## MCP server

```bash
pip install 'dbst[agent]'
dbst mcp install   # registers dbst in the current project's .mcp.json
```

Exposes 14 tools, 5 resources, and 3 prompts to any MCP-aware AI CLI:

- **Schema**: `list_profiles`, `list_catalogs`, `list_schemas`, `list_tables`, `describe_table`
- **Query**: `run_query`, `analyze_query`, `explain_query`, `get_query_metrics`, `get_warehouse_status`, `query_history`
- **Web UI** (needs `dbst ui` running): `get_active_tab`, `get_last_result`, `edit_active_tab`
- **Resources** (for clients that support browsing, e.g. Claude Desktop): `dbst://profiles`, `dbst://{profile}/catalogs`, `dbst://{profile}/{catalog}/schemas`, `dbst://{profile}/{catalog}/{schema}/{object_type}`, `dbst://{profile}/{catalog}/{schema}/{table}/columns`
- **Prompts**: `optimize_query(sql)`, `fix_query_error(sql, error)`, `explain_plan(plan_text)`

The last three tools read and write whatever's open in the web UI's active tab — that's what powers the Optimize/Fix/Explain buttons above, and works the same way if you just ask your AI CLI directly (e.g. "optimize the query open in my dbst tab").

## CLI Reference

```
dbst profile add|list|remove|test|default
dbst query run|history
dbst analyze run
dbst ui
dbst mcp [install]
```

## License

MIT
