dbt Version Compatibility

Tested Versions

Docglow has been tested with the following dbt versions:

dbt-core Version	Manifest Schema	Status
1.8.x	v12	Tested
1.9.x	v12	Tested
1.11.x	v12	Tested

Test fixtures for each version are located in tests/fixtures/dbt-{version}/ and validated by parameterized tests in tests/test_dbt_versions.py.

Minimum Version

The minimum tested version is dbt-core 1.8.x. Docglow reads standard dbt artifacts (manifest.json, catalog.json, run_results.json). The Pydantic models use extra="allow" for forward compatibility with newer schema versions, so newer dbt releases are expected to work without code changes.

If you encounter issues with a different dbt version, please open an issue.

Adapter Compatibility

Docglow is adapter-agnostic — it reads compiled dbt artifacts, not database connections directly. Any adapter that produces standard manifest.json and catalog.json files should work:

• DuckDB
• PostgreSQL
• Snowflake
• BigQuery
• Redshift
• Databricks
• Spark
• Trino
• ClickHouse
• Athena (Presto)
• SQL Server (TSQL)
• Fabric (TSQL)
• Oracle
• Starburst (Trino)

The optional column profiling feature (docglow[profiling]) currently supports DuckDB, PostgreSQL, and Snowflake adapters.

Column Lineage

Column-level lineage is enabled by default and uses sqlglot to parse SQL and trace column dependencies. It works best with compiled SQL — run dbt compile before docglow generate for best results.

To disable column lineage, use --skip-column-lineage on the CLI or set column_lineage: false in your docglow.yml. For large projects (75+ models), Docglow prints a time estimate and suggests using --column-lineage-select <model> to scope the analysis.

What works well

• Standard SQL: SELECT, JOIN, CTEs, subqueries, UNION, window functions
• Snowflake dialect: variant access (metadata:key::type), QUALIFY, IFF
• Common dbt macros: dbt_utils.surrogate_key, dbt_utils.star, dbt.date_trunc, dbt.safe_cast, type helpers, and more (12 macros expanded automatically)
• Models with SELECT * FROM <cte> — columns are resolved from the CTE definition even without catalog data
• Dynamic Tables and other models without compiled SQL fall back to Jinja-stripped raw SQL

Known limitations

• Complex Jinja macros: Custom macros and dbt_utils.pivot() are replaced with NULL if compiled SQL is unavailable. The column lineage for those expressions is lost.
• Deeply nested CTEs: sqlglot's lineage tracer has a 2-second timeout per column. Very complex SQL with many nested CTEs may time out on some columns.
• Adapter-specific functions: While Snowflake is well-supported, some adapter-specific SQL functions may not parse correctly in other dialects.

Recommendations

1. Run dbt compile before generating — compiled SQL has all macros resolved
2. Use --column-lineage-select <model> to analyze incrementally — results cache across runs
3. Use --skip-column-lineage or column_lineage: false in docglow.yml to disable entirely
4. Check .docglow-column-lineage-failures.log for details on models that couldn't be fully analyzed

Optional Artifacts

Artifact	Required	Notes
manifest.json	Yes	Generated by dbt compile, dbt run, or dbt build
catalog.json	No	Generated by dbt docs generate. Without it, column types are unavailable.
run_results.json	No	Generated by dbt run, dbt test, or dbt build. Without it, test statuses show as unknown.
sources.json	No	Generated by dbt source freshness. Without it, freshness data is unavailable.