Use mermaid for migrations graph

[AArnott]

The migrations ASCII art previously used was somewhat hard to read and much harder to maintain over time. Mermaid markdown provides a very easy way to add new nodes to the graph, and the result is far more visually parseable.

Mermaid can be rendered on GitHub or via a local extension such as in VS Code. I've added an extension recommendation for VS Code as part of this change.

Here is what it looks like in VS Code:

And right here in the PR, github will render the graphic with the click of a button on the introduced file.

[AArnott]

Other ideas I have for improving on this is to make it more clear which nodes I need to derive on when I change a particular database entity. So maybe elsewhere in the new markdown file, a list of each db entity (e.g. table, view, index) with a sub-list of each migration that impacted it, and a description of what the migration did to it. That way if I need to change an entity, I can quickly find the list of dependencies I'll need. Then by referring to the graph, I can weed out the redundant dependencies.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (3cbc481) 65.03% compared to head (86543dc) 65.02%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1186      +/-   ##
==========================================
- Coverage   65.03%   65.02%   -0.01%     
==========================================
  Files         114      114              
  Lines       11108    11108              
==========================================
- Hits         7224     7223       -1     
- Misses       3884     3885       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[nuttycom]

Can mermaid render to a textual DAG? I find it really helpful to have the graph in migrations.rs, but I would not at all object to doing the rendering with a tool and then copy/pasting in the result.

[AArnott]

@nuttycom: Copilot says no.

Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions to create and modify complex diagrams². However, it does not inherently support rendering to a textual Directed Acyclic Graph (DAG). Mermaid's primary function is to render graphical representations of diagrams based on the provided textual input².

If you want to convert a Mermaid diagram to a textual DAG, you would need to implement a custom solution. This could involve parsing the Mermaid syntax and converting it into a textual representation of a DAG. Please note that this would require a good understanding of both the Mermaid syntax and the desired textual format for the DAG.

If you're looking for a tool that can generate textual DAGs, you might want to consider other libraries or tools that are designed for this purpose. Always choose the tool that best fits your specific needs.

(1) GitHub - mermaid-js/mermaid: Generation of diagrams like flowcharts or .... https://github.com/mermaid-js/mermaid.
(2) How to render a mermaid flowchart dynamically? - Stack Overflow. https://stackoverflow.com/questions/65212332/how-to-render-a-mermaid-flowchart-dynamically.
(3) Include diagrams in your Markdown files with Mermaid. https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/.
(4) undefined. https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js.

[daira]

Here's the mermaid-js feature request: mermaidjs/mermaid-live-editor#36
Doesn't seem to be any active work on it.

[AArnott]

I'd rather see only the .md file. But given @nuttycom prefers the ascii approach, what if I modify the PR to retain the ASCII graphic and simply add the .md file? That way folks who prefer to refer the image can do so, at the cost of maintaining two sources of truth, although the .md file is much easier to maintain than the .rs comments, so it doesn't add a lot of effort to have to add maintenance of the .md file.