DimonSmart.DbSketch 0.1.4

DbSketch

DbSketch is a small C# CLI tool that reads a live database schema and writes a compact database structure diagram.

The MVP supports SQL Server, PostgreSQL, and MySQL. It reads schemas/namespaces, tables, columns, primary key markers, and real foreign key relationships, then applies include/exclude table filters before rendering DOT or Mermaid.

Install

Global tool

dotnet tool install --global DimonSmart.DbSketch
dbsketch generate --config dbsketch.yml

Local tool in repository

dotnet new tool-manifest
dotnet tool install DimonSmart.DbSketch --version 0.1.0
dotnet tool restore
dotnet tool run dbsketch -- generate --config dbsketch.yml

One-shot run

dotnet tool exec DimonSmart.DbSketch@0.1.0 -- generate --config dbsketch.yml

With .NET 10, dnx can also run the tool:

dnx DimonSmart.DbSketch@0.1.0 -- generate --config dbsketch.yml

CI example

- name: Restore local tools
  run: dotnet tool restore

- name: Generate DB schema diagram
  env:
    DB_CONNECTION: ${{ secrets.DB_CONNECTION }}
  run: dotnet tool run dbsketch -- generate --config dbsketch.yml

Development

Build and test:

dotnet restore DbSketch.sln
dotnet build DbSketch.sln
dotnet test DbSketch.sln
dotnet pack src/DbSketch.Cli/DbSketch.Cli.csproj -c Release

The .NET tool package id is DimonSmart.DbSketch; the installed command remains dbsketch.

Git hooks

This repository uses Husky.Net for local Git hooks.

After cloning the repository, run:

dotnet restore DbSketch.sln

The restore step installs local .NET tools and configures Git hooks automatically.

The pre-commit hook formats staged .NET files with dotnet format and re-stages only files that were already staged before the hook started.

To skip hooks for a single commit:

git commit --no-verify

To disable Husky installation in CI or special local environments:

HUSKY=0 dotnet restore DbSketch.sln

Direct CLI options can override config values:

dbsketch generate --provider sqlserver --connection "Server=.;Database=AppDb;Trusted_Connection=True;TrustServerCertificate=True" --out docs/db/schema.dot

Config

provider: sqlserver
connectionString: ${DB_CONNECTION}

include:
  tables:
    - "dbo.*"

exclude:
  tables:
    - "dbo.__EFMigrationsHistory"
    - "dbo.Log_*"

output:
  path: docs/db/schema.dot
  format: dot # dot, md-dot, mermaid, md-mermaid

diagram:
  title: "Database schema"
  rankdir: LR
  compact: true
  show:
    schemaName: true
    columnTypes: false
    nullability: false
    primaryKeys: true
    foreignKeys: true

descriptions:
  enabled: false

Provider aliases: mssql maps to sqlserver, and postgresql maps to postgres.

Output Formats

Supported values for output.format and --format:

• dot: raw Graphviz DOT.
• md-dot: Markdown with a fenced dot block.
• mermaid: raw Mermaid erDiagram.
• md-mermaid: Markdown with a fenced mermaid block.

Example Mermaid Markdown config:

output:
  path: docs/db/schema.md
  format: md-mermaid

erDiagram
  direction LR
  "dbo.Orders" }|--|| "dbo.Users" : "FK_Orders_Users"

Manual Integration Tests

DbSketch has explicit manual integration tests that use Testcontainers and require Docker. They are not run by default.

Run them explicitly:

dotnet test --filter-method "DimonSmart.DbSketch.Tests.Integration.PostgresNorthwindEndToEndTests.Generate_WithPostgresNorthwind_WritesDotSchema" --explicit only

Example DOT

digraph DbSketch {
  graph [
    rankdir=LR,
    labelloc="t",
    label="Database schema"
  ];

  "table_dbo_Orders":"col_UserId" -> "table_dbo_Users":"col_Id" [
    label="FK_Orders_Users"
  ];
}

Not Supported Yet

DbSketch does not render SVG/PNG, run Graphviz or Mermaid CLI, generate DBML or PlantUML, infer relationships by naming convention, read database comments, generate HTML docs, diff schemas, or provide a GUI.