Virtual environments preserve StreamBuild’s versioned deployment workflow. Use virtual mode as the
project default:
Alternatively, set mode = "virtual" in an individual pipeline.toml.
The lifecycle is:
Planning and building do not affect the published graph. Inspection and a deployment audit inform
the operator, but the resulting readiness assessment is advisory rather than a promotion lock.
Promotion binds the stable views to the staged deployment; rollback can later bind the complete
graph to a retained prior publication.
In this workflow, audit is the operation and assessment is its overall result. The deployment
audit combines staged-versus-active comparisons, replay coverage, and applicable SQL data-quality
audits into a ready, caution, or not_ready assessment.
Build
Build creates deployment-specific model objects while the active stable views remain unchanged:
The deployment ID is generated as YYYYMMDDTHHMMSSZ_<six-hex> unless supplied with
--deployment-id.
Discover and inspect
Build prints the generated ID. You can also reconstruct inventory from authoritative warehouse
evidence:
Inventory distinguishes active, staged, superseded, incomplete, metadata-missing, and
physical-missing deployments. List and show are read-only.
The development UI exposes the same inventory and deployment detail, including scoped lineage,
staged-versus-live changes, promotion preview, resumable partial promotion, and retained rollback
guidance. Cleanup is also available from the deployment list. Audit and rollback remain explicit CLI
operations.
Compare the active graph with a retained deployment, or compare two explicit endpoints:
Diff reports added, removed, changed, unchanged, and physically missing model relations using model
presence, schemas, physical availability, and current row counts. Either explicit endpoint may be
active.
Audit staged data
stb deployment audit compares staged and active data, checks replay coverage, runs applicable SQL
audits, and reports an overall assessment:
ready means the available evidence satisfies the configured freshness and row-count checks and
no error-severity SQL audit failed.caution means the evidence is incomplete or warrants review, such as unavailable freshness
evidence, missing replay partitions, or a staged row count below the configured ratio.not_ready means a stronger negative signal was found, such as lag beyond the configured limit,
an empty staged relation replacing a populated active relation, or a failed error-severity SQL
audit.
Warning-severity SQL audit failures appear in the results but do not by themselves change the
overall assessment.
Configure the advisory replay thresholds in committed project configuration:
The assessment is an operator safety signal, not an enforced promotion lock. deployment promote
does not require a previously persisted ready result.
tbl__orders to read from the selected deployment
table. ClickHouse replaces each relation atomically, but the complete graph is not graph-atomic:
bindings are switched one relation at a time and StreamBuild reports that capability in output.
Before promotion, consumers reach deployment A through the unsuffixed stable view and deployment B
remains staged. Promotion replaces that view definition so it reads deployment B. The replacement
is atomic for this one relation only; a multi-model graph can be partly switched if promotion stops,
and retry applies the remaining bindings.
Before confirmation, the CLI and UI show additions, replacements, removals, and orphaned live
relations. If promotion stops after switching only part of the graph, the deployment remains
retryable and the next promotion applies only the remaining changes.
Show, audit, and promote require explicit positional IDs. There is no automatic sole-candidate or
latest-candidate selection.
Roll back
Roll back the complete stable graph to the immediately preceding distinct publication or an explicit
previously published deployment:
Rollback requires confirmation unless --auto-approve is supplied. JSON mode also requires
--auto-approve. StreamBuild rejects staged, unpublished, already-active, missing, and drifted
targets rather than guessing from partial state.
Rollback restores a prior publication’s definitions and bindings, not a historical data snapshot.
Retained streaming graphs remain live and may have received newer rows since publication.
Operational commands
doctor diagnoses stable-view and deployment-reference problems.repair active-view points one broken logical view at a known deployment.reconcile previews or records a compatible live metadata baseline.janitor previews or removes stale deployment objects while protecting active and
rollback-retained state.
Promotion, rollback, repair, reconciliation, and janitor operations must not overlap against the
same target database.
These commands are virtual-environment-only. There is no automatic mode conversion or direct-mode
equivalent. 
