SchemaSpy with LocalDB (SQL Server)

Intro

SchemaSpy is my preferred tool for generating browsable HTML docs and ER diagrams from SQL databases. I’ve already shown how to configure it with SQLite, but SQL Server’s LocalDB edition introduces a completely different set of quirks.

LocalDB is a lightweight SQL Server runtime used by tools like Lansweeper and Visual Studio. Unlike full SQL Server or Express, which run as services and listen on TCP, LocalDB doesn’t accept TCP connections at all. It only exposes a named pipe endpoint, and it only works with Windows integrated authentication (NTLM/SSPI).

That’s why most SchemaSpy guides skip LocalDB entirely — Microsoft’s official JDBC driver expects TCP, and Java has no built-in NTLM support. The workaround is to use the older jTDS driver, which still supports named pipes, plus its companion ntlmauth.dll for NTLM authentication.

After a lot of trial and error, I found a reliable combination: SchemaSpy 6.1.0 + jTDS 1.3.3 + ntlmauth.dll + Graphviz 2.38. It’s fiddly, but once you have the pieces in place, you can generate a complete HTML schema doc site for any LocalDB-backed application.

The Pieces You Need

Heads-up Microsoft’s official JDBC driver cannot connect to LocalDB — it only works over TCP. That’s why jTDS is required.

Suggested Setup (Windows)

Keep everything SchemaSpy needs in one folder so paths are consistent:

C:\bin\SchemaSpy\
  schemaspy-6.1.0.jar     # SchemaSpy itself
  jtds-1.3.3.jar          # JDBC driver
  ntlmauth.dll            # From jTDS zip, for Windows SSO

Install Graphviz to its default location:

C:\Program Files (x86)\Graphviz2.38\

Important About ntlmauth.dll
The jTDS 1.3.3 zip includes three versions:

• x86\ntlmauth.dll → use if you run 32-bit Java
• x64\ntlmauth.dll → use if you run 64-bit Java (most common today)
• ia64\ntlmauth.dll → legacy Itanium, almost never needed

Copy the correct DLL into your C:\bin\SchemaSpy\ folder. When running SchemaSpy, add:

-Djava.library.path="C:\bin\SchemaSpy"

If the bitness doesn’t match, you’ll see UnsatisfiedLinkError or “Login failed” errors.

Step 1: Find the LocalDB Instance Pipe

LocalDB doesn’t have a fixed hostname like localhost,1433. Instead, every time it starts, Windows assigns it a unique named pipe. That pipe is what jTDS connects to.

To check the pipe, open PowerShell or Command Prompt on Windows (on the same machine that’s running LocalDB) and run:

SqlLocalDB start LSInstance
SqlLocalDB info  LSInstance

This will print details about the LocalDB instance, including the Instance pipe name. For example:

np:\\.\pipe\LOCALDB#SH964109\tsql\query

