I have released sqlalchemy-annotate, a small command-line tool that keeps a schema summary at the top of every SQLAlchemy model file.

When you read a SQLAlchemy model, the Python tells you which attributes exist but not what the database does with them. Whether a column is nullable, how long a string can be, which columns are indexed, what the foreign keys point at - none of that is visible in the model. You have to open the migration or connect to the database to find out. Rails has addressed this for years with annotate_models. This tool brings the same idea to modern SQLAlchemy 2.x and Alembic projects.

It maintains a block like this, kept in sync with your actual metadata:

# == Schema Information
#
# Table name: users
#
# id         : integer, primary key
# email      : varchar, not null
# created_at : timestamp
#
# Indexes
#   ix_users_email (email) UNIQUE
#
# == End Schema Information

There are three commands. sqlalchemy-annotate generate writes or updates the block, typically run after a migration. sqlalchemy-annotate check exits non-zero when a model has drifted from its comment, which makes it suitable as a CI gate or pre-commit hook. sqlalchemy-annotate remove strips every block.

Two design decisions are worth stating directly.

First, it never connects to a database. The schema is read from Base.metadata. If you pass a connection URL, only its dialect is used, so types compile correctly offline, and the URL is then discarded. Annotating a file does not require database credentials.

Second, it does not rewrite files with regular expressions. All edits go through a single libcst transformer, so imports, comments, blank lines and formatting outside the marked block are preserved exactly. Running generate twice produces no further change, which is what makes check reliable.

One trade-off should be clear before you adopt it. The tool imports your model package, in the same way pytest and Alembic do. If importing your models triggers side effects, those will run. For most projects this is not an issue, but it is worth knowing.

Installation is from PyPI:

pip install sqlalchemy-annotate

The source, full documentation and configuration options are at github.com/abhinavs/sqlalchemy-annotate. The tool is intentionally small. The schema already exists in your metadata; this simply puts it where the person reading the model can see it.