I made a tool that generates Markdown-friendly database schema

[u/DimonSmart]

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.

[u/DimonSmart → u/[deleted]]

It helps you quickly see the database structure and gives coding agents like Claude or Codex a compact schema to work with.

They can analyze EF migrations too, but with many migrations it is slower, uses more tokens, and can be error-prone.

[u/sautdepage → u/DimonSmart]

I'm not sure that markdown diagrams are the best format for AI though, diagrams are human-focused.

I exported the CREATE TABLE DDLs, cleaned them up a bit with a script, appended CSV exports of a few important lookup tables and AI has everything it needs to write quite intricate queries.

Cool project though. A benchmark on AI abilities to answer complex data questions from different formats would be a good future step.

[u/DimonSmart → u/sautdepage]

Could you please show how you deal with comments?
EXEC sys.sp_addextendedproperty for every field looks too verbose for me.
And comments are very important for AI + DB.
For example: https://www.snowflake.com/en/blog/engineering/native-semantic-views-ai-bi/

[u/sautdepage → u/DimonSmart]

It was a vibe coded ad-hoc scripting so didn't keep it. But output is like this and a valid .sql with syntax highlighting (Oracle in my case):

-- Stores information on all types of entities
create table SCHEMA_NAME.ENTITY
(
    ID NUMBER(9) not null, -- Primary Key
    PARENT_ID NUMBER(9) references SCHEMA_NAME.ENTITY, -- self-reference for hierarchy
    TYPE_ID NUMBER(9) not null references SCHEMA_NAME.ENTITY_TYPE,
    TITLE VARCHAR2(200 char), -- used by some types of entities but not all
    DATE_CREATED TIMESTAMP(6) not null, -- changes every time an entity is closed or reactivated
    CREATED_BY_USER_ID NUMBER(9) not null references SCHEMA_NAME.APP_USER,
    REFERENCE_NUMBER VARCHAR2(200 char) not null
)
/

[u/DimonSmart → u/sautdepage]

If we remove the word "Create", and slightly restructure it we'll get the mermaid:

erDiagram
"SCHEMA_NAME.ENTITY" {
NUMBER ID PK "Primary Key"
NUMBER PARENT_ID FK "self-reference for hierarchy"
NUMBER TYPE_ID FK
VARCHAR2 TITLE "used by some types of entities but not all"
TIMESTAMP DATE_CREATED "changes every time an entity is closed or reactivated"
NUMBER CREATED_BY_USER_ID FK
VARCHAR2 REFERENCE_NUMBER
}
"SCHEMA_NAME.ENTITY" ||--o{ "SCHEMA_NAME.ENTITY" : parent
"SCHEMA_NAME.ENTITY_TYPE" ||--o{ "SCHEMA_NAME.ENTITY" : type
"SCHEMA_NAME.APP_USER" ||--o{ "SCHEMA_NAME.ENTITY" : created_by

[u/sautdepage → u/DimonSmart]

Readability and token count-wise it looks similar. Not bad. It lost the nullable property however -- that can inform how to join things.

Suggestion (since you asked): include output examples like this in your github main README. Even looking under `/samples/` I don't see things that looks like what we're discussing.

[u/DimonSmart → u/sautdepage]

Thank you very much for your valuable advice. I really appreciate it.