Skip to main content

sqb build

Compiles, plans, and executes the selected build lifecycle. Direct mode runs the full selected scope. Virtual environments can additionally use --changes-only to build work not already represented by the target VDE’s bound versions. Use --no-tests and --no-audits to skip validation for fast iteration.

Usage

Flags

Fast iteration

Use --no-tests and --no-audits to skip validation when you only want to materialize models:
This replaces the former sqb run command. The full lifecycle (tests + audits) is always the default; skip flags opt out of specific phases when you need speed.

Execution order

  1. Managed sources are loaded (unless --no-load)
  2. Seeds are loaded (if changed)
  3. Source audits run before their dependent models (unless --no-audits)
  4. SQL unit tests run before their target model (unless --no-tests)
  5. Models are materialized in DAG topological order (virtual --changes-only limits this to stale work)
  6. Error-severity audits run against the staging table before promotion to the target (unless --no-audits)

Output

Deferred builds

Use --defer-to to resolve unselected model references against another target. This lets you build a subset of models in dev while referencing production tables for everything else:
No manifest.json is required. --defer-to selects only the namespace used for unselected references. SQLBuild resolves those relations through the active target’s sole physical connection and never opens the deferred target’s connection. The deferred namespace must be visible and readable through the active connection; deferral is not a cross-account, cross-server, or cross-file transfer mechanism.

Failure behavior

When a model fails:
  • Downstream models are automatically blocked and skipped
  • Staging/delta tables are retained for inspection
  • Failure details show the model name, failed phase, and error message

Fingerprints

After a successful build, SQLBuild writes version identities to _sqlbuild_fingerprints in the target schema. These are used on subsequent runs to detect changes and skip unchanged work. See Planning and Change Detection for details.

Runtime artifacts

Build writes executed lifecycle SQL to target/run/models/. These files contain the actual SQL that was executed, including resolved cursor bounds and runtime substitutions.