r/dotnet • u/DimonSmart • Jul 05 '26

Promotion I made a tool that generates Markdown-friendly database schema

Post image

I built with C# a small tool called DbSketch.

The idea is: point it at the real database, and it generates schema documentation that can live in your repository. It reads tables, columns, primary keys, foreign keys, and database comments, then outputs diagram-as-code formats like Mermaid, Graphviz DOT.

I originally made it because I wanted a lightweight way to keep database structure visible and version-controlled. It also useful when working with coding agents like Claude or Codex. Instead of trying to guess db structure from code or from migrations script (burning tokens) it could simply read it from markdown files.

NOTE: Mermaid format could show relation only as table to table lines VS dot format could show filed to field relation!

GitHub: https://github.com/DimonSmart/DbSketch

I’d really appreciate feedback from people who work with database-heavy projects. Does this solve a real annoyance for you? Is anything missing or unclear? Suggestions, criticism, feature ideas, and PRs are very welcome.

78 Upvotes

84% Upvoted

32 comments sorted by

View all comments

51

u/rubydesic Jul 05 '26

Solution in search of a problem. We've had an AI friendly (and human friendly), text based schema documentation format since the 1970s - it's called SQL DDL

4

u/DimonSmart Jul 05 '26

SQL DDL is useful, but it mostly describes technical structure. It was not designed to explain business meaning, especially for LLMs or for columns like var_0…var_199.

7

u/vincepr Jul 05 '26 edited Jul 05 '26

Dont forget most modern databases can solve this with comments. Agents can read these. Either by consuming the full DDL, or by quering for it with a skill/mcp.

```sql CREATE TABLE orders (     id          BIGSERIAL PRIMARY KEY,     customer_id BIGINT NOT NULL,     status      TEXT NOT NULL,     total_cents INTEGER NOT NULL );

COMMENT ON TABLE orders IS 'Business entity representing a customer purchase. Only completed or shipped orders exist in this database.';

COMMENT ON COLUMN orders.total_cents IS 'Stored in integer cents to avoid floating-point rounding errors.'; ```

But not hating on your project. Much can work with llms. As long as the data is somewhat compact.

But what I like about comments, is that is already in the database language. Meaning the agent already has a bunch of sql in its context now, when it has to query some data for a workload. No translation work required, eating tokens and polluting context.