Virtual Environments

Virtual environments preserve SQLTide’s versioned deployment workflow. Use virtual mode as the project default:

[defaults]
pipeline_mode = "virtual"

Alternatively, set mode = "virtual" in an individual pipeline.toml.

The lifecycle is:

1. Write typed SQL and validate it with sqt compile.
2. Read the proposed work with sqt plan.
3. Build a separate version with sqt build and inspect its results.
4. Publish it with sqt deployment promote --latest.

Planning and building do not change what consumers read. sqt deployment audit reports whether a deployment looks ready, but sqt deployment promote does not check that result, so audit before you promote. Promotion binds the stable views to the staged deployment; rollback can later bind the complete graph to a retained prior publication.

Build

sqt build --auto-approve
sqt build --select orders --full-refresh --auto-approve
sqt build --select orders --start-time 2026-07-01T00:00:00Z --auto-approve

Build creates deployment-specific model objects while the active stable views remain unchanged:

tbl__orders__20260729T120000Z_ab12cd
mv__orders__20260729T120000Z_ab12cd

The deployment ID is generated as YYYYMMDDTHHMMSSZ_<six-hex> unless supplied with --deployment-id.

Discover and inspect

Build prints the generated ID. List all deployments, or show the newest one:

sqt deployment list
sqt deployment show --latest

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:

sqt deployment diff --latest
sqt deployment diff 20260729T120000Z_ab12cd:20260730T120000Z_cd34ef

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

sqt deployment audit --latest

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

Set the thresholds deployment audit uses in sqltide_project.toml:

[defaults.deployment_readiness]
maximum_lag = "30s"
minimum_staged_row_ratio = 0.5

sqt deployment promote does not run or check the audit, and will promote a not_ready deployment. Audit before you promote.

Promote

sqt deployment promote --latest

Promotion points each stable view, such as tbl__orders, at the deployment’s table. ClickHouse switches each view atomically, but SQLTide switches the views one at a time, not all together: while promotion runs, a consumer that reads two models can see the new version of one and the old version of the other. If promotion stops partway, run sqt deployment promote again with the same deployment ID; it switches only the views that remain.

The CLI promotes without asking for confirmation; the UI shows a preview first.

Show, diff, audit, and promote take a deployment ID, or --latest for the most recently built deployment. sqt deployment promote --latest refuses when that deployment is already published or when more than one deployment is staged, and prints the ID it promotes.

From 0.68.1, promotion also refuses a deployment built on an upstream model version that is no longer published. This happens when a deployment that changed only a downstream model is promoted after another deployment published a new version of its upstream model. The error names the model; rebuild it with sqt build --select <model> and promote that build.

Staged views that stopped receiving rows (fixed in 0.68.0)

In virtual mode up to and including 0.67.3, a build that staged a model without staging the model it reads created that model’s materialized view on the upstream model’s stable view. ClickHouse never runs a materialized view for inserts into a view, so that version stopped receiving new rows as soon as its build finished, both before and after promotion. Builds that also staged the upstream model were not affected.

To check a target database, list the materialized views that read a view:

SELECT arrayJoin(dependencies_table) AS materialized_view
FROM system.tables
WHERE database = currentDatabase() AND engine = 'View';

Each name ends with its deployment ID, and that deployment’s version of the model receives no new rows. Do not promote or roll back to any deployment listed here; rebuild the model instead.

After upgrading to 0.68.0, rebuild each affected model and promote it:

sqt build --select order_report --full-refresh
sqt deployment promote --latest

The full refresh replays the source’s retained history, so rows that arrived while the old version was stalled come back if the source still has them. The stalled deployment stays listed until sqt janitor --apply removes it.

Roll back

Roll back the complete stable graph to the immediately preceding distinct publication or an explicit previously published deployment:

sqt deployment rollback --previous
sqt deployment rollback 20260729T120000Z_ab12cd

Rollback requires confirmation unless --auto-approve is supplied. JSON mode also requires --auto-approve. Rollback refuses a deployment that was never published, is already active, is missing tables, or whose stable views no longer point where SQLTide last left them.

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

sqt doctor
sqt repair active-view --table tbl__orders --deployment-id 20260729T120000Z_ab12cd
sqt reconcile
sqt reconcile --apply
sqt janitor
sqt janitor --retention-days 30 --apply

• doctor diagnoses stable-view and deployment-reference problems.
• repair active-view points one broken logical view at a deployment that doctor lists for it.
• 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.