Clone wiki

sqlalchemy / UsageRecipes / SchemaDisplay

Schema Display

Introduction

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.

Usage

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:

dbschema.png

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
    try:
        cls = getattr(model, attr)
        mappers.append(class_mapper(cls))
    except:
        pass

# 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

Files:

As a python package

Further development on GitHub

Todo

  • 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

Updated