MigrationRoom operator guide
Read the dashboard, fire the six migration actions, and know where each result belongs.
Dashboard map
MigrationRoom separates controls and live run state from the agent conversation:
| Region | Purpose | Operator check |
|---|---|---|
| Setup | Select the source, source database, and OLAP query pack | Source is Databricks, database is migration_demo.tpch, and the canonical queries are loaded |
| Conversation | Start or resume the chat bound to the selected source agent | Databricks → ClickHouse Cloud is selected and the intended conversation is active |
| Steps | Fire one of six source-specific prompt templates | Read the current state before re-firing; all six buttons remain clickable |
| Live-run header | Pick a run and see state, elapsed time, throughput, ETA, and controls | The intended run is selected before pausing, resuming, or cancelling |
| Migration tab | Follow per-table progress, KPIs, and milestone events | Data movement is complete before validation |
| Validation tab | Read source/target row-count results | Every required table passes or the workflow stops |
| Benchmark tab | Read per-query source and target timing | Correctness and timing type are understood before interpreting a speedup field |
| Chat pane | Review reasoning, DDL, translations, and agent proposals | Human review remains responsible for design and claims |
The dashboard lists source databases through the source connector. If enumeration fails, it permits a manually typed source database; that fallback does not prove credentials or namespace access are correct.
The six actions
1. Discover & Design Schema
The agent introspects Databricks through the read-only source MCP and uses the OLAP
queries to propose physical design. It pauses for human approval before applying target
DDL through ClickHouse tooling. Review
types, timezone semantics, ORDER BY, semi-structured columns, generated columns,
deletion/history requirements, and the target database before continuing.
2. Migrate Data
The agent creates a migrationkit job, dispatches it, tails once to prove it started,
and stops chatting. It may show generated Python in tool activity, but the operator does
not run that code separately. The Migration tab becomes the authoritative progress view.
Direct batches are the workshop default; staged S3 movement is an advanced option.
3. Validate
The validator compares source and target table counts and writes rows to the Validation tab. A mismatch is a stop gate: correct the schema or copy process and re-fire migration, then validation. Do not patch target rows to manufacture parity.
4. Rewrite Queries
The agent reasons through each Databricks-to-ClickHouse SQL translation in chat. This is not a mechanical script. Require the same result shape and semantics for every translation, including nested data, JSON, window filters, arithmetic edge cases, and namespace changes. Save the accepted target set through Edit · OLAP.
5. Benchmark
The benchmarker times equivalent queries on source and target and writes the result to the Benchmark view. Databricks server time is used when query-history access provides it; otherwise wall time must be labeled as such. Verify correctness before latency and do not describe the guided UI comparison as a concurrency/load test.
6. Optimize
The agent proposes ClickHouse-specific changes. Proposals are not automatically correct for the workload: approve them only after plan, cardinality, correctness, and operational cost review. Re-fire Benchmark after an accepted change with the same semantics and configuration.
Recovery rules
- Re-firing is permitted, but always record the authoritative run ID.
- Quiet chat during migration is expected; inspect the Migration tab before intervening.
- Preserve redacted failures. An instructor screenshot can explain an unavailable step, but participant evidence must say not executed.
- Keep all credentials in ignored environment files, credential stores, or secure delivery channels. Never put rendered secrets or signed URLs in chat or screenshots.
- MigrationRoom owns the copy workflow and can query prepared catalogs through chat.
Unity and REST
DataLakeCatalogattachment is instructor preparation and must not be presented as a MigrationRoom button capability.