Metadata-Version: 2.4
Name: psql-chat
Version: 0.3.1
Summary: An AI-powered tool that can be called from inside psql to ask natural language questions about your PostgreSQL database with access to the database context and PostgreSQL documentation.
Author-email: Stefan Keller <stefan.keller@ost.ch>
Maintainer-email: Lars Herrmann <lars.herrmann@ost.ch>
License: PostgreSQL License (MIT-style)
Project-URL: Repository, https://gitlab.com/geometalab/psql-chat#
Keywords: sql,natural-language,postgresql,ai,llm,database,psql
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Dynamic: license-file

# psql-chat

psql-chat lets you ask your PostgreSQL database questions in natural language. The tool translates your request into SQL or `psql` shell commands, gives you a syntax-highlighted explanation, and can optionally execute the command after confirmation.

## Features

- **Natural language to SQL** – Converts plain-language prompts into PostgreSQL commands.
- **Database-aware** – Gathers schema context automatically (tables, columns, relationships) unless disabled with `--no-context`.
- **Documentation lookup** – Fetches relevant PostgreSQL docs on demand through Context7.
- **Safety first** – Warns when a query will modify data and asks for confirmation before executing.
- **Rich terminal output** – Uses Rich for colored, syntax-highlighted explanations.
- **Flexible usage** – Explain-only (default), execute with `--execute`, or skip docs with `--no-docs` for faster responses.

## Quick Start

```
uvx psql-chat "how do I list all users?"
uvx psql-chat --dsn "postgresql://user:pass@host:5432/db" "show top 10 customers"
uvx psql-chat "delete inactive users" --execute  # confirmation required
```

You can also call it from inside `psql`:

```
\! psql-chat "count orders by month"
\! psql-chat --no-docs "list tables"
```

## Requirements

- Python 3.11+
- A PostgreSQL connection (either via environment variables/`.pgpass` or `--dsn`)
- An OpenAI API key available as the `OPENAI_API_KEY` environment variable
- `uv` package manager (for `uvx`) or another way to install/run the package

## Installation

```
uv pip install psql-chat
```

On Windows the repository includes a `setup.ps1` helper script that installs dependencies and configures a shell alias so `psql-chat` is available in `psql`.

## Usage Options

```
psql-chat [OPTIONS] "your request"

Options:
  --dsn TEXT          PostgreSQL connection URI.
  --no-context        Skip schema discovery for faster responses.
  --no-docs           Skip fetching PostgreSQL documentation.
  -e, --execute       Execute the generated command after confirmation.
  --verbose           Show gathered schema context for debugging.
  --version           Show the program version and exit.
```

## License

This project is released under the PostgreSQL License (MIT-style).
