Benchdog SQL Documenter

Run benchdog sql doc --server demo.database.windows.net --database AdventureWorksLT --out docs --format html --format pdf. The formats are html, markdown, word and pdf, and html is the default. Give --database more than once to put several databases on the same server in one document.

Add --windows for a SQL Server on your network with your Windows account, or --sql-login sa for a server that only allows SQL logins; Benchdog asks for the password without showing it. The command prints each step as it goes, then Wrote 117 files for 112 pages to docs. and the page to open first.

On the command line, --title, --author and --copyright go on the cover, in the file's properties and in every footer. --logo brand/logo.png puts a PNG or JPEG logo, up to 5 MB, on the cover and in the HTML header, --css brand/docs.css adds your stylesheet after the HTML one, and --name Sales names the Word or PDF file. The title defaults to the database name.

In the desktop app the Generate tab has boxes for the title, author and copyright. The logo, CSS and file name live in a project file, as logo, css and output.name, and the app keeps them when you open and save one.

Keep or leave out objects by name with --include sales.* and --exclude dbo._*, where * and ? are wildcards. Leave out a whole kind with --exclude-kind users; the kinds are tables, views, procedures, functions, triggers, types, sequences, synonyms, users, roles and schemas.

Leave out a section on every page with --exclude-section scripts, or on one kind's pages only with the kind first, such as --exclude-section tables:scripts. The sections are scripts, permissions, dependencies, extended-properties, indexes, constraints, triggers, files, options, space, protection and diagrams. A link to anything left out becomes plain text. In a project file the same choices are include, exclude, excludeKinds and excludeSections.

In VS Code, click the pencil beside an object, column or parameter, or right-click a database and choose Edit Description. In the desktop app, pick the item in the tree, type in the box on the right and press Save. The text is saved in the database as MS_Description, so SSMS shows it too, and clearing it removes it after you confirm.

From the command line, benchdog sql describe --server demo.database.windows.net --database AdventureWorksLT --object SalesLT.Customer --column EmailAddress --text "The customer's main email address" shows the old and new text and asks for y or yes first. Use --parameter @CustomerId for a parameter, --schema sales, --principal reporting or --whole-database for a schema, a user or role, or the database itself, --remove to remove the text, --property for any other extended property, and --yes in scripts. SQL Server keeps up to 3,750 characters.

Tick more than one database in the Generate tab or in the Generate Documentation picker in VS Code, or give --database more than once on the command line for databases on one server. The result is one document with a project cover listing the databases, a page and contents for each, and a chapter for each in Word and PDF.

For databases on different servers, use a project file: each entry under databases names its own server, database and signIn, which is entra, windows or sql with a user. Add --server-page, or "serverPage": true, for a page about each server with its version, edition, collation, main settings and the databases documented on it.

Save a .sqldoc.json project file. In VS Code, New Project File on the view's menu writes one for the databases in the view, and the file then gets autocomplete, hover help and a Generate Documentation link at the top; you can also right-click the file in the Explorer and choose Generate Documentation from Project. In the desktop app, File, Open project fills the Generate tab from a file and File, Save project writes the tab's choices back.

On the command line, benchdog sql doc --project sales.sqldoc.json makes the documents the file describes, and --out or --format on the command line override what the file says. Paths in the file are relative to it, comments and trailing commas are allowed, and it holds a SQL login's name but never its password.

HTML is a folder of pages with a sidebar tree and a filter box; open index.html straight from disk, as it loads nothing from the internet. Markdown is a file per page with relative links, made for an Azure DevOps wiki or GitHub, with diagrams as Mermaid blocks that GitHub draws.

Word and PDF are one file each, named after the database or --name, with a chapter for each group, every object in Word's navigation pane and the PDF's bookmarks, links that jump to the page or column, and page numbers in the footer. PDFs embed their fonts, so they look the same on every system.

Right-click a database in VS Code and choose Test Connection, or run benchdog sql test --server sqlhost --database Archive --windows. Both show the login the server sees, with its edition and version, such as Connected to Archive on sqlhost as DOMAIN\you. followed by SQL Server 16.0.1000.6, Developer Edition (64-bit).

