I love the diagrams from the SQLite documentation: https://www.sqlite.org/syntaxdiagrams.html

SQLite diagrams plus examples are pretty much the way I wish all of my documentation worked.

I've been bitten by those before because they are not generated from the actual syntax-parsing code, and thus are sometimes out of sync and wrong (or at least misleading).

Those are commonly called “railroad diagrams”: <https://en.wikipedia.org/w/index.php?title=Syntax_diagram&ol...>

Sometimes I find it annoying but mostly it works well for me. I've come to embrace the find feature and visually scanning over any parenthetical stuff.

The alternative is they have to break it up into several quasi examples, each with their own optional modifiers.

FWIW square brackets indicate an optional parameter and the pipe inside indicates all the parameters available; but I agree, I don't particularly care for that notation and prefer actual running SQL examples.

Railroad-esque diagrams can be weird but they say a lot in a very short space, I would highly recommend spending a little extra time working on thinking through them, they are everywhere!

>Railroad-esque diagrams

Now and forever I will think of railroads when I see these.

Well, you should! But, I didn't invent anything there, that's what they are named :)

Syntax diagrams (or railroad diagrams) are a way to represent a context-free grammar. They represent a graphical alternative to Backus–Naur form, EBNF, Augmented Backus–Naur form, and other text-based grammars as metalanguages... https://en.wikipedia.org/wiki/Syntax_diagram

I'm looking at the postgres docs now, and they certainly have the arcane formal syntax definitions, but they also have plenty of useful examples https://www.postgresql.org/docs/current/sql-altertable.html#...

PostgreSQL Administration Cookbook series served me well

https://www.oreilly.com/library/view/postgresql-16-administr...

For real-world SQL examples and generating queries fast, you might like https://ai2sql.io/ . It's an AI-based tool that lets you enter natural language prompts and outputs efficient SQL code tailored to your needs.