-
-
Ingest
-
Ask exact sqlcode
-
Ask vector search
-
Ask jbdc sqlcode
-
Stats
-
Db2 table
Inspiration
Db2 errors like SQL0668N ... reason code 7 or a bare driver exception are hard for newcomers to read. A web search often returns answers for the wrong platform or version, and students and app developers lose hours on it. We wanted a tool that gives a Db2-specific cause and fix in seconds, and that uses Db2 itself to do it.
What it does
You paste a Db2 error and get back its cause, a fix, and a catalog query to check.
Exact lookup: if the text names a code (SQL0204N, SQLCODE=-803, or a code inside a JDBC exception), the answer is a primary-key lookup in Db2. Vector search: if there is no code (“my insert says the key already exists”), Db2 runs a cosine similarity search over embedded knowledge-base entries. Analytics: every request is logged to Db2, and stats reports which errors are diagnosed most often. Optional explanation: a local Ollama LLM can rewrite the retrieved notes as a short explanation. The tool works fully without it.
How we built it
Python CLI with ingest, ask and stats commands. Db2 Community Edition 12.1.5 in Docker, set up with the IBM Db2 Developer Extension for VS Code. The knowledge base is 41 common SQLCODEs. It is stored as a relational table (DOCTOR_KB) and as a VECTOR(384, FLOAT32) table managed by LangChain’s DB2VS. Embeddings come from local all-MiniLM-L6-v2, and VECTOR_DISTANCE(..., COSINE) runs the search inside Db2. Connectivity uses ibm_db_dbi. Every value is bound with a parameter marker, and the knowledge-base reload is one transaction. 24 offline pytest tests run against a recording fake connection.
Challenges we ran into
Vector support: it needs Db2 12.1.2 or later, so we had to get the right Community Edition image running. Routing: exact lookup should run before vector search, because an error that names its code has one right answer. Safety: table names can’t be parameter-bound, so we allow-list them. We also treat pasted error text as untrusted input to the LLM prompt. Testing without a live database: we built a fake connection that records the SQL it receives.
Accomplishments that we're proud of
It works end to end on a real Db2 instance. Ingest loaded 41 rows into both tables, and the exact, vector and JDBC examples all returned the expected codes. Db2 is the only data store: knowledge base, vectors and request log. It works fully offline, with no cloud API needed. It needs only CREATE TABLE, SELECT, INSERT and DELETE on its three tables, not DBADM.
What we learned
Db2 12.1 has native vector search, and langchain-db2 makes it easy to use. Retrieval needs more than embeddings. Exact matching is better when the answer is deterministic, and vectors help only for free-text descriptions. Putting the request log in Db2 turns a tool into something that can report on itself. A tool that depends on an LLM should still work when the LLM fails.
What's next for Db2 Error Doctor
Ingest the full Db2 message reference instead of 41 codes. Parse reason codes, not just describe them. Add a small web UI. Use stats to suggest which missing codes to add next. Add an approximate vector index for larger knowledge bases.