The important part is the instance token (LOCALDB#SH964109). You’ll pass that value into SchemaSpy with:

-instance "LOCALDB#SH964109"

Heads-up: The token changes every time LocalDB restarts. If SchemaSpy suddenly stops connecting, rerun SqlLocalDB info to grab the updated string.

Step 2: Authentication Options

SQL Server supports two authentication modes, but only one works with LocalDB:

• Windows Integrated (SSO)
  LocalDB uses Windows credentials instead of SQL usernames. The account that runs SchemaSpy must be a Windows user who has been granted access to the database.

  By default, this is the same account that installed or created the LocalDB instance (for example, the Windows user who installed Lansweeper). If you run SchemaSpy as a different user — even another local admin — you may get Login failed for user until that account is explicitly added as a login in SQL Server Management Studio.

  To make NTLM authentication work in Java, you also need ntlmauth.dll from the jTDS package. Without it, SchemaSpy will fail to authenticate even if the Windows account has access.

• SQL Login (username/password)
  This works on full SQL Server or Express, where TCP/IP is enabled and you can create dedicated logins. LocalDB does not allow this mode out of the box, so you can’t rely on -u/-p against a stock LocalDB instance.

Step 3: The Working Command

With SchemaSpy, jTDS, and Graphviz in place, you’re ready to run the actual command. This is where everything comes together.

Important SchemaSpy appends \bin\dot to whatever you provide via -gv. Always pass the Graphviz install root folder, not the path to dot.exe.

Option 1: Windows Integrated Authentication (SSO)

This is the normal way to connect to LocalDB. SchemaSpy will log in as the Windows account you’re running under (make sure that account has database access). You also need ntlmauth.dll and -Djava.library.path.

If you’re running from cmd.exe:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -sso ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

If you’re running from PowerShell:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" `
  -t mssql-jtds-instance `
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" `
  -host . `
  -instance "LOCALDB#SH964109" `
  -db lansweeperdb `
  -s dbo `
  -sso `
  -connprops "namedPipe\=true" `
  -o "C:\bin\SchemaSpy\output" `
  -gv "C:\Program Files (x86)\Graphviz2.38"

Heads-up Use ^ in Command Prompt and ` (backtick) in PowerShell. Mixing them up will cause errors like '-t' is not recognized as an internal or external command.

Option 2: SQL Login (if one exists in LocalDB)

Some applications (like Lansweeper) create a SQL login inside LocalDB (lansweeperuser). If such a login exists, you can use it with -u/-p instead of SSO. The continuation rules are the same as above.

java -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -u lansweeperuser -p "SuperSecret" ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

Note If no SQL login exists in your LocalDB instance, this will fail with Login failed for user. In that case, you must use SSO.

Flag Breakdown

• -t mssql-jtds-instance → use the jTDS SQL Server driver profile.
• -dp → path to the jTDS JAR file.
• -host . + -instance "LOCALDB#..." → connect via the LocalDB named pipe.
• -db lansweeperdb → database name to document.
• -s dbo → schema to include (typically dbo).
• -sso → use Windows integrated authentication.
• -u/-p → alternative, if a SQL login exists.
• -connprops "namedPipe=true" → critical: forces jTDS to use named pipes instead of TCP.
• -gv "<GraphvizRoot>" → Graphviz install root (SchemaSpy appends \bin\dot).
• -o → output directory for the generated site.

What Normal Output Looks Like

SchemaSpy is chatty. A successful run doesn’t just say “Connected” — you’ll see:

• ASCII-art SchemaSpy banner and license text.
• Warnings about restricted methods (expected with jTDS + modern Java).
• A line like:

  INFO  - Connected to Microsoft SQL Server - 16.00.xxxx
  

• Long “Gathering schema details…” progress lines with dots.
• Occasional warnings about sysproperties (safe to ignore — SQL Server 2016+ removed it).
• Graphviz messages about “graph is too large for cairo-renderer” with scaling (also safe).
• A final summary like:

  Wrote relationship details of 1274 tables/views to directory 'C:\bin\SchemaSpy\output'
  View the results by opening C:\bin\SchemaSpy\output\index.html
  

The key thing to look for is that output files get written and you see a final “View the results…” line. Everything else (warnings, scaling errors, missing comments) is normal noise.

The output directory will contain a full HTML site with:

• index.html → overview page
• tables/ → per-table pages
• columns/ → per-column detail pages
• relationships/ → ER diagrams (static images + clickable maps)

Open index.html in your browser to start exploring.

Why This Works

• SchemaSpy 6.1.0 preserves working integration with mssql-jtds-instance.
• jTDS 1.3.3 supports named pipes and Windows SSO (critical for LocalDB).
• -connprops "namedPipe=true" routes through the LocalDB pipe.
• Graphviz 2.38 is the last hassle-free version for SchemaSpy 6.x.
• ntlmauth.dll provides NTLM/SSPI so SSO works from Java.

Troubleshooting Matrix

Even with the right jars and flags, LocalDB is fiddly. Here’s a quick reference for the most common errors and how to resolve them:

Links & Stuff

• SchemaSpy
  📥 SchemaSpy v6.1.0 JAR (GitHub)
  SchemaSpy Documentation

• jTDS JDBC Driver (1.3.3)
  📥 Download jTDS 1.3.3 (SourceForge)
  Archived jTDS project site

• Graphviz (2.38 for Windows)
  📥 Graphviz 2.38 Windows installer (archive)
  Graphviz site & docs

• SQL Server LocalDB
  Microsoft Docs – SQL Server Express LocalDB

• SQL Server Management Studio (SSMS)
  📥 Download SSMS (Microsoft)
  Handy for browsing your LocalDB, verifying database names (e.g. lansweeperdb), and checking which logins exist.

(For long-term use, consider mirroring the required JARs and DLLs internally so your team isn’t chasing archive sites years later.)

Conclusion

LocalDB’s named-pipe-only quirk trips up the usual JDBC approach. The dependable combo is:

SchemaSpy 6.1.0  +  jTDS 1.3.3  +  -connprops "namedPipe=true"  +  Graphviz 2.38

With that in place — and the LocalDB instance pipe refreshed as needed — you’ll get clean, searchable HTML docs and ERDs for any LocalDB-backed app (e.g. Lansweeper, Visual Studio projects).

If you run into an edge case I didn’t cover, send it my way feedback@adminjitsu.com and I’ll expand the troubleshooting matrix.