HIPAA rules. They’re a nightmare. Especially for developers.
Especially when your database decides to go rogue at 3 AM. You’ve got query plans. Sensitive data. And a strict no-cloud policy. So what do you do? You comb through JSON by hand. Like it’s 2015.
Until now. Enter Plansmith. It’s a local Postgres triage co-pilot. Built for one reason: HIPAA compliance. It won’t send your sensitive plans anywhere. Not to ChatGPT. Not to Claude. Not even to the cloud.
This isn’t some pie-in-the-sky PR stunt. This is born from necessity. A staff DBA at a major healthcare company needed this. Badly.
Why Local Matters
Frontier LLMs are great. For most things. But not when patient data is involved. HIPAA is a hard line. Query plans, table names, filter literals – none of that leaves the premises. Air-gapped servers are the norm. Standard practice. Sending that data out? A non-starter.
Plansmith circumvents this. It runs the entire pipeline locally. Model included. The only network call? To 127.0.0.1:11434. That’s Ollama on the same laptop.
The whole pipeline runs locally, including the model. The only outbound network call Plansmith makes is to
127.0.0.1:11434, which is Ollama on the same laptop.
And it’s not asking the LLM to do the grunt work. That’s the genius. A deterministic Python script first. It walks the EXPLAIN (ANALYZE, FORMAT JSON) trees. It extracts a structured diff. Scan methods flipping. Row estimate errors. Sort spills. Hash spills. All the nasty details. Only that compact, measured data goes to the LLM.
Gemma 4’s job? The part it’s actually good at. Explaining things. In plain English. And crafting a ranked runbook. Based on real evidence. Not guesswork.
A CLI That Actually Works
Forget clunky interfaces. This has a CLI. You feed it two EXPLAIN outputs. A baseline. An incident plan. And the query itself. Plansmith spits out a triage report. It’s immediate. And actionable.
Consider this gem from a sample run:
╭─────────────────── Plansmith ───────────────────╮
│ baseline 15ms · incident 7421ms · 497.7× slower │
╰─────────────────────────────────────────────────╯
Structured diff findings
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Severity ┃ Kind ┃ Summary ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ CRITICAL │ runtime_regression │ Execution time grew 497.7× │
│ CRITICAL │ scan_method_flip │ orders: Index Scan → Seq Scan │
│ CRITICAL │ row_estimate_miss │ Seq Scan on orders off by 124158× │
│ CRITICAL │ nested_loop_blowup │ Nested Loop with 248,317 outer │
└──────────┴────────────────────┴───────────────────────────────────┘
Then the LLM kicks in. It delivers a triage report. Verbatim from a local run on a laptop:
TL;DRThe planner incorrectly switched to a Sequential Scan on orders because statistics are stale, leading to massive row overestimation and a subsequent join blowup.
- Stale statistics on the
orderstable, causing the planner to drastically underestimate the cardinality of the filtered result set. - The lack of a suitable composite index covering the
WHEREclause columns (customer_id,placed_at) or the join key. - The planner incorrectly choosing a Nested Loop join due to the highly inflated row estimates.
Run VACUUM ANALYZE orders; to force an update of statistics on the affected table.
If the index is known to be correct, temporarily force the planner: SET LOCAL enable_seqscan = off;
Create a composite index on orders covering the filter columns:
CREATE INDEX idx_orders_customer_time ON orders (customer_id, placed_at);
That’s what you need. Fast. Clear. Written in minutes, not twenty.
The project also offers a Flask web UI. plansmith serve. Two text areas. A button. A streamed Markdown panel. Same code path. It’s useful for explaining things to colleagues. Side-by-side. Discussing the LLM’s suggestions.
It’s under Apache-2.0. On GitHub. A real solution for a real problem.
Does This Replace Database Experts?
No. Of course not. But it makes them faster. Much faster. Imagine cutting triage time from twenty minutes to two. That’s significant. This tool augments expertise. It doesn’t replace it. It handles the tedious, repetitive parts. Freeing up human brains for the harder problems. Like, say, actual architecture. Or strategic database design. Things LLMs are still terrible at.
Why is This Important for Open Source?
It proves a point. Local LLMs aren’t just for hobbyists. They have critical, real-world applications. Especially in regulated industries. Where data privacy is paramount. This project removes the barrier to entry for companies that couldn’t otherwise use LLM tech. It democratizes advanced tooling. For sectors that desperately need it.
🧬 Related Insights
- Read more: File Chaos: Engineers Lose 15 Mins Daily [Deckspace Fix]
- Read more: 2029 Quantum Deadline Looms Over Agent Identity Stacks
Frequently Asked Questions
What is Plansmith? Plansmith is a local tool that uses a small language model to analyze and explain differences between two PostgreSQL query execution plans, providing actionable triage steps.
Is Plansmith HIPAA compliant? Yes. Plansmith is designed to run entirely locally on your machine, ensuring sensitive query plan data never leaves your controlled environment, thereby adhering to HIPAA regulations.
Can I use Plansmith with other LLMs? The core diffing logic is separate from the LLM. While the project ships with Gemma 4, it’s designed to be adaptable to other local models supported by Ollama, provided they can handle the task of explaining structured data.