It connects as you and reads the database's catalog views in one round trip, so it needs to be able to connect and see the objects. Row counts and sizes come from SQL Server's own catalog, not from the data, and logins are never read. An encrypted view, procedure or function, or one written in .NET, has no definition to show, and the page says so.

Saving a description uses SQL Server's own sp_addextendedproperty, sp_updateextendedproperty and sp_dropextendedproperty, so it needs the same rights as changing the object: ALTER on it, or CONTROL on the database to describe the database itself. The server page reads the server's settings; when you may not read them, the page says so and the database is still documented.

Only the structure is read, never table data: settings, files, schemas, tables, columns, keys, indexes, constraints, views, procedures, functions, triggers, types, sequences, synonyms, users, roles, permissions, dependencies and extended properties. SQL Server 2017 or later and Azure SQL are supported, and the catalog is read as the signed-in user.

A database changes only when you save a description, and a description is removed only after you confirm. The output folder must be new, empty, or one SQL Documenter wrote before, which it knows by the .benchdog-sqldoc list of files it wrote, so it never removes a file it did not write. Removing a database from the list changes nothing in the database.

Yes. Add a database by its server name and choose Windows sign-in, and no Benchdog sign-in is needed; the desktop app and the command line work before you sign in. Entra sign-in works on your own servers too, and a SQL login, such as sa on SQL Server in Docker, is there for servers that only allow one. The list of Azure SQL databases is the only part that needs your Benchdog sign-in.

It never reads table data, so there are no sample rows in the documents. A password is never scripted: a contained user with a password or an application role gets a commented-out statement with ... in its place. SQL Server's own objects, such as sysdiagrams, are left out. The diagram on a database's page is drawn only when it has 60 or fewer tables with foreign keys, and every diagram shows up to 25 objects and says how many more it left out.

PDFs use the Inter font, which has no Chinese, Japanese or Korean letters, so those show as boxes in a PDF. Word 2016 or later shows the SVG diagrams in a Word file; older Word shows a blank picture.

It uses the same place SSMS does. Every description you see in the tree and in the documents is the object's MS_Description extended property, so anything already there shows at once, and anything you write in Benchdog shows in SSMS. Every run reads the live database, so the documents match what is deployed on the day they are made.

Yes. Every tool has a thirty day trial with every feature, and no card. Ask for one at benchdog.dev/trial with your name and email, and the trial licence arrives by email, as a line to paste and a benchdog.licence file. One trial per person covers every tool at once.

One licence is for one person and covers the VS Code extension, the desktop app and the benchdog command, on every machine that person works from. There is no machine limit and no server count. Buying another tool reissues your licence with that tool added.

The licence shows whose it is: your name and email appear in each tool's About and account menu.

The last version released while you were paid keeps working. Only updates stop. A licence is checked offline and never expires a version it covers, so nothing stops working the day your year ends.

The VS Code extensions run in VS Code 1.95 or later on Windows, Linux and Mac. The desktop apps and the benchdog command are single programs for Windows (x64), Mac (Apple silicon) and Linux (x64), with no .NET install needed. The SQL tools work with SQL Server 2017 or later, Azure SQL Database and Azure SQL Managed Instance.

No. The engine runs on your machine, reads your vaults and databases as you, and keeps the results with you. A tool contacts benchdog.dev only when you click something that needs it, such as asking for your licence, and never in the background. Licences are checked offline.

Every change a tool makes runs in one transaction with XACT_ABORT on, so it all happens or none of it does. A SQL Schema Compare deploy, a SQL Data Comparer sync and a SQL Data Filler fill are each one transaction, and SQL Data Scrambler scrambles each table in one. The scripts the tools write for you to run in SSMS or sqlcmd are wrapped the same way and roll back if any batch fails. SQL Multi Runner runs your own script as it is, and wraps each database in a transaction when you tick that. Before any change, a tool says what it will do and asks first: SQL Schema Compare names the tables and columns whose rows go, SQL Data Comparer says how many rows change, and SQL Data Scrambler asks you to type the database's name. SQL Schema Compare also stops if either database changed after you read the plan. Even so, nothing replaces a backup, and the SQL Server tools can take one first.

