1. Michael Bayer
  2. sqlalchemy


Clone wiki

sqlalchemy / UsageRecipes / SchemaDisplay

Schema Display


I wanted to explore automatic documentation generation capabilities of GraphViz and created a small module that traverses SQLAlchemy metadata and mappers and generates images from them. This currently is strictly works-for-me hacky buggy ugly code, but I already got some nifty images out of it. If the idea gathers momentum then maybe a generally useful and robust will come out of this.


You will need atleast SQLAlchemy and pydot along with graphviz for this. Graphviz-cairo is higly recommended to get tolerable image quality. If PIL and an image viewer are available then there are functions to automatically show the image. Some of the stuff, specifically loading list of tables from a database via a mapper and reflecting indexes currently only work on postgres.

But enough talk, lets see some code and screenshots. This is an example of database entity diagram generation:

from sqlalchemy import MetaData
from sqlalchemy_schemadisplay import create_schema_graph

# create the pydot graph object by autoloading all tables via a bound metadata object
graph = create_schema_graph(metadata=MetaData('postgres://user:pwd@host/database'),
   show_datatypes=False, # The image would get nasty big if we'd show the datatypes
   show_indexes=False, # ditto for indexes
   rankdir='LR', # From left to right (instead of top to bottom)
   concentrate=False # Don't try to join the relation lines together
graph.write_png('dbschema.png') # write out the file

This produces:


And an UML class diagram from a model:

from myapp import model
from sqlalchemy_schemadisplay import create_uml_graph
from sqlalchemy.orm import class_mapper

# lets find all the mappers in our model
mappers = []
for attr in dir(model):
    if attr[0] == '_': continue
        cls = getattr(model, attr)

# pass them to the function and set some formatting options
graph = create_uml_graph(mappers,
    show_operations=False, # not necessary in this case
    show_multiplicity_one=False # some people like to see the ones, some don't
graph.write_png('schema.png') # write out the file

This produces: schema.png


As a python package

Further development on GitHub


  • More output customization options
  • A way to get comments and relation labels from the schema to the diagram
  • Improve SQLAlchemy reflection support
  • In UML show relations not on the current graph as properties.
  • Better documentation