okhp3-database-cartographer

okhp3-database-cartographer

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Interrogates a live database of largely unknown or partially-documented structure and turns it into two things: a schema inventory with severity-classified findings against whatever spec you point it at, and a Mermaid ER diagram. It does the surveying and the cartography does not happen in the same tool -- interrogation and diagramming are deliberately decoupled (see "Architecture" below), because the best tool for connecting to a database and the best tool for drawing a diagram are never the same tool.

Scope

If the task is "does this database's structure match what we documented" or "what does this database actually look like," this is the right skill. If the task is "is the data in this table clean" or "write me a migration," it is not.

Architecture: two jobs, two tools, one handoff

Interrogation (engine-specific, produces a normalized schema-inventory) → diagramming (engine-agnostic, produces Mermaid text). Nothing about the diagram-generation step knows or cares which database engine the data came from. This split is why the skill doesn't depend on any single-purpose "database-to-ER-diagram" library -- those libraries (eralchemy2 and similar) couple the two jobs together and inherit the weaker of the two tools' maintenance status. Reflection tooling (SQLAlchemy) is rock solid; diagram-generation tooling that also does DB connections is not. Decoupling means each half can be swapped independently.

Step 1 -- Interrogate

Pick the adapter for the target engine. Full driver table, INFORMATION_SCHEMA/sys.* fallback queries, and per-engine gotchas: references/engine-adapters.md.

• Postgres, MySQL/MariaDB, MSSQL, SQLite, Oracle: one code path. sqlalchemy.inspect(engine) returns tables, columns, types, PK/FK, indexes in one consistent shape regardless of engine. Use sqlacodegen if the deliverable should include generated ORM model code, not just an inventory.
• MS Access (.accdb/.mdb): pyodbc + the Access ODBC driver on Windows, or COM/DAO automation. Treat this path as fragile -- say so in the output, don't present it with the same confidence as the SQLAlchemy path.
• Firestore/NoSQL: out of scope for this version. No mature Python tooling exists to lean on; don't attempt a from-scratch sampling script under this skill without an explicit ask.

Normalize whatever comes back into one shape:

{
  "entities": [
    {"name": "TABLE_NAME", "columns": [
      {"name": "col", "type": "int", "constraints": ["PK"], "note": "optional annotation"}
    ]}
  ],
  "relationships": [
    {"from": "A", "to": "B", "cardinality": "||--o{", "label": "relationship verb"}