williamlimasilva/efcore-d2-db-diagram

EF Core D2 Database Diagram Generator

When to Use

Use this skill when the user wants to generate a database / ERD diagram from an Entity Framework Core codebase.

Typical requests:

• Generate a D2 database diagram from EF Core entities.
• Visualize tables, columns, primary keys, foreign keys and relationships.
• Analyze DbContext, DbSet<T>, IEntityTypeConfiguration<T>, Fluent API and migrations.
• Produce a .d2 file renderable to SVG/PNG with the d2 CLI.
• Document the database model of an ASP.NET Core / .NET project.

Goal

Create a readable D2 entity-relationship diagram that reflects the actual EF Core persistence model, not only the raw C# class shape.

The diagram must prioritize:

1. Database tables and relationships.
2. Primary keys, foreign keys, required/optional columns.
3. Owned types and value objects.
4. Many-to-many relationships and join tables.
5. Indexes, unique constraints and table names.
6. EF Core conventions only when explicit mapping is absent.

Output is .d2 source code. It can be rendered to SVG or PNG via the d2 CLI.

Tools

• d2 CLI: render .d2 files to SVG/PNG.
  • d2 input.d2 output.svg
  • d2 --layout=elk input.d2 output.svg
• d2 fmt: format D2 files.
  • d2 fmt input.d2
• No MCP server is required. The skill generates D2 source code as text.

Recommended Workflow

1. Read the EF Core project structure.
2. Locate all DbContext classes.
3. Locate all DbSet<T> declarations.
4. Locate entity classes, owned types, enum types and value objects.
5. Read OnModelCreating and all IEntityTypeConfiguration<T> classes.
6. Read migrations when available to confirm table names, join tables, indexes and delete behaviors.
7. Build a normalized database model before writing D2.
8. Ask the mandatory diagram questionnaire before generation.
9. Generate the .d2 file using the database model, not raw class nesting.
10. Validate D2 syntax with d2 fmt before delivery.
11. Render with d2 --layout=elk schema.d2 schema.svg when possible.
12. If regenerating, re-read EF Core mappings and migrations first.

Mandatory Questions Before Diagram Generation

Ask these questions for every new diagram and every regeneration unless the user already answered them in the same request.

1. Which DbContext should be diagrammed? (auto-detect/all/specific name)
2. Display columns? (all/key-only/none)
3. Display column types? (Yes/No)
4. Display nullable/required markers? (Yes/No)
5. Display indexes and unique constraints? (Yes/No)
6. Display enum values? (Yes/No)
7. Display owned types? (inline/separate/hide)
8. Display many-to-many join tables? (explicit/compact/hide)
9. Display audit/technical tables? (Yes/No)
10. Display migration-only tables not present as entities? (Yes/No)
11. Which grouping mode? (bounded-context/schema/namespace/flat)
12. Which layout engine? (elk/dagre/tala)
13. Which output format? (d2/svg/png)

Default values, when the user asks for a quick generation:

• DbContext: auto-detect
• Columns: key-only
• Column types: Yes
• Nullable markers: Yes
• Indexes: Yes
• Enums: No
• Owned types: inline
• Join tables: explicit
• Audit/technical tables: No
• Migration-only tables: Yes
• Grouping: bounded-context
• Layout: elk
• Output: d2

Reference Documents

Load these on demand when needed:

| Reference | When to load | |---|---| | references/efcore-model-extraction.md | Rules for reading DbContext, DbSet, Fluent API, configurations and migrations | | references/d2-erd-style.md | D2 syntax and visual conventions for ERD diagrams | | references/relationship-rules.md | How to infer one-to-one, one-to-many, many-to-many and owned relationships | | references/grouping-modes.md | Rules for bounded-context, schema, namespace and flat grouping | | references/quality-gate.md | Final checklist before delivering the generated diagram |

EF Core Extraction Rules

Source Priority

Use this priority order when sources disagree:

1. Latest applied migration / migration snapshot.
2. Fluent API configuration in OnModelCreating or IEntityTypeConfiguration<T>.
3. Data annotations.
4. EF Core conventions.
5. Raw C# class shape.

