abhinavs/sqlalchemy-annotate

sqlalchemy-annotate is a small command-line tool for Python projects that use SQLAlchemy 2.x and Alembic. Its job is to keep a Schema Information comment block at the top of each model file, summarizing the underlying database table. The block lists columns with their types and nullability, indexes, and foreign keys, so anyone reading a model file in a pull request or editor can see the table shape without opening a database client or hunting through migration scripts. The idea is borrowed from the Rails annotate_models gem, adapted for the modern SQLAlchemy world. A key promise of the tool is safety. It never connects to a real database. It reads everything from SQLAlchemy's own Base.metadata and __table__ attributes. If you pass a connection URL, it is parsed only to pick the SQL dialect so that column types render the way that backend would compile them. File rewriting is done through a single libcst transformer rather than regex, which means imports, blank lines, comments, and existing Black formatting are kept byte-for-byte; only the region between the start and end markers is changed. Running the generate command twice in a row produces no diff, which is what makes the matching check command reliable as a CI gate or pre-commit hook. You install it with pip or uv, then run sqlalchemy-annotate generate to write or refresh the blocks. Other commands include check (exits with a non-zero status if any file is stale), remove (strips all blocks), and a --dry-run flag that prints the diff without writing. The --models option points at a Python package such as app.models, and subpackages are imported recursively. Broken modules are reported as warnings and skipped, not treated as fatal. Defaults can be set in pyproject.toml under a [tool.sqlalchemy-annotate] section, with options to include or exclude indexes, foreign keys, and relationships, sort columns by definition order or alphabetically, normalize types into Rails-style names like bigint and varchar(255), and exclude tables by glob pattern. The README sketches the internal layout (discovery, schema, formatter, parser, writer, config, cli modules) and a roadmap of designed-but-not-built features such as Markdown schema export, ER diagrams, a schema diff command, watch mode, and a VSCode integration. The package ships with PEP 561 type information and is MIT licensed.