legrandlegrand / revj2 Goto Github PK

Installation
============
Install Graphviz (tested with ver 2.38 and 2.43)
Install Python (tested with ver 3.8 and 3.9)

Self-tests
==========
python revj.py

Note that some tests may fail in order to document bugs/future work. They are documented as "known bug"


Running on Unix
===============
gvpr minds about the line endings in the dir.g file. 


GUI
===
There is a very simple interface that displays a welcome message if everything was installed correctly. If not, check that Graphviz is installed, ex: dot is in the PATH, and if there is pyparsing.py in PYTHONPATH.

Paste the SQL in the upper text entry, select the diagram generation algorith (or leave the default "fdp"), and press "Generate diagram". If edges are cluttered, increase the "distance" parameter. In case there are any problems due to the dir.g script, please use the "one-pass" algorithm, or use the command line. 

The generated diagram is in the file "current.gif". You can also edit "current.dot" and run "dot" on top of it

To run the tool:

python gui.py



Bugs and Limitations
====================
Please qualify columns with aliases. Instead of "select a from table" use "select t.a from table t". This is trivial to fix for one table, however in general it does require access to the database. Instead of "Select name, id, dep_name from person inner join department..." use ""Select p.name, p.id, d.dep_name from person p inner join department d .."


Generating a diagram from standard input
========================================
Command line parameter '-' will cause text to be read from standard input.
Iy you paste directly text, end input with ^D (^Z on Windows)

python revj.py -



Generating a diagram from file
==============================
Specify filename on commandline:

python revj.py sample.sql | dot -Grankdir=LR -Edir=none -T png -o current.png



Getting nicer output from Graphviz
==================================
Emden R. Gansner suggested to generate a graph, parse it and generate a new, directed graph which looks much better

python revj.py - | fdp | gvpr -fdir.g | dot -Grankdir=LR -Edir=none -T png -o current.png


You might want to try several layout algorithms, since the graph layout varies wildly. Usually neato and fdp looks the best and are reliable.

python revj.py vesel.sql | neato | .....
python revj.py vesel.sql | circo | ...
python revj.py vesel.sql | dot | ...
python revj.py vesel.sql | fdp | ...
python revj.py vesel.sql | twopi | ...


Credits:
========
Emden R. Gansner and his colleagues at AT&T Research
Paul McGuire for developing PyParsing and code reviews
Pascal Lemoy for submitting lots of SQL fragments with bugs