Azure calls run as you, through a browser sign-in once or through your existing az login, in any tenant you belong to. The SQL tools use your Microsoft account, your Windows sign-in or a SQL login, and every connection is encrypted. A SQL login's password is kept until the app closes, or in your system's secure store (DPAPI on Windows, Keychain on Mac, libsecret on Linux) if you tick Remember. It is never written to a settings file, a project file or a log.

The message is C:\docs already holds other files. Pick an empty folder, or one Benchdog SQL Documenter wrote before. A folder can be documented to when it is new, empty, or holds the .benchdog-sqldoc list from an earlier run. A .sqldoc.json project file and files a system adds, such as .DS_Store, desktop.ini and Thumbs.db, do not count. Pick another folder, or empty this one yourself; SQL Documenter will not remove files it did not write.

The message is The text is 4000 characters. SQL Server keeps up to 3750. SQL Server holds up to 3,750 characters in an extended property, so shorten the text. Blank text removes the description instead, after you confirm.

VS Code shows every problem the engine finds in the Problems panel on its line, and the desktop app names it with its line and column under PROJECT. The messages say what to fix, such as list at least one database under "databases"., every database needs a "server" and a "database"., signIn for Archive must be entra, windows or sql., Archive signs in with sql, so it needs a "user". The password is never kept in a project file. and there is no format called docx. Use html, markdown, word, pdf. A file that is not JSON gets a project file is JSON that starts with {, but this one starts with ... with the line and column.

The message is SQL Server refused the password for sa on localhost. Enter it again. A refused password is forgotten at once, from memory and from the system's secure store, so the next try asks again. To clear a remembered password yourself, right-click the database and choose Forget Password, use Database, Forget saved password in the desktop app, or run benchdog sql forget-password --server localhost --sql-login sa.

The message is Benchdog found no Azure SQL databases you can see. Check the tenant in Settings, or add the database by its server name. The list comes from the subscriptions your account can see in one tenant, so set benchdogSqlDoc.tenant in VS Code, or the tenant in the desktop app's Settings, when the databases are in another tenant you belong to. Or pick SQL Server, type the server's name and sign in with Entra, which needs no list at all.

The page says The definition is encrypted, so SQL Server does not show it. for a view, or There is no definition to show: it is encrypted, or written in .NET (CLR). for a procedure, function or trigger. SQL Server keeps no readable code for an object created WITH ENCRYPTION or written in .NET, so there is nothing to document beyond its parameters, columns, dependencies and permissions, which the page still shows.

Turn on the diagnostics log: in a desktop app, Settings, then Write a diagnostics log; in VS Code, the extension's diagnostics setting; for the benchdog command, set the environment variable BENCHDOG_DIAGNOSTICS=1. Each run writes one file to the logs folder in the Benchdog folder (%LOCALAPPDATA%\Benchdog\logs on Windows, ~/Library/Application Support/Benchdog/logs on Mac, ~/.local/share/Benchdog/logs on Linux), and the last ten are kept. The desktop apps have Open logs folder, and VS Code has the Open Diagnostics Logs Folder command.

The log records sign-in requests, Azure calls, engine requests, SQL connections, times and errors. Passwords, connection strings, tokens, secret values and your data are never written, so it is safe to send to support.

That is the crash window, for an error the app did not expect. Copy details puts the error and its details on the clipboard, Email support opens a message to support with them, and Open logs folder shows the crash report, which is written even with the diagnostics log off. If the error happened on a background thread the app has to close, and the window shows when it next starts.

Browser sign-in keeps its tokens in the desktop keyring, and that machine has none unlocked, which is common in WSL. Install and unlock a keyring such as GNOME Keyring or KWallet, or sign in with az login and turn on Use az login in Settings or pass --cli to the benchdog command. Benchdog never falls back to a plain file for tokens.

The SQL Server you connected to uses a certificate your machine does not trust, which is usual for a server on your own network with a self-signed certificate. Pick Trust the server's certificate in the picker, or add --trust-server-certificate on the command line, for servers you know. For a server you do not know, install its certificate chain instead.

In a desktop app, choose Forget saved password from the menu. On the command line, run benchdog sql forget-password --server <server> --sql-login <login>. Either removes it from the system's secure store, which is the only place it was kept.

Write to support@benchdog.dev or use the support form on this site, and a person replies. Say which tool and version you were using (Help, About in a desktop app shows both), what you did and what you saw, and attach the diagnostics log if you have one.