pg-llm-usodb: The PostgreSQL Server That Makes Up Its Own Database
It speaks the wire protocol, fools real clients, and uses an LLM plus virtual state to fabricate tables, rows, and metadata on demand.
pg-llm-usodb … LLMが"それっぽい"応答を捏造するPostgreSQL互換サーバー。「LLMエージェントが得意な実装・よく理解している概念」を語る入口に
- pg-llm-usodb is not a better SQL engine. It is a protocol-faithful illusion that lets a real client interrogate a database that invents its own contents.
- Its real innovation is state, not generation. VirtualDbState and JSONL logging make the hallucination durable enough to survive follow-up queries and replay.
- The project saves LLM calls for the moments that need invention, while fast paths handle routine introspection and cached answers.
- It sits in a narrow middle lane between mocks, text-to-SQL tools, and real databases, which is why it is useful for agent stress testing and fast prototyping.
The Database That Isn’t There
The first trick is that this is not a database app pretending to be one. It is a real PostgreSQL server on the wire, which means tools like psql and ORM clients can connect and start behaving normally. The surprise is that the server then improvises the rest.
That matters because most mock databases ask developers to script the answers up front. pg-llm-usodb flips the burden around. The client’s queries become the input that shapes the fiction.
Why This Is More Than a Toy Mock
| Approach | Input | Output | State | Client compatibility | Best use case |
|---|---|---|---|---|---|
| Traditional SQL mock | Test code | Predefined rows or errors | Manual or absent | Low, often adapter-specific | Unit tests with fixed expectations |
| Text-to-SQL system | Natural language | SQL text | Usually none | Indirect | Query generation and assistants |
| pg-llm-usodb | SQL over PostgreSQL wire protocol | Fabricated rows, metadata, and schema | VirtualDbState plus JSONL log | High, real PostgreSQL clients can connect | Agent stress testing and rapid prototyping |
| Real database | SQL over PostgreSQL wire protocol | Persisted truth from storage | Durable engine state | High | Production or serious local development |
The table above is the point. This project is not trying to outgrow mocks by being more configurable. It is trying to outgrow them by being protocol compatible. That means you can aim a real app at it and see how far the illusion holds.
The Three-Layer Stack
The architecture is intentionally split into three layers. The PostgreSQL adapter handles the wire protocol. The LLM service layer decides what kind of response to invent. The utility layer keeps an append-only trail of what happened.
The Query Router: Fast Path, Introspection, Mutation
This is the best engineering move in the repository. Not every query deserves the same amount of invention. Routine metadata can come from memory or a fast cache. The ambiguous or state-changing cases go through specialized agents.
// Conceptual shape of the router
switch (classify(sql)) {
case 'fast-path':
return answerFromMemory(sql)
case 'introspection':
return runExecuteAgent(sql)
case 'mutation':
return runTableOrRecordAgent(sql)
}
Why VirtualDbState Is the Real Product
The illusion only works if the server remembers what it claimed five queries ago. That is what VirtualDbState does. It tracks tables, columns, and action history so the next query can be consistent with the last one.
That makes the project feel less like a generator and more like a state machine with a very creative transition function. Once a table exists, later selects can refer to it. Once a row is inserted, later filters can find it.
JSONL Replay Makes the Hallucination Auditable
The system also keeps a JSONL action log. That is a sober design choice in an otherwise playful project. Every mutation can be appended, replayed, and inspected without guessing how the virtual database got into its current state.
This is what turns the project from a demo into a debugging surface. If the hallucination goes wrong, there is a paper trail.
Where It Stops Working
- It supports the Simple Query protocol, not the full extended query flow.
- Prepared statements and many advanced ORM paths are out of scope.
- Its consistency depends on the LLM and the state model, so determinism is limited.
- It is built for believable interaction, not for production truth.
Those limits are not incidental. They define the niche. This is a tool for experiments, not a drop-in replacement for PostgreSQL.
What It Replaces, What It Refuses To Be
| Tool type | What it gives you | What it refuses | Where pg-llm-usodb fits |
|---|---|---|---|
| SQL mock | Predictable canned answers | Real protocol behavior | Too static for agent testing |
| Text-to-SQL assistant | Natural language to SQL | A believable database backend | It goes the other direction |
| Real PostgreSQL | Durable data and correctness | Synthetic invention on demand | It imitates the interface, not the guarantees |
| pg-llm-usodb | A database that improvises under load | Truthful storage | A protocol-faithful hallucination engine |
That last row is the whole story. The project is useful because it stands in the awkward space between fake and real. It is convincing enough to test software, but unstable enough to expose how much of a client’s trust lives in the wire protocol itself.
