SQLite Railroad Diagrams

Originally shared on Twitter in Jul. 2022.

Programming languages (including SQL) are generally defined in terms of formal grammars. Often this gets documented using formal grammar notion syntaxes like Backus–Naur form. For example, here is how Postgres documents their syntax:

While SQLite does uses a syntax like that internally, for the purposes of their documentation, they generate these delightful “Railroad Diagrams” that work more like little choose your own adventure flow charts. I personally find them very intuitive to read, despite having spent quite a bit of time thinking about formal grammars and being relatively fluent in the various metasyntaxes.

Like many things the SQLite folks do, they actually created their own declarative language Pikchr for defining diagrams which get embedded in documentation. I believe this is what’s used to generate these railroad diagrams. Note that the tool’s site is hosted using Fossil which is their all in one source control/website tool which they also hand rolled and is powered by (you guessed it) SQLite. At this point you’ll be unsurprised to learn that Fossil includes a hand rolled HTTP stack.