sqt plan

Compare the compiled project with ClickHouse and print what a build would change. sqt plan changes nothing in ClickHouse; it writes the plan and the SQL a build would run to target/run/plan/.

sqt plan
sqt plan --select orders
sqt plan --select pipeline:order_events --json
sqt plan --deployment-id 20260701T120000Z_release202607
sqt plan --verbose
sqt plan -v

The effective project mode chooses the planner:

• Direct mode: plan the requested destructive rebuild. No selector means every model; selectors include downstream closure. Matching objects are not pruned.
• Virtual environments: plan changed deployment objects, replay roots, and policies against published and staged state.

In both modes, a warning follows the plan when a live Kafka table consumes as a different consumer group than the project declares, for example after name was edited by hand. It names both groups and notes that offsets would not carry over if the table were recreated. --json lists these warnings under consumer_group_warnings, an empty list when there are none; the same key is in the published plan artifact. The warning does not change or block the plan.

Use --deployment-id in virtual-environment mode to inspect exact deployment-specific physical names. Its timestamp prefix also fixes the deployment creation timestamp, so unchanged warehouse state and the same explicit identity produce deterministic workflow bytes. If omitted, plan generates a disposable preview identity.

Selection

Repeat --select to union bare model names and pipeline:<name> selectors:

sqt plan --select orders --select region_lookup

Graph + syntax, tags, paths, globs, and exclusions are not supported by plan.

Changed direct models

sqt plan --changed
sqt plan --changed --include-missing-upstream

--changed selects changed direct models and pipelines reading managed Kafka sources with deployed settings drift, then expands their downstream scope. It is direct-only and cannot be combined with --select. --include-missing-upstream includes absent project-owned prerequisites; it requires --changed or --select. The same flags work on sqt build. Inspect the connected plan rather than assuming every missing or drifted source can be safely recreated.

Replay controls

sqt plan --select orders --full-refresh
sqt plan --select orders --start-time 2026-07-01T00:00:00Z

The replay controls are mutually exclusive. --full-refresh requires --select in virtual mode; direct --start-time accepts --changed or an explicit selection.

--full-refresh applies only to virtual environments. --start-time applies to both modes. In direct mode it shows the effective start time in plan text and the nullable top-level start_time field in plan JSON. The direct SQL template shows the capture, preflight, and replay structure; values captured from ClickHouse during execution remain placeholders. Direct replay inputs must already exist and expose timestamp or landed-at lineage through the selected closure.

Common options

Connecting commands accept --host, --port, --username, --password, --database, --target, --vars, and --project-dir. --json emits structured output and --verbose (-v) includes full schema diffs.

Workflow artifacts

After read-only connected inspection, SQLTide atomically replaces the complete plan directory. Direct mode publishes a non-executable template because replay watermarks and other runtime captures do not exist yet:

target/run/plan/
├── plan.json
├── workflow.template.sql
└── steps/
    ├── 0001_<step-id>.sql.template
    └── ...

Virtual-environment plans have all physical identities and SQL values available during planning, so they publish exact workflow.sql and steps/*.sql files instead.

The bytes printed by sqt plan --json are exactly the bytes stored in plan.json; text mode writes the same JSON through the same serializer. In either layout, the combined workflow joins the numbered statements in execution order.

Plan and build use the same rules, but sqt build plans again from scratch and never reads target/run/plan/. If the warehouse changes between the two commands, the build can differ from the plan; sqt build shows its own plan before you confirm.

All target/run/ files are disposable visibility output, not local state. Failed compilation, connected inspection, workflow assembly, or publication leaves any previous complete plan artifact unchanged.