Introduction

xSchema is a command-line SQL Server schema extraction tool written in Python. It connects to a SQL Server database and produces a comprehensive, human-readable Markdown document describing every aspect of the schema — tables, columns, keys, indexes, views, stored procedures, functions, sequences, and user-defined types.

The output is designed to be fed directly into AI assistants, used as living project documentation, or committed to version control alongside your codebase.

Requirements

Install the dependency

pip install pyodbc

ODBC Driver

A SQL Server ODBC driver must be installed on your system. xSchema automatically selects the newest available driver. The recommended driver is ODBC Driver 17 for SQL Server or later.

Quick Start

Step 1 — Set your connection details

Open xSchema.py and edit the configuration block near the top:

SERVER      = "192.168.0.1"   # Your SQL Server IP or hostname
PORT        = 1433              # Default SQL Server port
DATABASE    = "sqlserver"          # Target database name
USERNAME    = "me"              # SQL Server login
PASSWORD    = "letmein"                # SQL Server password
OUTPUT_FILE = "schema.md"       # Output filename (or None for auto)

Step 2 — Run the script

python xSchema.py

Step 3 — Find your output

The schema file (schema.md by default) is written to the same directory as the script. xSchema prints progress messages as it connects, queries, and writes, finishing with the file size in bytes.

Connection Settings

All connection parameters live in the configuration block at the top of xSchema.py. There is no external config file — this is intentional for simplicity.

Certificate Trust

The connection string includes TrustServerCertificate=yes, bypassing SSL certificate validation. Appropriate for local/internal servers — remove for production connections with a trusted certificate.

Windows Authentication

To use Windows auth instead of SQL auth, replace the UID/PWD portion in build_connection_string() with Trusted_Connection=yes; and remove the USERNAME/PASSWORD variables.

CLI Arguments

xSchema accepts optional flags to control output content. All are opt-in; the defaults produce the most focused result.

Output File

xSchema writes a single UTF-8 Markdown (.md) file, readable in any Markdown renderer including GitHub, VS Code, Obsidian, and AI chat tools.

Document Structure

Output File Naming

Usage Examples

Basic extraction — tables with data only

python xSchema.py

Include stored procedures and views

python xSchema.py --sprocs --views

Only tables with 100+ rows, include stored procedures

python xSchema.py --minrecords 100 --sprocs

Include all tables regardless of row count

python xSchema.py --minrecords 0 --sprocs --views

Auto-name the output file

Set OUTPUT_FILE = None in the script. The file will be written as schema.md.

Schema Output — What's Captured

For each table, xSchema extracts the following detail:

Architecture

xSchema is a single-file Python script with a clear layered structure. Each layer has a single responsibility.

TOC Injection Mechanism

During document assembly a placeholder comment <!-- TOC --> is inserted at the table of contents position. TOC entries are accumulated as each section is built, then joined and substituted in a single string replacement — avoiding any two-pass build logic.

ODBC Driver Selection

build_connection_string() calls pyodbc.drivers(), filters for entries containing "SQL Server", sorts alphabetically, and picks the last — effectively the highest version number installed. No manual driver configuration is required.

Function Reference

CLI & Connection

Schema Extractors

Markdown Formatters

Core Builder & Entry Point

Extending xSchema

Adding a New Schema Object Type

The pattern is consistent throughout. To add synonyms, for example:

1. Add an extractor function:

def get_synonyms(cursor):
    return q(cursor, """
        SELECT s.name, sc.name AS schema_name,
               s.base_object_name
        FROM sys.synonyms s
        JOIN sys.schemas sc ON s.schema_id = sc.schema_id
        ORDER BY sc.name, s.name
    """)

2. Call it inside build_markdown():

synonyms = get_synonyms(cursor)
if synonyms:
    lines.append(md_h2("Synonyms"))
    toc_entries.append("- [Synonyms](#synonyms)")
    lines.append(md_table(
        ["Schema", "Name", "Base Object"],
        [(r.schema_name, r.name, r.base_object_name) for r in synonyms]
    ))

Adding a New CLI Flag

Add the argument in parse_args(), then gate the relevant section in build_markdown() with if args.your_flag:, following the same pattern as --sprocs and --views.

Troubleshooting