Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt

Use this file to discover all available pages before exploring further.

​
sqb build

Compiles, plans, and executes the full build lifecycle including seeds, SQL unit tests, model materialization, and audits.

​
Usage

sqb --project-dir <path> build [flags]

​
Flags

FlagDescription
--no-sql-validationSkip compile-time SQL syntax validation
--defer-toResolve unselected model references against another environment
--full-refreshDrop and rebuild all selected models from scratch
--fail-fastStop on first failure and skip remaining nodes
--concurrencyNumber of worker connections (default: 1)
--verbose, -vShow lifecycle SQL inline after each model
--start-cursor-tsOverride start cursor for timestamp incremental models (ISO format)
--end-cursor-tsOverride end cursor for timestamp incremental models (ISO format)
--start-cursor-intOverride start cursor for integer incremental models
--end-cursor-intOverride end cursor for integer incremental models
--select, -sSelect specific models
--excludeExclude specific models

​
Execution order

  1. Seeds are loaded first
  2. Source audits run before their dependent models
  3. SQL unit tests run before their target model
  4. Models are materialized in DAG topological order
  5. Audits run after their attached model completes

​
Output

Execution  sqb build  (concurrency: 1)

   1/13  seed      waffle_types                                          OK     0.09s
   2/13  view      stg_customers                                         OK     0.05s
           audit     not_null (customer_id)                              PASS
           audit     unique (customer_id)                                PASS
   3/13  view      stg_orders                                            OK     0.03s
           test      test_stg_orders                                     PASS
           audit     not_null (order_id)                                 PASS
           audit     unique (order_id)                                   PASS
  10/13  table     hourly_order_activity  (delete_insert)                OK     0.16s
           audit (d) expression_is_true                                  PASS  4/4
           audit (d) not_null (activity_hour)                            PASS  4/4
           audit (f) expression_is_true                                  PASS
           audit (f) not_null (activity_hour)                            PASS

Completed successfully.
PASS=66  WARN=0  FAIL=0  SKIP=0  TOTAL=66  (1.09s)

​
Deferred builds

Use --defer-to to resolve unselected model references against another environment. This lets you build a subset of models in dev while referencing production tables for everything else: 
sqb --project-dir examples/waffle_shop build --select fact_orders --defer-to prod
No manifest.json is required. Deferred references resolve directly against the live environment.

​
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 query fingerprints to _sqlbuild_fingerprints in the target schema. These are used by plan to detect query changes on subsequent runs.

​
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.