AI for Database Documentation: Our Approach

The Documentation Nobody Wrote

Every long-lived Oracle database carries objects whose purpose is genuinely unknown. A package last modified in 2011 by someone who left in 2014. A table with 60 columns where eleven are populated. A trigger that exists because of an incident nobody recorded.

Documentation was never written because it is tedious and low-status work, and it is exactly the kind of tedious work worth automating — provided you are honest about what the output is.

Start From What Is Provable

The foundation is not generated — it is extracted from the catalog, which cannot be wrong: columns and types, constraints and their definitions, indexes and what they cover, foreign keys and the dependency graph, row counts and storage size, which objects reference which.

That dependency graph alone answers most of the questions people actually have (“what breaks if I change this?”), and it needs no model at all.

Then What Must Be Inferred

The genuinely useful layer on top: a plain-language summary of what a 900-line package does, the apparent purpose of a table inferred from its columns and relationships, and a note on which constructs will need attention during migration.

This part is inference, so it gets labelled as inference. Generated descriptions are marked as such, kept separate from extracted facts, and never silently merged with them. Documentation that mixes “this column is NUMBER(10)” with “this column probably holds a customer tier” without distinguishing them is worse than no documentation, because it launders a guess into a fact.

Grounding in Reality

The most valuable annotation isn’t a description at all — it is evidence of use. A column that is 100% NULL across twelve million rows is almost certainly dead, whatever anyone believes about it. A table nothing references and nothing has written to in two years is a migration candidate for deletion, not conversion.

CUSTOMER_ARCHIVE            2.1M rows   last DML: 2019-03   refs: 0
  CUST_TIER    NUMBER(2)    100% NULL   -> dead column
  LEGACY_CODE  VARCHAR2(8)   3 distinct -> lookup, candidate for enum

Nothing there was invented. It is measurement, and it settles arguments that opinions cannot.

Do It During the Migration

A migration is the one moment when someone is systematically reading every object in the database. Capturing that understanding as it happens costs almost nothing; reconstructing it later costs the same discovery work again. The migration is also the natural point to delete rather than convert — the cheapest object to migrate is one you decide not to.