Show SQL DDL

This recipe demonstrates how to include the SQL CREATE TABLE statement in your documentation.

Configuration

In your mkdocs.yml:

plugins:
  - sqlalchemy:
      base_class: "show_sql.models.Base"
      app_path: "src"
      display:
        show_sql: true

Usage

In your markdown file:

# MkDocs SqlAlchemy Plugin

{% sqlalchemy %}

Each table documentation will include a collapsible section with the SQL DDL.

---

Result

Table: posts

column	type	nullable	default	primary_key	unique	foreign_key
id	INTEGER	❌		✔️	❌
title	VARCHAR(200)	❌		❌	❌
content	TEXT	✔️		❌	❌
is_published	BOOLEAN	✔️	False	❌	❌
user_id	INTEGER	✔️		❌	❌	users.id
created_at	DATETIME	✔️	utcnow	❌	❌
updated_at	DATETIME	✔️	utcnow	❌	❌

View SQL

CREATE TABLE posts (
    id SERIAL NOT NULL, 
    title VARCHAR(200) NOT NULL, 
    content TEXT, 
    is_published BOOLEAN, 
    user_id INTEGER, 
    created_at TIMESTAMP WITHOUT TIME ZONE, 
    updated_at TIMESTAMP WITHOUT TIME ZONE, 
    CONSTRAINT pk_posts PRIMARY KEY (id), 
    CONSTRAINT fk_posts_user_id_users FOREIGN KEY(user_id) REFERENCES users (id)
)

Indexes:

• ix_posts_updated_at: updated_at

Constraints:

• fk_posts_user_id_users (ForeignKeyConstraint)
• pk_posts (PrimaryKeyConstraint)

Table: user_profiles

column	type	nullable	default	primary_key	unique	foreign_key
id	INTEGER	❌		✔️	❌
user_id	INTEGER	✔️		❌	✔️	users.id
first_name	VARCHAR(50)	✔️		❌	❌
last_name	VARCHAR(50)	✔️		❌	❌
bio	TEXT	✔️		❌	❌

View SQL

CREATE TABLE user_profiles (
    id SERIAL NOT NULL, 
    user_id INTEGER, 
    first_name VARCHAR(50), 
    last_name VARCHAR(50), 
    bio TEXT, 
    CONSTRAINT pk_user_profiles PRIMARY KEY (id), 
    CONSTRAINT uq_user_profiles_user_id UNIQUE (user_id), 
    CONSTRAINT fk_user_profiles_user_id_users FOREIGN KEY(user_id) REFERENCES users (id)
)

Indexes: None

Constraints:

• uq_user_profiles_user_id (UniqueConstraint)
• pk_user_profiles (PrimaryKeyConstraint)
• fk_user_profiles_user_id_users (ForeignKeyConstraint)

Table: users

column	type	nullable	default	primary_key	unique	foreign_key
id	INTEGER	❌		✔️	❌
username	VARCHAR(50)	❌		❌	✔️
email	VARCHAR(120)	❌		❌	✔️
is_active	BOOLEAN	✔️	True	❌	❌
created_at	DATETIME	✔️	utcnow	❌	❌

View SQL

CREATE TABLE users (
    id SERIAL NOT NULL, 
    username VARCHAR(50) NOT NULL, 
    email VARCHAR(120) NOT NULL, 
    is_active BOOLEAN, 
    created_at TIMESTAMP WITHOUT TIME ZONE, 
    CONSTRAINT pk_users PRIMARY KEY (id), 
    CONSTRAINT uq_users_username UNIQUE (username), 
    CONSTRAINT uq_users_email UNIQUE (email)
)

Indexes: None

Constraints:

• uq_users_username (UniqueConstraint)
• pk_users (PrimaryKeyConstraint)
• uq_users_email (UniqueConstraint)