I recently released my first open-source project: shirube, named after the Japanese word 標べ, meaning a signpost or guide.
shirube is a local-first schema explorer for PostgreSQL that lets you read your database as a map. The latest beta also includes an AI navigator, so you can ask questions about your schema and see the relevant tables and relationships on the map.
This article is about why I built it, why database understanding still matters in the AI coding era, and what shirube can do today.
✍️ We Write Less SQL by Hand Now
ORMs, query builders, and AI coding tools have changed how we interact with databases.
In many applications, database access is no longer written directly as raw SQL. Tables are often hidden behind models, relationships behind methods, and more of that code can now be generated or edited by AI.
That is useful. I use these tools too.
But the schema underneath has not disappeared.
When an AI coding tool writes a data access layer, I still need to review what it is doing. Which tables does it read from? Which columns does it touch? Which relationships does it follow? Is the join path actually the one the application should use?
The same problem appears when asking AI for help. If I do not understand the rough shape of the database, it is hard to ask a good question, and even harder to judge whether the answer is right.
AI can help write the query, but it cannot remove our responsibility to understand the data model.
🧩 Table Lists Hide Relationships
Most database tools start with a list of tables.
That works well when I already know what I am looking for. If I need to open a specific table, inspect its columns, or preview a few rows, a table list is perfectly useful.
But when I am trying to understand how a database is connected, the list is not enough.
A table list shows me objects one by one. It does not naturally show what each table references, what references it, or which path leads to the data I need.
Relationships are the part I most need to follow, but they are also the easiest part to lose in a list.
That is why I wanted shirube to treat the database less like a catalogue, and more like a map.
🗺️ Reading the Database as a Map
When you connect shirube to a PostgreSQL database, it reads the schema and opens an interactive ER map.
The map shows tables, views, materialised views, columns, foreign keys, and view dependencies.
Instead of drawing every table at once, shirube starts from one table and its immediate neighbours. You can click a related table to recentre the map, then keep moving through the schema one hop at a time.
This is intentional. Large schemas can become unreadable if everything is shown at once. I wanted the map to feel less like a static diagram and more like a way to travel through the database.
When you select a table, shirube also shows its columns, primary keys, nullability, and relationships in both directions. If you need to check actual rows, you can open a read-only data preview with sorting, filtering, and paging.
The goal is not to replace a database client.
The goal is to make the structure of the database easier to see.
🤖 The AI Navigator
The latest beta adds the part I had wanted to build from the beginning: the AI navigator.
You can ask questions like:
- Where does a customer's email address live?
- How is a rental linked to a film?
- Which tables are involved in authentication?
- Why does this join go through
inventory?
shirube sends the relevant schema metadata to the model you configured, then shows the answer with concrete table and column names. When the answer mentions a table or view, you can jump to it on the map.
The important point is that the navigator is not a SQL generator.
It does not:
- run SQL
- modify your database
- inspect row values
It only uses schema metadata: table names, view names, column names, data types, primary keys, foreign keys, view dependencies, comments, and row-count estimates.
That makes the AI feel less like a black box producing a query, and more like a guide pointing at the parts of the schema worth checking.
🔒 Local-First and Read-Only by Design
Because shirube connects to real databases, I wanted the safety model to be conservative.
shirube runs on your machine and binds to 127.0.0.1. It is not a hosted service, and your database credentials are not stored on a shirube server.
Database connections are opened read-only, with a statement timeout. shirube does not include a query editor, and it has no feature for editing rows or changing schemas.
Saved passwords are stored in the OS keychain, not in a plain text config file.
For the AI navigator, you bring your own provider: Claude, OpenAI, an OpenAI-compatible endpoint, or a local model such as Ollama. Before schema metadata is sent to a remote provider, shirube asks for confirmation.
If you use a local model, the schema does not leave your machine.
The aim is simple: shirube should help me understand a database without adding unnecessary risk.
🚀 Trying shirube
shirube is currently in beta and supports PostgreSQL.
You can run it without installing it into your project:
pipx run shirube
# or
uvx shirube
This starts a small local server and opens shirube in your browser.
From there, you can add a PostgreSQL connection, inspect the schema, and start exploring the map.
If you do not have a PostgreSQL database ready, the repository includes a helper script for running the pagila sample database with Docker:
# Clone the repository
git clone https://github.com/shou-taro/shirube.git
cd shirube
# Start the pagila sample database with Docker
./scripts/dev-db.sh up
Then connect to:
postgresql://postgres:postgres@127.0.0.1:5432/pagila
🌱 What's Next
shirube is still a beta, and there is a lot I want to improve.
The current version focuses on PostgreSQL, the ER map, read-only data previews, and the AI navigator.
Next, I want to let users save their own map layouts, add custom relationship links, improve the navigator, and support more databases over time.
I also want to keep the core idea clear: shirube is not a tool for hiding the database from developers.
It is a tool for making the database easier to understand.
AI may change how much SQL we write by hand, but it does not remove the need to understand the data model underneath.
If you work with PostgreSQL and often need to understand how a schema is connected, I would love for you to try shirube and share your feedback.
shirube
You hand-write less SQL than ever.
You still own the schema.
標べ (shirube) — Japanese for a signpost. It reads your database as a map.
🚧 Status: Beta. Both the explorer and the AI navigator work today. shirube is pre-1.0, so things may still change — see the roadmap.
Ask a question — see the answer on the map.
🤖 Why shirube
You hand-write less SQL than you used to — tables become models and methods in your code and in the AI-coding era much of even that code is written for you. But the schema is still there underneath, and it is still yours to understand: to judge whether the code an AI wrote is right — which tables it reads, which columns it touches, which relationships it follows — and to ask the tools for the right thing in the first place.
A plain…
Top comments (0)