Crate sql_docs 

Sql File Comment and Statement Parsing for Documentation

This crate extracts documentation from SQL files by parsing:

• SQL statements (via sqlparser)
• Line and block comments
• Table and column locations

Then comments are attached to the SQL structures they describe, producing a structured, queryable documentation model.

Example

With a directory structured like this:

sql_dir/
└── users.sql

and the content of users.sql being:

/* Table storing user accounts */
CREATE TABLE users (
    /* Primary key for each user */
    id INTEGER PRIMARY KEY,
    -- The user's login name
    username VARCHAR(255) NOT NULL,
    /* User's email address */
    email VARCHAR(255) UNIQUE NOT NULL
);

A rudimentary implementation can be generated with:

use sql_docs::SqlDoc;
use sql_docs::error::DocError;
use std::{env, fs};

fn main() -> Result<(), DocError> {
    // Temporary directory and file created for demonstration purposes
    let base = env::temp_dir().join("tmp_dir");
    let _ = fs::remove_dir_all(&base);
    fs::create_dir_all(&base)?;
    let example = base.join("example.sql");

    fs::write(
        &example,
        r#"-- Table storing user accounts
-- Contains all user values
/* Rows generated at registration */
CREATE TABLE users (
    /* Primary key for each user */
    id INTEGER PRIMARY KEY,
    -- The user's login name
    username VARCHAR(255) NOT NULL,
    /* User's email address */
    email VARCHAR(255) UNIQUE NOT NULL
);"#,
    )?;

    // Extract documentation from a single file
    let docs = SqlDoc::from_path(&example)
        // Capture all valid comment lines preceding the statements directly
        .collect_all_leading()
        // Replace `\n` with a `str`
        .flatten_multiline_with(". ")
        // Finally build the `SqlDoc`
        .build()?;
    // Or extract recursively from a directory
    // let docs = SqlDoc::from_dir(&base).build()?;

    // Retrieve a specific table
    let users = docs.table("users", None)?;

    // Table name
    assert_eq!(users.name(), "users");
    // Optional table-level documentation
    assert_eq!(users.doc(), Some("Table storing user accounts. Contains all user values. Rows generated at registration"));
    // Path to the source file
    assert_eq!(users.path(), Some(example.as_ref()));

    let _ = fs::remove_dir_all(&base);
    Ok(())
}

Primary Interface (Main API)

These are the primary entry points most users will interact with:

• SqlDoc::from_path Build documentation from a single .sql file.
• SqlDoc::from_dir Recursively scan a directory for .sql files and build documentation.
• SqlDocBuilder::build Finalize the builder and produce a SqlDoc.
• SqlDocBuilder::deny Exclude specific files by full path.
• SqlDocBuilder::flatten_multiline Flatten multiline comments into a single line.
• SqlDocBuilder::collect_single_nearest Collect only the nearest leading comment.

Use Cases

This crate is designed for generating documentation from SQL schemas by attaching comments to:

• Tables
• Columns

using only comments that immediately precede the items they describe, with the ability to differentiate between multiple leading comments per statement or collect only the nearest comment preceding a statement.

This makes it well-suited for:

• Auto-generating Markdown or HTML documentation
• Building database schema explorers
• Enforcing documentation rules in CI
• Static analysis of SQL schemas

Design Notes

• Inline and interstitial comments are intentionally ignored.
• Comment attachment is line-based and deterministic.
• One SQL file may define multiple tables.
• No database connection is required.
• sql_doc items are sorted by table name and column name, supporting binary searching

Module layout

• files — Discover and load .sql files from disk
• ast — Parse SQL into an AST using sqlparser
• comments — Extract and model SQL comments and spans
• docs — Generate structured documentation (TableDoc, ColumnDoc)
• sql_doc — Build the top-level SqlDoc and primary entry point

Start here: SqlDoc::from_dir or SqlDoc::from_path

Re-exports

pub use sql_doc::SqlDoc;

Modules

ast

Parse SQL text into an AST (sqlparser) for downstream comment attachment.

comments

Extract comment spans from parsed SQL files.

docs

Convert parsed SQL + extracted comments into structured documentation types.

error

Error types returned by this crate’s public APIs.

files

Discover and filter .sql files on disk.

source

Module for structuring the Sql input

sql_doc

Public entry point for building SqlDoc from a directory, file, or string.