dbt-treesitter.nvim

An experimental Neovim 0.12+ integration for structurally highlighting dbt files with a template-aware SQL parser.

Phase 1 changed the design from the initial prototype:

Neovim filetype: dbt
root parser:      dbt_sql (SQL grammar with Jinja template holes)

grammar/dbt_sql is based on DerekStride's MIT-licensed tree-sitter-sql (see grammar/dbt_sql/README.md for the pinned upstream revision). It adds opaque jinja_output, jinja_statement, and jinja_comment tokens: statements/comments are SQL extras, outputs are accepted in expression, relation, object-reference, and select-list positions.

The old Jinja-root/SQL-injection prototype is kept as dbt_injected queries so ./scripts/test can compare both approaches on the same corpora.

Why start here?

A stock SQL parser does not expose reliable Jinja nodes for injection. A Jinja root parser reliably separates template control flow and literal output. The risk is that SQL receives discontinuous ranges and invalid holes where Jinja expressions occur. The corpus tests are intended to measure that risk before we commit to a composite grammar.

Development setup

Requirements:

• Neovim 0.12+
• tree-sitter CLI
• a C compiler
• Git

Build the composite parser (regenerates and compiles parser/dbt_sql.so):

nvim -l build.lua

With lazy.nvim:

{
  "local/dbt-treesitter.nvim",
  dir = vim.fn.expand("~/dbt-treesitter.nvim"),
  dependencies = { "geigerzaehler/tree-sitter-jinja2" },
  config = function()
    require("tree-sitter-jinja2").setup()
    require("dbt-treesitter").setup()
  end,
}

Fetch the pinned external corpora and print their basic statistics:

./scripts/fetch-corpora
./scripts/corpus-stats
./scripts/test

Current status

• Detects .sql files below a directory containing dbt_project.yml as dbt.
• Parses dbt buffers with the composite dbt_sql parser (Jinja holes).
• Highlights Jinja tokens; SQL highlighting is inherited from the SQL queries.
• Keeps the Jinja-root prototype available as dbt_injected for comparison.
• Has a pinned, ignored corpus rather than vendoring third-party repositories.
• Does not claim correct SQL trees across Jinja branches, loops, or macro expansions. See docs/PHASE2.md for the known limitation and blocker.

See docs/PLAN.md for milestones and exit criteria.