How to Document SQL Server Schemas Visually in 2025
For the person who owns a SQL Server schema nobody has written down, and has to hand a readable version of it to developers, auditors or a new colleague.
On this page
A new developer joins, opens the database, and gets a flat list of two hundred tables. Which ones belong to billing, which foreign key connects an invoice to its customer, and what user_event_log_old was for are questions the list cannot answer. DbSchema answers them by reverse-engineering the SQL Server schema into diagrams you arrange, descriptions you write once, and documentation you export as HTML5, PDF or Markdown from the DbSchema database documentation tool.
The diagram DbSchema draws from the live schema
DbSchema connects to your SQL Server instance and reads the schema over JDBC: tables, columns, keys, indexes. It lays the tables out on a diagram with a line for every foreign key, and select all plus Diagram → Auto Arrange untangles the layout of a schema that came back overlapping.
One diagram for two hundred tables helps nobody, and DbSchema does not force one on you. A project holds many diagrams, each with its own layout and its own visible tables, so billing, reporting and staging each get a picture a person can actually read. The same table can appear on several of them. Everything you arrange, group and hide is stored in the DbSchema model file, a .dbs XML file on your computer; the SQL Server database is only read.
Interactive HTML5 documentation, and PDF or Markdown from the same dialog
Diagram → Export HTML5 or PDF Documentation opens the documentation dialog, where you choose the format, the diagrams to include, and which schema elements go in: tables, columns, foreign keys, indexes, comments. Tagging diagrams with the tag documentation lets you export exactly those, in the order the tag value sets.
The HTML5 output opens in any browser with no server behind it. It carries the diagram as a vector image, a searchable table list and the full column details, so a reviewer clicks a table to jump to its definition and hovers a column to read its description. PDF is the printable version of the same content for an audit or a formal review, and Markdown writes each table as a section with columns, types and descriptions, which is the format to commit next to the source code. Documentation export is a Pro feature.
Descriptions and comment tags that survive the export
A diagram shows how the tables connect. What each one is for has to be written down, and the place to write it is the schema itself rather than a wiki page that drifts. Text you type in the Description field of a table or a column appears in every documentation format DbSchema generates, and in the HTML5 output it also shows as a mouse-over tooltip on the table or column name.
Comment tags are the structured version: key-value pairs attached to a table or a column, for the owner, the sensitivity level, the deprecation status. They land in the generated documentation too, and automation scripts can read them, which is how a nightly job can list every column tagged as personal data. Descriptions and tags are saved in the DbSchema model file; nothing is written to SQL Server until you apply a change through the synchronization dialog.
The model file belongs in Git
The .dbs file is XML, so it versions like source code. Open the Model menu, choose Git — Collaborative Design, and enter the repository URL and your credentials. From that dialog you Stage the changed file, Commit it with a message, and Push it to GitHub, GitLab, Bitbucket or a self-hosted server, and Pull brings back what a colleague pushed. The Git guide walks through the whole cycle.
The payoff arrives on the pull. Compare with Current opens the Synchronization Dialog against the version you just fetched, so you see exactly which tables and columns changed in a teammate's branch before any of it reaches a database. Saving the model to a file is a Pro feature, and so the Git workflow around it is too.
When someone alters the database behind your back
Not every change goes through the model. Somebody adds a column in SSMS at four in the afternoon, and your documentation is wrong by five. Reconnect and click Refresh Model from Database: DbSchema compares the model with the live SQL Server schema and lists every difference.
Each difference is yours to decide in the Synchronization Dialog. Apply it to the database, pull it into the model, or generate a migration script and hand it to whoever runs deployments. That is also the only step in this workflow that changes the SQL Server schema, which is why designing offline is safe: switch the connection to Disconnected, keep editing, and the changes stay in the .dbs file until you reconnect and synchronize. Schema synchronization is in the Pro edition.
Views, procedures and triggers, not only tables
Half of what a SQL Server database does lives in views, stored procedures, functions and triggers. The standard JDBC API does not expose the triggers, the procedures and the functions, so DbSchema retrieves those with per-database queries you can inspect and adjust. The Project Structure panel then lists them next to the views, tables, indexes and constraints.
Right-click any object there to open its data, edit its structure, or drop it onto a diagram, which is how a view that joins six tables ends up on the same picture as the tables it reads. Add a description to it the way you would to a table, and the description goes into the exported documentation with everything else.
Rows to look at while you demonstrate the schema
An empty diagram is a poor demo, and QA cannot test against a schema with no rows in it. Data Tools → Generate Random Data opens the Data Generator, where each column gets a pattern, from plain numbers and dates to reverse regular expressions and Groovy scripts, and you set the number of rows per table. Order the tables so a parent is filled before the table that references it.
This step writes rows into SQL Server. Every step above it changes only the model file, apart from the Synchronization Dialog, which applies schema changes to the database. DbSchema asks whether to drop the existing data before generating, so point it at a development instance and never at production. The Data Generator is a Pro feature, and the patterns it uses are saved in the model file with the rest of the design.
Following the foreign keys through real rows
Documentation explains the structure; the rows explain the meaning. The Relational Data Editor opens a table and the tables related to it side by side, and clicking a row in the parent refilters every child pane to the records that match, as many levels deep as the foreign keys go. Where SQL Server has no foreign key, drag one column onto another in the diagram to create a virtual foreign key: it is stored in the model file, changes nothing in the database, and the editor follows it exactly like a real one.
That makes the editor the fastest way to find out what a table like user_event_log_old actually holds and which rows still point at it. Edits you make in it are pending until you click Commit, so browsing costs nothing. The Relational Data Editor is in the Pro edition.
Documenting a SQL Server schema stops being a project of its own when the documentation comes out of the design you already keep. Download DbSchema at https://dbschema.com/download.html, connect to your database and read the diagram in the free Community Edition; the HTML5, PDF and Markdown documentation, the Git workflow around the model file, schema synchronization, the Data Generator and the Relational Data Editor are in Pro.