Required EF Core Concepts to Detect

Detect and represent:

• DbContext and DbSet<T>.
• Entity class names and actual table names from ToTable.
• Schema names from ToTable("Table", "schema").
• Primary keys from HasKey, [Key], conventions and migrations.
• Composite keys.
• Foreign keys from HasForeignKey, navigation properties and migration operations.
• Delete behavior when explicit: Cascade, Restrict, NoAction, SetNull, ClientSetNull.
• Required/optional relationship markers.
• Owned types from OwnsOne, OwnsMany and [Owned].
• Many-to-many relationships from UsingEntity and implicit EF Core join tables.
• Indexes from HasIndex, IsUnique and migrations.
• Alternate keys from HasAlternateKey.
• Shadow properties configured in Fluent API.
• Value conversions when they affect persisted type or readability.
• Enum properties.
• Ignored properties and ignored entities.

Diagram Rendering Rules

Tables

Represent each persisted table as a D2 node with shape: sql_table when possible.

Use this content convention:

Clients: {
  shape: sql_table
  constraint: primary_key
  Id: uuid {constraint: primary_key}
  Name: text
  Status: enum
}

If sql_table is unavailable or causes validation issues, fallback to a rectangle with structured text.

Relationships

Use directional edges from dependent table to principal table.

Labels must include relationship cardinality and FK name when known:

Offers.ClientId -> Clients.Id: "N:1 FK_Offers_Clients_ClientId"

Use these cardinality labels:

• 1:1
• 1:N
• N:1
• N:N
• owned

Owned Types

Owned types default to inline rendering.

Inline example:

Clients: {
  shape: sql_table
  Id: uuid {constraint: primary_key}
  Address.Street: text
  Address.ZipCode: text
  Address.City: text
}

If the user chooses separate, represent owned types as visually subordinate tables and use an owned relationship.

Many-to-Many

Default to explicit join tables because EF Core creates real tables.

For implicit many-to-many relationships, create a generated join table node and mark it as implicit join.

Technical Tables

Hide technical tables by default unless requested.

Examples:

• __EFMigrationsHistory
• Hangfire tables
• ASP.NET Identity tables
• Audit logs
• Outbox tables

If technical tables are hidden, mention them in the summary after the diagram.

Grouping Modes

• bounded-context: group by detected domain area or folder/module.
• schema: group by database schema, e.g. public, auth, billing.
• namespace: group by C# namespace.
• flat: no containers, all tables at the same level.

Style Rules

Use consistent styles:

• Primary entity tables: solid border.
• Join tables: dashed border.
• Owned types: lighter stroke or nested inline fields.
• Technical tables: muted style.
• External tables or migration-only tables: dotted border.
• Required relationships: solid line.
• Optional relationships: dashed line.
• Cascade delete: label suffix cascade.

Quality Gate Before Delivery

Before delivering the diagram, verify:

• [ ] The selected DbContext is clear.
• [ ] All DbSet<T> entities are considered.
• [ ] Fluent API configurations are read.
• [ ] Migrations are checked when present.
• [ ] Table names and schema names match EF Core mapping.
• [ ] Primary keys are present.
• [ ] Foreign keys and cardinalities are represented.
• [ ] Owned types are handled according to user choice.
• [ ] Many-to-many join tables are explicit unless the user asked otherwise.
• [ ] Hidden technical tables are listed in the final summary.
• [ ] D2 syntax is valid with d2 fmt.
• [ ] Edge endpoints use full dot-notation when inside containers.
• [ ] The diagram remains readable and avoids crossing-heavy layouts.

Output Format

When the user asks for a skill installation, provide this folder structure:

.github/
  skills/
    efcore-d2-db-diagram/
      SKILL.md
      references/
        efcore-model-extraction.md
        d2-erd-style.md
        relationship-rules.md
        grouping-modes.md
        quality-gate.md

When the user asks to generate a diagram, provide:

1. The .d2 source file content.
2. The render command using the selected layout engine.
3. A concise summary of assumptions and hidden tables.