About

Welcome to the GraphDoc wiki!

I wrote GraphDoc very quickly during a short contract where I needed to look at a system with set of SqlServer databases that had no documentation at all; no external documents, and barely any comments in the code. The developers who had worked on this system were gone with no handover of any knowledge. Many of the procedures were huge - several thousand lines of code - and were reading and writing to other databases, often on remote servers, as well as locally. Several of the databases had recently been migrated to new kit and upgraded to SqlServer 2017 from 2012 and 2014 and there were major upcoming jobs that ran annually that had not yet been migrated on to the new servers. My brief was to establish that everything would run satisfactorily at the right time, and to document the overall architecture with a view that the organisation was going to replace the system in the next year. Migrating to the new servers went fine but I didn't have time or the inclination to pore over all this code manually.

It needed to be detailed enough that the eventual developers of the replacement system could get a clear picture on what was going on. I used the excellent SchemaSpy to document the database structures. Untangling the code was trickier. I looked around for tools (of the free or very cheap variety) but didn't really find much. I tried a not-free product that produced overviews of the code with a mixture of diagrams and annotated code, but as most procedures were ridiculously large the result was less than readable. Its scope was the local database only unless I ponied up for the fancy version which wasn't going to happen, so all the non-local references became grey boxes. Furthermore it was a monthly payment for the licence and I don't suppose my employer would have been too happy with me leaving them with a requirement to pay a licence fee for some mystery product I'd happened to use.

So, I figured I'd better come up with something myself. I wanted a pictorial view of these huge stored procedures that would hopefully be easy enough for a developer to read and get a quick understanding of what was going on. I'd used Graphviz in an earlier project and figured that would be a good tool to do the drawing.

This system also had loads of SqlServer agent jobs to call these procedures where there was significant logic embedded in the sql command of the the steps within the job. This is not something I would expect to see ordinarily but there it was. So my other requirement was to document these jobs graphically too.