What is merlin-dbt?

merlin is a command-line tool that reads your dbt project's manifest file and produces Mermaid flowchart diagrams showing how your data models are connected. dbt (data build tool) is a popular tool used by data engineers to transform data in warehouses, it creates a manifest.json file that describes all the models, sources, and relationships in a project. Mermaid is a text-based diagram format that GitHub, many documentation tools, and AI assistants can render as visual flowcharts. You run merlin by naming a model and choosing how much of its data lineage (the chain of upstream and downstream dependencies) to include. The pattern +my_model+ shows the model plus everything that feeds into it and everything that depends on it, +my_model shows only upstream ancestors, my_model+ shows only downstream descendants, and my_model alone gives just that one model. Traversal stops at source nodes, which are treated as roots with no further ancestors. The output uses different shapes to distinguish models (rectangles), sources (stadium shapes), seeds, and snapshots (both hexagons), so you can see at a glance what type each node is. The typical use is to pipe the diagram output into a GitHub pull request description so reviewers can immediately see what data dependencies a change affects. A GitHub Actions example in the README shows how to automate this. You can also use the --raw flag to get plain Mermaid syntax for scripting. Requirements are Python 3.10 or later and a dbt project with a current manifest.json generated by running dbt compile. The tool supports dbt Core 1.0 and later.