Metadata-Version: 2.4
Name: shirube
Version: 0.1.0b3
Summary: Understand your database as a map — built for the AI-coding era.
Project-URL: Homepage, https://github.com/shou-taro/shirube
Project-URL: Repository, https://github.com/shou-taro/shirube
Project-URL: Changelog, https://github.com/shou-taro/shirube/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/shou-taro/shirube/issues
License-Expression: AGPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: keyring>=25.7.0
Requires-Dist: platformdirs>=4.2
Requires-Dist: psycopg[binary]>=3.3.4
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: structlog>=25.1.0
Requires-Dist: uvicorn[standard]>=0.51.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/logo.svg" width="88" alt="shirube" />
</p>

<h1 align="center">shirube</h1>

<p align="center">
  <strong>AI writes the SQL.<br />You still own the schema.</strong><br />
  <sub>標べ — a signpost for reading a database as a map.</sub>
</p>

<p align="center">
  <a href="https://github.com/shou-taro/shirube/actions/workflows/ci.yml"><img src="https://github.com/shou-taro/shirube/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://pypi.org/project/shirube/"><img src="https://img.shields.io/pypi/v/shirube" alt="PyPI" /></a>
  <img src="https://img.shields.io/badge/status-beta-a78bfa" alt="Status: beta" />
  <a href="https://github.com/shou-taro/shirube/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-AGPL--3.0-blue" alt="Licence: AGPL-3.0" /></a>
  <img src="https://img.shields.io/badge/PostgreSQL-ready-336791?logo=postgresql&logoColor=white" alt="PostgreSQL" />
</p>

> 🚧 **Status: Beta.** The explorer core is here and usable today. The AI navigator — the
> feature shirube is ultimately built around — is the next milestone. shirube is pre-1.0:
> things may still change.

<p align="center"><em>See the whole database as a map.</em></p>

<p align="center">
  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/home.png" alt="shirube exploring a database: an ER diagram with a table's detail and its rows" width="960" />
</p>

## 🤖 Why shirube

You write less SQL by hand than you used to — an AI writes much of it for you. But that
SQL still runs against **your** schema, and someone still has to understand that schema:
to prompt the AI well, to check what it gave back, to reason about where the data
actually lives. That understanding used to come for free while you wrote the queries
yourself. It doesn't any more.

shirube is where that understanding lives — and it's just as useful in the classic case,
dropping into a project with hundreds of undocumented tables and needing to find your
footing fast.

> AI changed how we write SQL. shirube changes how we understand databases.

## 🧭 What shirube does

shirube opens on an interactive ER diagram and lets you explore a database like a map:
search for a table, focus on it, and follow its relationships outward — so you can see
how everything connects without reading DDL or writing a single query.

It is **not** another SQL IDE or database administration console — there is no query
editor, and nothing that ever writes. shirube is a tool for *understanding* a database.

## ✨ Features

Everything below works today, in the beta:

- 🗺️ **ER diagram home** — auto-generated and centred on the most-connected table; see a
  table and its immediate neighbours, and travel outward one hop at a time.
- 📋 **Table detail** — columns with their types, primary keys and nullability, plus
  relationships split into *references* and *referenced by*.
- 🔗 **Relationship navigation** — click a related table to glide the map over to it.
- 👁️ **Data preview** — read a table or view's actual rows in a drawer, with click-to-sort
  columns, simple filters and paging.
- ⚡ **Instant search** — jump straight to any table or column.
- 🔐 **Saved connections** — passwords kept in your operating system's keychain, never in
  a config file.
- 🌗 **Light and dark themes.**

## 🛡️ Safe by design

- 🔒 **Read-only** — every connection is opened read-only with a statement timeout. shirube
  cannot modify your database — no writes, no schema changes, ever.
- 💻 **Local-first** — it runs on your machine and binds to `127.0.0.1` only. Your database
  credentials and data never leave your computer.
- 📝 **Metadata-only logging** — the local log records errors and request timings, but
  never the values in your data.

## 🚀 Getting started

You'll need a PostgreSQL database to point shirube at, and a way to run a Python
application without installing it permanently.

> The beta is tested on **macOS** and **Windows**. Linux support is planned.

```bash
pipx run shirube   # with pipx
# or
uvx shirube        # with uv
```

Either command starts a small local server and opens shirube in your browser. Add a
connection with your PostgreSQL details, and shirube inspects the schema and opens the ER
diagram.

> 💡 shirube connects with whatever credentials you give it. A read-only role with
> `CONNECT` and `SELECT` is all it needs — and all it should have.

## 📚 Learn more

- **Full README, roadmap and the AI-navigator preview** —
  <https://github.com/shou-taro/shirube>
- **Contributing** —
  <https://github.com/shou-taro/shirube/blob/main/CONTRIBUTING.md>
- **Licence** — [GNU AGPL-3.0](https://github.com/shou-taro/shirube/blob/main/LICENSE)
