Rust Workspace Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• Cargo.toml
• README.md
• crates/dbt-main/Cargo.toml
• crates/dbt-docs-server/README.md
• crates/dbt-ci/README.md
• crates/dbt-parser/src/resolver.rs
• crates/dbt-ci/src/utils.rs

The dbt-core repository transition from v1 to v2 represents a ground-up rewrite in Rust, designed to power the Fusion engine. This architecture is structured as a Cargo workspace containing numerous specialized crates that handle distinct aspects of the dbt lifecycle, including parsing, compilation, execution, and documentation. The workspace is engineered for high performance at scale, utilizing a tightly-defined language specification and producing analytical artifacts in Parquet format.

Sources: README.md:6-14, Cargo.toml:4-10

Workspace Structure and Dependency Management

The project uses a standard Cargo workspace to manage a large number of internal crates. Global configurations for authors, edition, license, and version are defined at the workspace level and inherited by member crates using the workspace = true syntax.

Key Workspace Members

The workspace is divided into several functional categories:

• Core Logic: Crates like dbt-common, dbt-parser, dbt-compilation, and dbt-dag.
• Adapters: Implementation-specific logic for different databases (e.g., dbt-adapter-sql, dbt-lexer-snowflake).
• Infrastructure: Tools for CI/CD (dbt-ci), macros (proto-rust-macros), and telemetry (dbt-telemetry).
• Documentation: The next-generation docs experience via dbt-docs-server and dbt-docs-core.

Sources: Cargo.toml:4-105, crates/dbt-main/Cargo.toml:21-46

Dependency Inheritance

The workspace utilizes a centralized [workspace.dependencies] section to ensure version consistency across all crates. This includes both external crates (like tokio, serde, and arrow) and internal path-based dependencies.

Category	Examples	Purpose
Data Formats	arrow, parquet, serde_json	High-performance data handling and serialization.
Async Runtime	tokio, futures	Powering concurrent execution and I/O.
Web/API	axum, reqwest, tower	Powering the docs server and API communications.
Internal Path	dbt-adapter, dbt-parser	Cross-crate functionality within the mono-repo.

Sources: Cargo.toml:193-455

Component Architecture

The system is designed as a pipeline where data flows from project source files through a resolver into a manifest, and eventually into execution or documentation artifacts.

The Parsing and Resolution Pipeline

The dbt-parser crate serves as the entry point for the resolve phase. It processes models, seeds, tests, and macros to produce a ResolverState and a JinjaEnv.

The resolution process handles complex logic such as macro patching, dependency extraction, and relation uniqueness checks.
Sources: crates/dbt-parser/src/resolver.rs:88-160, crates/dbt-parser/src/resolver.rs:260-310

Documentation Server Architecture

dbt-docs-server is a stateless, read-only HTTP server built with axum. It serves as the successor to the v1 docs generate/serve workflow.

The server is self-contained; the React SPA is baked into the binary via the embed-ui feature.
Sources: crates/dbt-docs-server/README.md:18-35, crates/dbt-docs-server/Cargo.toml:15-20

Build and Release Infrastructure (dbt-ci)

The dbt-ci crate provides specialized commands for managing the Rust workspace release lifecycle. It handles version bumping, Python wheel packaging, and Homebrew formula rendering.

CI Utility Logic

The workspace root is dynamically discovered by searching for the nearest ancestor containing a [workspace] table in its Cargo.toml.

pub(crate) fn cargo_workspace_root() -> PathBuf {
    // Searches ancestors for Cargo.toml with [workspace]
    // Falls back to current directory if not found
}

Sources: crates/dbt-ci/src/utils.rs:36-55

Distribution Lifecycle

The CI tools support a multi-platform distribution strategy:

1. Version Management: bump-cargo-version updates the workspace-level version.
2. Packaging: pypi pack converts pre-built binaries into platform-specific Python wheels.
3. Publication: Supports AWS CodeArtifact, PyPI, and TestPyPI environments.
4. Installation Metadata: homebrew render generates Ruby formulas for macOS and Linux distribution.

Sources: crates/dbt-ci/README.md:5-25, crates/dbt-ci/src/publish.rs:45-75

Conclusion

The Rust Workspace Architecture in dbt-core v2.0 represents a significant shift toward a modular, high-performance monorepo. By leveraging Cargo's workspace features for dependency management and Rust's safety for complex parsing logic, the system provides a robust foundation for the Fusion engine. The architecture ensures that components like the dbt-docs-server can operate independently while remaining part of a unified, self-contained binary distribution.

Sources: README.md:18-30, Cargo.toml:4-10