diff --git a/.env.example b/.env.example
index 6f971a9..23eb6ed 100644
--- a/.env.example
+++ b/.env.example
@@ -18,12 +18,13 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 
 
 # ── Agent Provider / Model ────────────────────────────────────
-# The three pre-built migration agents (Postgres, Snowflake, ClickHouse OSS)
-# each default to whichever API key is set above. Override globally or
-# per-source. Use LibreChat provider casing exactly:
+# The five pre-built migration agents (Postgres, Snowflake, BigQuery,
+# ClickHouse OSS, Databricks) each default to whichever API key is set
+# above. Override globally or per-source. Use LibreChat provider casing
+# exactly:
 #   anthropic | openAI | google | bedrock | azureOpenAI
 #
-# Global default (applies to all three agents unless overridden):
+# Global default (applies to all five agents unless overridden):
 # AGENT_PROVIDER=anthropic
 # AGENT_MODEL=claude-sonnet-4-6
 #
@@ -36,6 +37,8 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # AGENT_MODEL_BIGQUERY=claude-sonnet-4-6
 # AGENT_PROVIDER_CLICKHOUSE_OSS=anthropic
 # AGENT_MODEL_CLICKHOUSE_OSS=claude-haiku-4-5-20251001
+# AGENT_PROVIDER_DATABRICKS=anthropic
+# AGENT_MODEL_DATABRICKS=claude-sonnet-4-6
 #
 # Changing any of these after first start requires `make reset-agent`.
 # (Partners can also edit each agent's model directly in the LibreChat UI.)
@@ -202,3 +205,22 @@ DATASET_SIZE=medium
 # STAGING_GCS_KEY_FILE=./secrets/gcp-key.json  # optional — defaults to BIGQUERY_KEY_FILE
 # STAGING_GCS_ACCESS_KEY_ID=<hmac-access-id>
 # STAGING_GCS_SECRET_ACCESS_KEY=<hmac-secret>
+
+# ── Databricks Source (only for the databricks migration source) ──
+# Requires a Databricks workspace with Unity Catalog and a SQL warehouse.
+# Provision everything with `make databricks-provision` (existing
+# workspace) or `make databricks-provision-workspace` (creates a new
+# serverless workspace), or set these by hand and run
+# `make databricks-setup` for the workload only.
+# See sources/databricks/GUIDE.md.
+#
+# DATABRICKS_HOST=https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
+# DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/xxxxxxxxxxxxxxxx
+# DATABRICKS_TOKEN=dapi................................
+# DATABRICKS_NAMESPACE=migration_demo.tpch     # <catalog>.<schema>
+#
+# S3 staging for large Databricks → ClickHouse Cloud migrations reuses the
+# STAGING_S3_* variables above. On Databricks it additionally needs a Unity
+# Catalog external location over the bucket with WRITE FILES granted —
+# `make databricks-provision` creates one when enable_s3_staging=true.
+# Without it, migrations still work via the direct batch path.
diff --git a/.gitignore b/.gitignore
index 485e470..d2701a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,6 +22,9 @@ venv/
 **/.terraform/
 **/.terraform.lock.hcl
 
+# Generated by `make databricks-provision-workspace` — contains an OAuth secret
+sources/databricks/terraform/demo/workspace.auto.tfvars.json
+
 # Service-account JSON keys (BigQuery, GCS staging). `secrets/` is
 # created on `make setup` with a placeholder gcp-key.json. The real key
 # replaces that file but must never be committed.
diff --git a/Makefile b/Makefile
index 63fdb74..967b172 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: setup up up-snowflake up-bigquery down reset reset-agent health logs pull diagram snowflake-setup snowflake-provision bigquery-provision tpch-data tpch-load-bigquery tpch-load-postgres tpch-load-clickhouse-oss migration-status
+.PHONY: setup up up-snowflake up-bigquery up-databricks down reset reset-agent health logs pull diagram snowflake-setup snowflake-provision bigquery-provision databricks-setup databricks-provision databricks-provision-workspace tpch-data tpch-load-bigquery tpch-load-postgres tpch-load-clickhouse-oss migration-status
 
 setup:
 	@echo "Setting up MigrationRoom..."
@@ -15,7 +15,8 @@ setup:
 	@mkdir -p secrets && [ -f secrets/gcp-key.json ] || echo '{}' > secrets/gcp-key.json
 	@# Seed a runtime librechat.yaml so `docker compose up` works even
 	@# before the user has run one of the up* targets. Defaults to empty
-	@# profiles, which strips snowflake-source and bigquery-source.
+	@# profiles, which strips snowflake-source, bigquery-source, and
+	@# databricks-mcp.
 	@COMPOSE_PROFILES="" bash scripts/build-librechat-runtime.sh
 	@echo "✅ Setup complete. Run: make up"
 
@@ -87,6 +88,57 @@ bigquery-provision:
 	@echo ""
 	@echo "Capture the .env block with: cd sources/bigquery/terraform && terraform output -raw env_block"
 
+up-databricks: export COMPOSE_PROFILES := databricks
+up-databricks:
+	@echo "Regenerating librechat.runtime.yaml for active profiles: databricks"
+	@bash scripts/build-librechat-runtime.sh
+	@echo "Pulling images..."
+	docker compose pull
+	@echo "Building custom containers..."
+	docker compose build
+	@echo "Starting services (including databricks-mcp)..."
+	docker compose up -d
+	@echo ""
+	@echo "Container status:"
+	@docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
+	@echo ""
+	@echo "If databricks-mcp shows unhealthy, check: docker compose logs databricks-mcp"
+	@echo "(DATABRICKS_HOST / DATABRICKS_HTTP_PATH / DATABRICKS_TOKEN in .env must be set.)"
+
+databricks-setup:
+	@echo "Installing setup dependencies (databricks-sql-connector)…"
+	@python3 -m pip install --quiet -r sources/databricks/scripts/requirements.txt
+	@echo "Setting up migration_demo.tpch workload in Databricks…"
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+	  python3 sources/databricks/scripts/setup_workload.py
+
+databricks-provision:
+	@echo "Provisioning the Databricks demo objects with Terraform…"
+	cd sources/databricks/terraform/demo && terraform init && terraform apply
+	@echo ""
+	@echo "Capture the .env block with:"
+	@echo "  cd sources/databricks/terraform/demo && terraform output -raw env_block"
+
+databricks-provision-workspace:
+	@echo "Phase 1/2 — creating a serverless Databricks workspace…"
+	cd sources/databricks/terraform/workspace && terraform init && terraform apply
+	@echo ""
+	@echo "Phase 2/2 — provisioning the demo objects into the new workspace…"
+	@# Hand the new workspace URL and the account SP's OAuth credentials to
+	@# the demo module. Terraform auto-loads *.auto.tfvars.json, so no
+	@# copy-paste step. The merge logic lives in a script, not an inline
+	@# heredoc: a heredoc spanning multiple Makefile recipe lines only
+	@# works under GNU Make's `.ONESHELL` (added in 3.82) — plain `make`
+	@# on macOS is still 3.81, which runs each recipe line in its own
+	@# shell and silently breaks a multi-line heredoc.
+	cd sources/databricks/terraform/workspace && terraform output -json > /tmp/mr-dbx-workspace-out.json
+	python3 sources/databricks/scripts/merge_workspace_tfvars.py /tmp/mr-dbx-workspace-out.json
+	cd sources/databricks/terraform/demo && terraform init && terraform apply
+	@rm -f /tmp/mr-dbx-workspace-out.json
+	@echo ""
+	@echo "Capture the .env block with:"
+	@echo "  cd sources/databricks/terraform/demo && terraform output -raw env_block"
+
 # Shared TPC-H workload. BigQuery is the first loader; future sources
 # get sibling targets (tpch-load-postgres, tpch-load-clickhouse-oss).
 # The Snowflake source keeps `snowflake-setup` — different mechanics
@@ -133,7 +185,7 @@ tpch-load-clickhouse-oss: tpch-data
 	  python3 workloads/tpch/clickhouse-oss/load.py
 
 down:
-	docker compose --profile snowflake --profile bigquery down
+	docker compose --profile snowflake --profile bigquery --profile databricks down
 
 reset:
 	@bash scripts/reset.sh
diff --git a/README.md b/README.md
index 6bea4e6..011d93f 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,8 @@ migration end-to-end in under an hour.**
 
 MigrationRoom is a self-contained Docker Compose playground that
 turns the messy reality of database migration into a six-click
-workflow. Pick a source (PostgreSQL, Snowflake, BigQuery, or
-ClickHouse OSS), click each step on the dashboard, and watch an LLM
+workflow. Pick a source (PostgreSQL, Snowflake, BigQuery, Databricks,
+or ClickHouse OSS), click each step on the dashboard, and watch an LLM
 agent with live MCP connections do the work: introspect the source,
 design a ClickHouse target schema, move the data, validate row
 counts, rewrite analytical queries, and benchmark source vs target —
@@ -35,7 +35,7 @@ all on a real ClickHouse Cloud service you control.
   not its training-data approximation of them. The skills are pulled
   in as a git submodule so updates ship with `git submodule update
   --remote`.
-- **Source-agnostic in the same shape.** Four sources, one dashboard,
+- **Source-agnostic in the same shape.** Five sources, one dashboard,
   one set of six step buttons. The agent and source MCP swap behind
   the scenes when you change the source dropdown — no setup juggling.
 - **MCP-native.** Every database connection is exposed through an MCP
@@ -58,6 +58,7 @@ all on a real ClickHouse Cloud service you control.
 | **ClickHouse OSS → ClickHouse Cloud** | Web analytics platform + TPC-H option | [sources/clickhouse-oss/GUIDE.md](sources/clickhouse-oss/GUIDE.md) |
 | **Snowflake → ClickHouse Cloud** | TPC-H + Snowflake-specific augmentations (VARIANT, TIMESTAMP_TZ, Stream, Dynamic Table, Clustering Key) | [sources/snowflake/GUIDE.md](sources/snowflake/GUIDE.md) |
 | **BigQuery → ClickHouse Cloud** | TPC-H + BigQuery-specific augmentations (STRUCT, ARRAY<STRUCT>, partitioned + clustered tables, materialized view) | [sources/bigquery/GUIDE.md](sources/bigquery/GUIDE.md) |
+| **Databricks → ClickHouse Cloud** | TPC-H + Databricks-specific augmentations (VARIANT, ARRAY&lt;STRUCT&gt;, MAP, generated column, liquid clustering, deletion vectors, materialized view) | [sources/databricks/GUIDE.md](sources/databricks/GUIDE.md) |
 
 ## Prerequisites
 
@@ -99,10 +100,10 @@ self-signed certificate warning). Sign in with
 > total. PostgreSQL: `docker compose logs postgres -f`. ClickHouse
 > OSS: `docker compose logs clickhouse-oss -f`.
 
-For Snowflake or BigQuery, run `make up-snowflake` or `make
-up-bigquery` instead — both source MCPs are profile-gated because
-they need account credentials in `.env` (see the per-source GUIDE for
-the setup walkthrough).
+For Snowflake, BigQuery, or Databricks, run `make up-snowflake`, `make
+up-bigquery`, or `make up-databricks` instead — all three source MCPs
+are profile-gated because they need account credentials in `.env` (see
+the per-source GUIDE for the setup walkthrough).
 
 ## Using the MigrationRoom dashboard
 
@@ -120,16 +121,17 @@ Three controls that determine which agent runs and what data it
 operates on. Change them before clicking any step button.
 
 - **Source dropdown** — `Postgres` / `Snowflake` / `BigQuery` /
-  `ClickHouse OSS`. Switching the source **auto-switches the
-  LibreChat agent** in the right pane to the matching pre-built agent
-  (e.g. picking BigQuery selects the `BigQuery → ClickHouse Cloud`
-  agent with its MCPs and system prompt). No agent toggling needed in
-  LibreChat.
+  `Databricks` / `ClickHouse OSS`. Switching the source
+  **auto-switches the LibreChat agent** in the right pane to the
+  matching pre-built agent (e.g. picking BigQuery selects the
+  `BigQuery → ClickHouse Cloud` agent with its MCPs and system
+  prompt). No agent toggling needed in LibreChat.
 - **Source database dropdown** — the actual database / dataset /
   schema name on the source. For bundled workloads: `ecommerce`
   (Postgres) or `analytics` (ClickHouse OSS) or `migration_demo`
-  (Snowflake / BigQuery). For TPC-H loaded via `make tpch-load-*`:
-  `tpch`.
+  (Snowflake / BigQuery / Databricks, e.g. `migration_demo.tpch` for
+  Databricks' `catalog.schema` pair). For TPC-H loaded via `make
+  tpch-load-*`: `tpch`.
 - **Edit · N OLAP button** — opens an editor for the analytical
   queries that drive step 1's `ORDER BY` design, step 4's query
   rewrite, and step 5's benchmark. `N` is how many queries are
@@ -209,6 +211,7 @@ reads `KPI DASHBOARD · LIVE · STEP N — <step name>`.
   [Postgres](sources/postgres/GUIDE.md) ·
   [Snowflake](sources/snowflake/GUIDE.md) ·
   [BigQuery](sources/bigquery/GUIDE.md) ·
+  [Databricks](sources/databricks/GUIDE.md) ·
   [ClickHouse OSS](sources/clickhouse-oss/GUIDE.md).
 - **Add your own source database** —
   [docs/adding-a-source.md](docs/adding-a-source.md) explains the
@@ -226,9 +229,10 @@ make setup               # first-time setup (submodules + agent skills + .env)
 make up                  # start the playground (Postgres + ClickHouse OSS sources)
 make up-snowflake        # also start the Snowflake source MCP (needs SNOWFLAKE_* in .env)
 make up-bigquery         # also start the BigQuery source MCP (needs BIGQUERY_* in .env)
+make up-databricks       # also start the Databricks source MCP (needs DATABRICKS_* in .env)
 make down                # stop without removing data
 make reset               # destroy volumes and start fresh
-make reset-agent         # delete + recreate the four pre-built agents (after model/provider changes)
+make reset-agent         # delete + recreate the five pre-built agents (after model/provider changes)
 ```
 
 The full command list lives in the [Makefile](Makefile); see the
diff --git a/docker-compose.yml b/docker-compose.yml
index ec8a087..b8ad991 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -229,6 +229,40 @@ services:
     networks:
       - playground-net
 
+  # ── Databricks Source MCP ───────────────────────────────────
+  # Purpose-built read-only MCP (docker/databricks-mcp) over a Databricks
+  # SQL warehouse. Databricks publishes no introspect-and-SELECT MCP for
+  # warehouses — their `databricks-mcp` package is an OAuth helper for the
+  # hosted UC-functions / vector-search / Genie servers — so this is ours,
+  # in the same spirit as clickhousectl-mcp. Because we author the tool
+  # schemas, no Gemini shim is needed (unlike snowflake-source).
+  #
+  # Profile-gated: partners using Databricks set DATABRICKS_* in .env then
+  # run `make up-databricks` (or `docker compose --profile databricks up -d`).
+  databricks-mcp:
+    profiles: ["databricks"]
+    build: ./docker/databricks-mcp
+    environment:
+      DATABRICKS_HOST: ${DATABRICKS_HOST:-}
+      DATABRICKS_HTTP_PATH: ${DATABRICKS_HTTP_PATH:-}
+      DATABRICKS_TOKEN: ${DATABRICKS_TOKEN:-}
+      DATABRICKS_NAMESPACE: ${DATABRICKS_NAMESPACE:-}
+    ports:
+      - "8008:8000"
+    # Probe /sse with Python stdlib — the image is python:3.12-slim and has
+    # no curl/wget. The connection to Databricks is lazy (opened per tool
+    # call), so this passes even with invalid credentials; that's
+    # deliberate, so a credential typo surfaces as a clear tool error in
+    # chat rather than a container that won't start.
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request, sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/sse', timeout=2).status == 200 else 1)"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 10s
+    networks:
+      - playground-net
+
   # ── Migration Runner ────────────────────────────────────────
   # Executes Python migration scripts in-chat (via run_python MCP tool)
   # so the agent can drive end-to-end migrations without asking the
@@ -329,8 +363,10 @@ services:
     # `docker compose ps` instead of a silent runtime bug.
     #
     # snowflake-source / snowflake-source-shim are profile-gated to
-    # `snowflake`; Compose silently skips depends_on entries for services
-    # excluded by the active profile set, so leaving them here is safe.
+    # `snowflake`, bigquery-source to `bigquery`, and databricks-mcp to
+    # `databricks`; Compose silently skips depends_on entries for
+    # services excluded by the active profile set, so leaving them
+    # here is safe.
     depends_on:
       mongodb:
         condition: service_healthy
@@ -353,6 +389,9 @@ services:
         # check we can express.
         condition: service_started
         required: false
+      databricks-mcp:
+        condition: service_healthy
+        required: false
     healthcheck:
       test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3080/health || exit 1"]
       interval: 10s
@@ -377,9 +416,9 @@ services:
       MONGO_URI: "mongodb://mongodb:27017/LibreChat"
       LIBRECHAT_URL: "http://librechat:3080"
       # Forwarded from the host's $COMPOSE_PROFILES so the agent loop knows
-      # which optional sources (snowflake, bigquery) the partner actually
-      # turned on. Agents for inactive sources are skipped and any stale
-      # row from a previous profile is deleted.
+      # which optional sources (snowflake, bigquery, databricks) the partner
+      # actually turned on. Agents for inactive sources are skipped and any
+      # stale row from a previous profile is deleted.
       ACTIVE_PROFILES: ${COMPOSE_PROFILES:-}
     entrypoint: ["/bin/bash", "-c"]
     command:
@@ -436,6 +475,7 @@ services:
           "postgres|Postgres → ClickHouse Cloud|POSTGRES"
           "snowflake|Snowflake → ClickHouse Cloud|SNOWFLAKE"
           "bigquery|BigQuery → ClickHouse Cloud|BIGQUERY"
+          "databricks|Databricks → ClickHouse Cloud|DATABRICKS"
           "clickhouse-oss|ClickHouse OSS → ClickHouse Cloud|CLICKHOUSE_OSS"
         )
         SHARED_MCPS=(clickhousectl clickhouse-docs migration-runner)
@@ -447,6 +487,7 @@ services:
         declare -A OPTIONAL_PROFILE=(
           [snowflake]=snowflake
           [bigquery]=bigquery
+          [databricks]=databricks
         )
         NORM_PROFILES=",$$(echo "$${ACTIVE_PROFILES:-}" | tr ' ' ',' | tr -s ','),"
 
diff --git a/docker/databricks-mcp/Dockerfile b/docker/databricks-mcp/Dockerfile
new file mode 100644
index 0000000..743a607
--- /dev/null
+++ b/docker/databricks-mcp/Dockerfile
@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY sql_guard.py server.py /app/
+
+EXPOSE 8000
+CMD ["python", "server.py"]
diff --git a/docker/databricks-mcp/requirements.txt b/docker/databricks-mcp/requirements.txt
new file mode 100644
index 0000000..5a98f30
--- /dev/null
+++ b/docker/databricks-mcp/requirements.txt
@@ -0,0 +1,3 @@
+mcp[cli]>=1.0
+databricks-sql-connector>=4.0
+sqlglot>=30.0
diff --git a/docker/databricks-mcp/server.py b/docker/databricks-mcp/server.py
new file mode 100644
index 0000000..932b72b
--- /dev/null
+++ b/docker/databricks-mcp/server.py
@@ -0,0 +1,193 @@
+"""MigrationRoom — Databricks source MCP server.
+
+Read-only introspection and SELECT access to ONE Databricks SQL warehouse,
+exposed over MCP/SSE so the migration agent can discover the source schema
+without writing Python.
+
+Why this exists rather than an off-the-shelf package: Databricks' own
+`databricks-mcp` PyPI package is an OAuth helper for their *hosted* MCP
+servers (Unity Catalog functions, vector search, Genie) — there is no
+official introspect-and-SELECT MCP for a SQL warehouse. Authoring the tool
+schemas ourselves also keeps them free of the JSON-Schema keywords that
+Gemini's function-calling API rejects, so this server needs no shim (unlike
+snowflake-source).
+
+Environment:
+    DATABRICKS_HOST         required — workspace URL or bare hostname
+    DATABRICKS_HTTP_PATH    required — e.g. /sql/1.0/warehouses/abc123
+    DATABRICKS_TOKEN        required — PAT for a read-only principal
+    DATABRICKS_NAMESPACE    optional — "<catalog>.<schema>" default scope
+    MCP_PORT                optional — default 8000
+"""
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from sql_guard import SqlNotAllowed, guard
+
+mcp = FastMCP("databricks-source")
+
+
+def _host() -> str:
+    """Bare hostname — the connector rejects a scheme or trailing slash."""
+    raw = os.environ["DATABRICKS_HOST"].strip()
+    return raw.removeprefix("https://").removeprefix("http://").rstrip("/")
+
+
+@contextmanager
+def _cursor():
+    """One short-lived connection + cursor per tool call.
+
+    Deliberately not pooled: LibreChat holds the SSE session open for the
+    whole conversation, and a warehouse that auto-stops would leave a stale
+    connection behind. Reconnecting costs ~1 s and is far less confusing
+    than a silently dead handle.
+    """
+    from databricks import sql as dbsql
+
+    conn = dbsql.connect(
+        server_hostname=_host(),
+        http_path=os.environ["DATABRICKS_HTTP_PATH"],
+        access_token=os.environ["DATABRICKS_TOKEN"],
+    )
+    try:
+        cur = conn.cursor()
+        try:
+            yield cur
+        finally:
+            cur.close()
+    finally:
+        conn.close()
+
+
+def _rows(cur) -> list[dict[str, Any]]:
+    columns = [c[0] for c in cur.description or []]
+    return [dict(zip(columns, row)) for row in cur.fetchall()]
+
+
+def _ident(name: str) -> str:
+    """Backtick-quote one identifier part, rejecting embedded backticks.
+
+    Identifiers arrive as tool arguments from the model, so they are
+    untrusted input even though they are not user-facing.
+    """
+    cleaned = (name or "").strip().strip("`")
+    if not cleaned or "`" in cleaned:
+        raise ValueError(f"invalid identifier: {name!r}")
+    return f"`{cleaned}`"
+
+
+@mcp.tool()
+def list_catalogs() -> list[dict[str, Any]]:
+    """List Unity Catalog catalogs visible to this principal."""
+    with _cursor() as cur:
+        cur.execute(
+            "SELECT catalog_name, comment "
+            "FROM system.information_schema.catalogs "
+            "ORDER BY catalog_name"
+        )
+        return _rows(cur)
+
+
+@mcp.tool()
+def list_schemas(catalog: str) -> list[dict[str, Any]]:
+    """List schemas in `catalog`."""
+    with _cursor() as cur:
+        cur.execute(
+            "SELECT schema_name, comment "
+            "FROM system.information_schema.schemata "
+            "WHERE catalog_name = ? "
+            "ORDER BY schema_name",
+            [catalog],
+        )
+        return _rows(cur)
+
+
+@mcp.tool()
+def list_tables(catalog: str, schema: str) -> list[dict[str, Any]]:
+    """List tables in `catalog`.`schema` with Delta size metadata.
+
+    Row counts are NOT included: Delta metadata doesn't carry them and a
+    per-table COUNT(*) would make this call slow. Get them with one
+    UNION ALL count query via run_select_query instead.
+    """
+    with _cursor() as cur:
+        cur.execute(
+            "SELECT table_name, table_type, comment "
+            "FROM system.information_schema.tables "
+            "WHERE table_catalog = ? "
+            "  AND table_schema = ? "
+            "ORDER BY table_name",
+            [catalog, schema],
+        )
+        tables = _rows(cur)
+        for row in tables:
+            row["sizeInBytes"] = None
+            row["numFiles"] = None
+            if row.get("table_type") not in (None, "MANAGED", "EXTERNAL"):
+                continue
+            fq = f"{_ident(catalog)}.{_ident(schema)}.{_ident(row['table_name'])}"
+            try:
+                cur.execute(f"DESCRIBE DETAIL {fq}")
+                detail = _rows(cur)
+            except Exception:
+                # Views and non-Delta tables have no DESCRIBE DETAIL.
+                continue
+            if detail:
+                row["sizeInBytes"] = detail[0].get("sizeInBytes")
+                row["numFiles"] = detail[0].get("numFiles")
+        return tables
+
+
+@mcp.tool()
+def describe_table(catalog: str, schema: str, table: str) -> dict[str, Any]:
+    """Full schema plus Delta detail for one table.
+
+    Returns columns, plus clustering/partition columns, table features,
+    deletion-vector state, and recent history — the source-specific
+    features the migration has to make decisions about.
+    """
+    fq = f"{_ident(catalog)}.{_ident(schema)}.{_ident(table)}"
+    out: dict[str, Any] = {"table": f"{catalog}.{schema}.{table}"}
+    with _cursor() as cur:
+        cur.execute(f"DESCRIBE TABLE EXTENDED {fq}")
+        out["describe_extended"] = _rows(cur)
+        try:
+            cur.execute(f"DESCRIBE DETAIL {fq}")
+            out["detail"] = _rows(cur)
+        except Exception as exc:
+            out["detail"] = {"unavailable": str(exc)}
+        try:
+            cur.execute(f"DESCRIBE HISTORY {fq} LIMIT 5")
+            out["history"] = _rows(cur)
+        except Exception as exc:
+            out["history"] = {"unavailable": str(exc)}
+    return out
+
+
+@mcp.tool()
+def run_select_query(sql: str, max_rows: int = 200) -> list[dict[str, Any]]:
+    """Run ONE read-only statement (SELECT / WITH / SHOW / DESCRIBE /
+    EXPLAIN) and return its rows.
+
+    A LIMIT is applied when the statement has none. Mutations and
+    multi-statement input are refused — run DDL against the target with
+    the clickhousectl MCP.
+    """
+    try:
+        statement = guard(sql, max_rows=max_rows)
+    except SqlNotAllowed as exc:
+        raise ValueError(str(exc)) from exc
+    with _cursor() as cur:
+        cur.execute(statement)
+        return _rows(cur)
+
+
+if __name__ == "__main__":
+    mcp.settings.host = "0.0.0.0"
+    mcp.settings.port = int(os.environ.get("MCP_PORT", "8000"))
+    mcp.run(transport="sse")
diff --git a/docker/databricks-mcp/sql_guard.py b/docker/databricks-mcp/sql_guard.py
new file mode 100644
index 0000000..de45a50
--- /dev/null
+++ b/docker/databricks-mcp/sql_guard.py
@@ -0,0 +1,181 @@
+"""Read-only statement guard for the Databricks source MCP.
+
+Deliberately free of `mcp` and `databricks` imports so it can be unit-tested
+on the host without the server's dependencies installed.
+
+A Databricks SQL warehouse has no session-level read-only switch, so the
+only place we can refuse a mutation is here. Grants are the second layer
+(see sources/databricks/GUIDE.md) — this is the first.
+
+This module used to classify statements by hand-lexing the leading keyword
+and scanning for semicolons/comments/quotes with regexes. Three review
+rounds each found a real bypass in that approach (a CTE prefixing DML, a
+backtick-quoted identifier blinding the CTE scanner, and comment/string
+lexing that diverged from Spark's grammar). Hand-matching Spark's lexical
+grammar is not a small task, so this rewrite delegates it to sqlglot's
+Databricks dialect tokenizer/parser instead of re-implementing it. A
+CTE-prefixed INSERT then simply *is* an `exp.Insert` node, and correct
+comment/string/identifier handling comes from a real tokenizer.
+"""
+from __future__ import annotations
+
+import logging
+
+import sqlglot
+from sqlglot import exp
+from sqlglot.dialects import Databricks
+from sqlglot.errors import ParseError, TokenError
+
+# sqlglot logs a WARNING ("... contains unsupported syntax. Falling back to
+# parsing as a 'Command'.") for every SHOW/EXPLAIN/OPTIMIZE/VACUUM statement,
+# because those are intentionally handled via the exp.Command fallback below.
+# That is expected here, not a problem to surface on every legitimate SHOW.
+logging.getLogger("sqlglot").setLevel(logging.ERROR)
+
+# Node types that represent a read-only statement once successfully parsed.
+READ_ONLY_NODES = (exp.Select, exp.Union, exp.Subquery, exp.Describe)
+
+# Leading verbs that are read-only even when sqlglot cannot build a full AST
+# for the statement (Databricks-specific extensions like `DESC DETAIL`) or
+# falls back to a generic exp.Command node (e.g. `SHOW CATALOGS`). Kept
+# narrow on purpose: this is NOT "allow anything unparseable", it is "allow
+# only these four verbs when parsing can't tell us more."
+READ_ONLY_VERBS = frozenset({"SHOW", "EXPLAIN", "DESCRIBE", "DESC"})
+
+_DATABRICKS = Databricks()
+_DIALECT = "databricks"
+
+
+class SqlNotAllowed(ValueError):
+    """Raised when a statement is not a single read-only statement."""
+
+
+def _strip_trailing_semicolon(sql: str, toks) -> str:
+    """Return `sql` with its single legal trailing ';' (if any) removed.
+
+    A trailing semicolon is a statement terminator, not statement text; if
+    we appended a LIMIT clause after it we'd produce invalid SQL. Everything
+    else about the original text — including internal whitespace and
+    formatting — is preserved untouched.
+    """
+    if toks and toks[-1].token_type == sqlglot.TokenType.SEMICOLON:
+        return sql[: toks[-1].start].rstrip()
+    return sql.strip()
+
+
+def _unwrap_subquery(node: exp.Expression) -> exp.Expression:
+    """Follow `Subquery.this` down to the innermost wrapped query.
+
+    `(SELECT ...)` parses to `exp.Subquery` wrapping an `exp.Select` (or
+    `exp.Union`), and a `LIMIT` already present in the source SQL may live
+    on that inner node rather than on the `Subquery` itself — e.g.
+    `(SELECT * FROM t LIMIT 5)` puts the limit on the inner `Select`, while
+    `(SELECT * FROM t) LIMIT 5` puts it on the outer `Subquery`. Checking
+    only one of the two slots would miss an existing limit and double it.
+    """
+    while isinstance(node, exp.Subquery) and node.this is not None:
+        node = node.this
+    return node
+
+
+def _existing_limit(root: exp.Expression) -> exp.Expression | None:
+    """Return the existing LIMIT clause for `root`, if any, checking both
+    the node itself and, for a parenthesized query, the query it wraps."""
+    limit = root.args.get("limit")
+    if limit is not None:
+        return limit
+    inner = _unwrap_subquery(root)
+    if inner is not root:
+        return inner.args.get("limit")
+    return None
+
+
+def guard(sql: str, max_rows: int = 200) -> str:
+    """Validate `sql` as one read-only statement and return it ready to run.
+
+    A row cap is appended to SELECT/UNION statements — including ones
+    wrapped in parentheses, e.g. `(SELECT ...)` — that don't already have
+    one, so an unbounded scan can't stream a whole fact table into the
+    chat context. The original statement text is returned (never a
+    sqlglot-regenerated form) with only the trailing statement terminator
+    removed and, when applicable, a LIMIT clause appended.
+
+    Raises SqlNotAllowed for anything else.
+    """
+    if not sql or not sql.strip():
+        raise SqlNotAllowed("empty statement; nothing to run")
+
+    try:
+        toks = _DATABRICKS.tokenize(sql)
+    except TokenError as exc:
+        raise SqlNotAllowed(
+            f"could not tokenize this statement, so it cannot be verified "
+            f"as read-only ({exc})"
+        ) from exc
+
+    # A SEMICOLON anywhere but the final token means multiple statements
+    # were sent. A single trailing ';' is legal and handled above/below.
+    if any(t.token_type == sqlglot.TokenType.SEMICOLON for t in toks[:-1]):
+        raise SqlNotAllowed(
+            "multiple statements are not allowed; send one statement at a time"
+        )
+
+    try:
+        # `exp.Semicolon` is a content-free node sqlglot appends to hold a
+        # comment that trails the statement terminator (e.g. `SELECT 1; --
+        # comment`); it is truthy, so it must be filtered alongside `None`
+        # or a harmless trailing comment reads as a second statement.
+        stmts = [
+            s
+            for s in sqlglot.parse(sql, dialect=_DIALECT)
+            if s and not isinstance(s, exp.Semicolon)
+        ]
+    except (ParseError, TokenError) as exc:
+        # Unparseable is rejected UNLESS the statement's leading token is a
+        # read-only verb — this covers Databricks extensions sqlglot's
+        # parser does not model, e.g. `DESC DETAIL`. We cannot safely modify
+        # text we could not parse, so it is returned as-is (minus a trailing
+        # terminator).
+        if toks and str(toks[0].text).upper() in READ_ONLY_VERBS:
+            return _strip_trailing_semicolon(sql, toks)
+        raise SqlNotAllowed(
+            f"this MCP is read-only and could not parse this statement to "
+            f"confirm that ({exc}). If this is DDL/DML for the target, use "
+            "the clickhousectl MCP instead."
+        ) from exc
+
+    if len(stmts) != 1:
+        raise SqlNotAllowed(
+            "expected exactly one statement; send one statement at a time"
+        )
+
+    root = stmts[0]
+
+    # exp.Command is sqlglot's "I did not model this statement" fallback.
+    # SHOW/EXPLAIN land here — so do OPTIMIZE and VACUUM, which is exactly
+    # why the verb check matters: allowing all Command nodes would be a
+    # new bypass.
+    if isinstance(root, exp.Command):
+        verb = str(root.this).upper()
+        if verb not in READ_ONLY_VERBS:
+            raise SqlNotAllowed(
+                f"this MCP is read-only; '{verb}' is not permitted. Run "
+                "DDL/DML against the target via the clickhousectl MCP "
+                "instead."
+            )
+        return _strip_trailing_semicolon(sql, toks)
+
+    if not isinstance(root, READ_ONLY_NODES):
+        raise SqlNotAllowed(
+            f"this MCP is read-only; '{type(root).__name__}' statements "
+            "are not permitted. Run DDL/DML against the target via the "
+            "clickhousectl MCP instead."
+        )
+
+    body = _strip_trailing_semicolon(sql, toks)
+    if (
+        isinstance(root, (exp.Select, exp.Union, exp.Subquery))
+        and _existing_limit(root) is None
+    ):
+        body = f"{body}\nLIMIT {max_rows}"
+    return body
diff --git a/docker/migration-runner/migrationkit/__init__.py b/docker/migration-runner/migrationkit/__init__.py
index 0530dcb..59e1083 100644
--- a/docker/migration-runner/migrationkit/__init__.py
+++ b/docker/migration-runner/migrationkit/__init__.py
@@ -29,6 +29,7 @@
     PostgresSource,
     ClickHouseOssSource,
     BigQuerySource,
+    DatabricksSource,
 )
 from .sources.base import UnloadResult
 from .targets import ClickHouseTarget
@@ -48,6 +49,7 @@
     "PostgresSource",
     "ClickHouseOssSource",
     "BigQuerySource",
+    "DatabricksSource",
     "ClickHouseTarget",
     "S3Stage",
     "GCSStage",
diff --git a/docker/migration-runner/migrationkit/api.py b/docker/migration-runner/migrationkit/api.py
index a6ed913..0bbc87a 100644
--- a/docker/migration-runner/migrationkit/api.py
+++ b/docker/migration-runner/migrationkit/api.py
@@ -365,6 +365,9 @@ def list_source_databases(src: str, refresh: bool = False) -> list[str]:
         elif src == "bigquery":
             from .sources.bigquery import BigQuerySource
             dbs = BigQuerySource.list_databases_from_env()
+        elif src == "databricks":
+            from .sources.databricks import DatabricksSource
+            dbs = DatabricksSource.list_databases_from_env()
         else:
             raise HTTPException(
                 status_code=404,
diff --git a/docker/migration-runner/migrationkit/migrator.py b/docker/migration-runner/migrationkit/migrator.py
index db602d6..449432a 100644
--- a/docker/migration-runner/migrationkit/migrator.py
+++ b/docker/migration-runner/migrationkit/migrator.py
@@ -242,9 +242,9 @@ def add_table_via_s3(
         """Register a table for S3-staged migration: source unloads to
         S3, then ClickHouse Cloud loads via `INSERT FROM s3(...)`.
 
-        Only sources that override `Source.unload_to_s3()` (Snowflake
-        and ClickHouse OSS today) support this path — Migrator validates
-        at `run()` time."""
+        Only sources that override `Source.unload_to_s3()` (Snowflake,
+        ClickHouse OSS, and Databricks today) support this path —
+        Migrator validates at `run()` time."""
         resolved_target = target_table or name
         _validate_target_table_name(resolved_target)
         plan = _S3TablePlan(
diff --git a/docker/migration-runner/migrationkit/sources/__init__.py b/docker/migration-runner/migrationkit/sources/__init__.py
index 5f9d716..edb0558 100644
--- a/docker/migration-runner/migrationkit/sources/__init__.py
+++ b/docker/migration-runner/migrationkit/sources/__init__.py
@@ -3,6 +3,7 @@
 from .postgres import PostgresSource
 from .clickhouse_oss import ClickHouseOssSource
 from .bigquery import BigQuerySource
+from .databricks import DatabricksSource
 
 __all__ = [
     "Source",
@@ -10,4 +11,5 @@
     "PostgresSource",
     "ClickHouseOssSource",
     "BigQuerySource",
+    "DatabricksSource",
 ]
diff --git a/docker/migration-runner/migrationkit/sources/base.py b/docker/migration-runner/migrationkit/sources/base.py
index dcd32a9..dfb308e 100644
--- a/docker/migration-runner/migrationkit/sources/base.py
+++ b/docker/migration-runner/migrationkit/sources/base.py
@@ -48,6 +48,9 @@ def execute_and_count(self, sql: str) -> tuple[int, float | None, float]:
                         keyed on the session's `cursor.sfqid`
           - Postgres:   `EXPLAIN (ANALYZE, FORMAT JSON)` → `Execution Time`
           - BigQuery:   (planned) `jobs.get` totalSlotMs / endTime-startTime
+          - Databricks: SQL query-history REST API keyed on `cursor.query_id`,
+                        falling back to `system.query.history`; `None` if
+                        neither is available
 
         `server_ms` may be `None` only when the engine genuinely can't
         return a server-side timing for this query — callers fall back
diff --git a/docker/migration-runner/migrationkit/sources/databricks.py b/docker/migration-runner/migrationkit/sources/databricks.py
new file mode 100644
index 0000000..e8c9a81
--- /dev/null
+++ b/docker/migration-runner/migrationkit/sources/databricks.py
@@ -0,0 +1,304 @@
+"""Databricks SQL warehouse as a migration source.
+
+Mirrors SnowflakeSource: direct batch reads for small tables, plus an
+S3 staging path for large facts. Unity Catalog is three-level
+(catalog.schema.table) but the playground models one "source database"
+per run, so DATABRICKS_NAMESPACE carries "<catalog>.<schema>" and
+`self.database` is that dotted string.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Iterator, TYPE_CHECKING
+
+from .base import Source, UnloadResult
+
+if TYPE_CHECKING:
+    from ..staging.s3 import S3Stage
+
+
+def split_namespace(namespace: str) -> tuple[str, str]:
+    """Split `"<catalog>.<schema>"` into its two parts."""
+    parts = [p.strip() for p in (namespace or "").split(".") if p.strip()]
+    if len(parts) != 2:
+        raise ValueError(
+            "DATABRICKS_NAMESPACE must be '<catalog>.<schema>' "
+            f"(e.g. migration_demo.tpch), got {namespace!r}"
+        )
+    return parts[0], parts[1]
+
+
+def normalize_host(raw: str) -> str:
+    """Bare hostname. The connector's `server_hostname` rejects a scheme."""
+    host = (raw or "").strip()
+    return host.removeprefix("https://").removeprefix("http://").rstrip("/")
+
+
+def parquet_only(objects: list) -> list:
+    """Keep only Parquet part-files.
+
+    Databricks' commit protocol writes `_committed_*`, `_started_*` and
+    `_SUCCESS` markers alongside the data. Counting them would inflate the
+    file count and byte total the dashboard shows for the unload phase.
+    """
+    return [o for o in objects if o.key.lower().endswith(".parquet")]
+
+
+class DatabricksSource(Source):
+    source_type = "databricks"
+
+    def __init__(
+        self,
+        server_hostname: str,
+        http_path: str,
+        access_token: str,
+        catalog: str | None = None,
+        schema: str | None = None,
+    ) -> None:
+        from databricks import sql as dbsql
+
+        self.catalog = catalog
+        self.schema = schema
+        self.database = f"{catalog}.{schema}" if catalog and schema else None
+        self._host = normalize_host(server_hostname)
+        self._token = access_token
+        self._conn = dbsql.connect(
+            server_hostname=self._host,
+            http_path=http_path,
+            access_token=access_token,
+            catalog=catalog,
+            schema=schema,
+        )
+
+    @classmethod
+    def from_env(cls) -> "DatabricksSource":
+        catalog = schema = None
+        namespace = os.environ.get("DATABRICKS_NAMESPACE")
+        if namespace:
+            catalog, schema = split_namespace(namespace)
+        return cls(
+            server_hostname=os.environ["DATABRICKS_HOST"],
+            http_path=os.environ["DATABRICKS_HTTP_PATH"],
+            access_token=os.environ["DATABRICKS_TOKEN"],
+            catalog=catalog,
+            schema=schema,
+        )
+
+    @classmethod
+    def list_databases_from_env(cls) -> list[str]:
+        """Return `catalog.schema` pairs visible to the env credentials.
+
+        Backs the dashboard's source-database dropdown. Every value is
+        also a usable SQL prefix, which is why the pair is returned as one
+        dotted string rather than a nested structure.
+        """
+        from databricks import sql as dbsql
+
+        conn = dbsql.connect(
+            server_hostname=normalize_host(os.environ["DATABRICKS_HOST"]),
+            http_path=os.environ["DATABRICKS_HTTP_PATH"],
+            access_token=os.environ["DATABRICKS_TOKEN"],
+        )
+        try:
+            cur = conn.cursor()
+            try:
+                cur.execute(
+                    "SELECT catalog_name, schema_name "
+                    "FROM system.information_schema.schemata "
+                    "WHERE schema_name <> 'information_schema' "
+                    "ORDER BY catalog_name, schema_name"
+                )
+                return [f"{row[0]}.{row[1]}" for row in cur.fetchall()]
+            finally:
+                cur.close()
+        finally:
+            conn.close()
+
+    def _fq(self, table: str) -> str:
+        """Fully-qualify a bare table name against the run's namespace."""
+        if "." in table:
+            return table
+        if not (self.catalog and self.schema):
+            raise ValueError(
+                f"table {table!r} is unqualified and no DATABRICKS_NAMESPACE "
+                f"is set — pass '<catalog>.<schema>.{table}' instead"
+            )
+        return f"{self.catalog}.{self.schema}.{table}"
+
+    def count_rows(self, query: str) -> int:
+        cur = self._conn.cursor()
+        try:
+            cur.execute(f"SELECT count(*) FROM ({query})")
+            (n,) = cur.fetchone()
+            return int(n)
+        finally:
+            cur.close()
+
+    def iter_batches(
+        self, query: str, batch_size: int
+    ) -> Iterator[list[dict[str, Any]]]:
+        cur = self._conn.cursor()
+        try:
+            cur.execute(query)
+            columns = [c[0].lower() for c in cur.description]
+            while True:
+                rows = cur.fetchmany(batch_size)
+                if not rows:
+                    return
+                yield [dict(zip(columns, row)) for row in rows]
+        finally:
+            cur.close()
+
+    def execute_and_count(self, sql: str) -> tuple[int, float | None, float]:
+        cur = self._conn.cursor()
+        try:
+            t0 = time.monotonic()
+            cur.execute(sql)
+            rows = cur.fetchall()
+            wall_ms = (time.monotonic() - t0) * 1000.0
+            statement_id = getattr(cur, "query_id", None)
+        finally:
+            cur.close()
+        server_ms = self._fetch_server_ms(statement_id) if statement_id else None
+        return len(rows), server_ms, wall_ms
+
+    def _fetch_server_ms(self, statement_id: str) -> float | None:
+        """Server-side execution time in ms, or None.
+
+        Three tiers, because no single surface is reliable: the SQL query
+        history REST API is near-instant but its response shape is not
+        contractually stable; `system.query.history` is stable but can lag
+        by minutes and may not be enabled. Returning None is explicitly
+        permitted by the Source ABC — Benchmarker falls back to wall_ms.
+        """
+        for attempt in range(2):
+            ms = self._server_ms_from_history_api(statement_id)
+            if ms is not None:
+                return ms
+            if attempt == 0:
+                time.sleep(0.25)
+        return self._server_ms_from_system_table(statement_id)
+
+    def _server_ms_from_history_api(self, statement_id: str) -> float | None:
+        """Returns a float or None — never raises, even for a malformed or
+        hostile response body. The response shape is a guess against a
+        live API (see module docstring / _fetch_server_ms), so both the
+        network call *and* the body-processing that follows it must
+        degrade to None rather than let an AttributeError/TypeError
+        escape and fail the whole benchmark row."""
+        try:
+            filter_by = json.dumps({"statement_ids": [statement_id]})
+            query = urllib.parse.urlencode({"filter_by": filter_by})
+            url = f"https://{self._host}/api/2.0/sql/history/queries?{query}"
+            request = urllib.request.Request(
+                url, headers={"Authorization": f"Bearer {self._token}"}
+            )
+            with urllib.request.urlopen(request, timeout=10) as response:
+                body = json.load(response)
+            for item in body.get("res") or []:
+                metrics = item.get("metrics") or {}
+                for key in ("execution_time_ms", "total_time_ms"):
+                    if metrics.get(key) is not None:
+                        return float(metrics[key])
+                if item.get("duration") is not None:
+                    return float(item["duration"])
+            return None
+        except Exception:
+            return None
+
+    def _server_ms_from_system_table(self, statement_id: str) -> float | None:
+        # NOTE: deviates from the brief, which interpolated statement_id
+        # into the SQL string with an f-string. statement_id comes from
+        # the connector (cursor.query_id), not user input, but the
+        # connector supports native positional binding (`?` placeholders,
+        # documented for databricks-sql-connector 3.0.0+), so we use that
+        # instead of hand-rolled string interpolation.
+        sql = (
+            "SELECT execution_duration_ms, total_duration_ms "
+            "FROM system.query.history "
+            "WHERE statement_id = ? LIMIT 1"
+        )
+        try:
+            cur = self._conn.cursor()
+            try:
+                cur.execute(sql, [statement_id])
+                row = cur.fetchone()
+            finally:
+                cur.close()
+        except Exception:
+            return None
+        if not row:
+            return None
+        for value in row:
+            if value is not None:
+                return float(value)
+        return None
+
+    def unload_to_s3(
+        self,
+        table: str,
+        stage: "S3Stage",
+        run_id: str,
+        file_format: str = "parquet",
+    ) -> UnloadResult:
+        """Bulk-export `table` to the per-run S3 prefix with
+        `INSERT OVERWRITE DIRECTORY ... USING PARQUET`.
+
+        Requires a Unity Catalog external location over the staging bucket
+        with WRITE FILES granted to this principal — the `demo` Terraform
+        module provisions one. Idempotent: OVERWRITE replaces this table's
+        files without touching others in the run.
+        """
+        from ..staging.s3 import list_s3_objects
+
+        if file_format.lower() != "parquet":
+            raise ValueError(
+                f"unload_to_s3: only parquet is supported, got {file_format!r}"
+            )
+
+        # Resolve before the try so an unqualified `table` (usage error)
+        # raises its own ValueError instead of being caught below and
+        # re-wrapped as a misleading "permissions" RuntimeError.
+        fq_table = self._fq(table)
+
+        target_uri = stage.s3_uri(run_id, table)
+        cur = self._conn.cursor()
+        try:
+            t0 = time.monotonic()
+            try:
+                cur.execute(
+                    f"INSERT OVERWRITE DIRECTORY '{target_uri}'\n"
+                    f"USING PARQUET\n"
+                    f"SELECT * FROM {fq_table}"
+                )
+            except Exception as exc:
+                raise RuntimeError(
+                    f"Databricks refused to write Parquet to {target_uri}. "
+                    "The staging bucket needs a Unity Catalog external "
+                    "location with WRITE FILES granted to this principal — "
+                    "sources/databricks/terraform/demo provisions one when "
+                    "enable_s3_staging=true. Until then use "
+                    "Migrator.add_table() for this table; the direct path "
+                    f"needs no external location. Original error: {exc}"
+                ) from exc
+            seconds = round(time.monotonic() - t0, 3)
+        finally:
+            cur.close()
+
+        files = parquet_only(list_s3_objects(stage, run_id, table))
+        return UnloadResult(
+            file_count=len(files),
+            total_bytes=sum(f.size for f in files),
+            seconds=seconds,
+        )
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except Exception:
+            pass
diff --git a/docker/migration-runner/requirements.txt b/docker/migration-runner/requirements.txt
index 77633d3..9e25acb 100644
--- a/docker/migration-runner/requirements.txt
+++ b/docker/migration-runner/requirements.txt
@@ -10,3 +10,4 @@ google-cloud-bigquery>=3.21
 google-cloud-storage>=2.16
 db-dtypes>=1.2
 pymongo>=4.6
+databricks-sql-connector>=4.0
diff --git a/docs/adding-a-source.md b/docs/adding-a-source.md
index 2c30e13..eff8121 100644
--- a/docs/adding-a-source.md
+++ b/docs/adding-a-source.md
@@ -24,10 +24,23 @@ sources/
 │   ├── prompts/
 │   └── GUIDE.md
 │
-└── snowflake/                  ← Snowflake → ClickHouse Cloud  (cloud source — no docker/)
+├── snowflake/                   ← Snowflake → ClickHouse Cloud  (cloud source — no docker/)
+│   ├── queries/
+│   ├── scripts/
+│   ├── prompts/
+│   └── GUIDE.md
+│
+├── bigquery/                    ← BigQuery → ClickHouse Cloud  (cloud source — no docker/)
+│   ├── queries/
+│   ├── scripts/
+│   ├── prompts/
+│   └── GUIDE.md
+│
+└── databricks/                  ← Databricks → ClickHouse Cloud  (cloud source — no docker/)
     ├── queries/
     ├── scripts/
     ├── prompts/
+    ├── terraform/               ← optional demo/workspace provisioning
     └── GUIDE.md
 ```
 
@@ -58,7 +71,7 @@ The components fall into five groups:
 - **`migration-runner`** — multi-purpose service. Hosts:
   - **MCP server** on SSE: exposes `run_python`, `run_python_background`, `tail_python_job`, `write_workspace_file`, `read_workspace_file`, `list_workspace_files`. This is the agent's Python sandbox.
   - **FastAPI** on `:8001`: REST + SSE for the dashboard. Endpoints under `/api/mk/runs/*` and `/api/mk/sources/*`. Source manifests and conversation pre-creation live here too.
-  - **`migrationkit` Python library** (importable inside `run_python`): `Migrator`, `Validator`, `Benchmarker`, the `Source` ABC (with concrete `PostgresSource`, `SnowflakeSource`, `BigQuerySource`, `ClickHouseOssSource`), `ClickHouseTarget`, and `S3Stage` / `GCSStage` for object-storage staging paths.
+  - **`migrationkit` Python library** (importable inside `run_python`): `Migrator`, `Validator`, `Benchmarker`, the `Source` ABC (with concrete `PostgresSource`, `SnowflakeSource`, `BigQuerySource`, `DatabricksSource`, `ClickHouseOssSource`), `ClickHouseTarget`, and `S3Stage` / `GCSStage` for object-storage staging paths.
   - **SQLite WAL state store** at `/workspace/state/migrationkit.db`. Authoritative state across the stack: `runs`, `run_tables`, `events`, `batches`, `controls`, `validations`, `benchmarks`. Concurrent writers in the same container; readers via FastAPI.
 
 **Source MCP layer** — one MCP server per supported source, all exposed to LibreChat over SSE:
@@ -67,6 +80,7 @@ The components fall into five groups:
 - **`clickhouse-oss-mcp`** (`mcp-clickhouse`) — `run_select_query`.
 - **`snowflake-source`** (`snowflake-labs/mcp`) + **`snowflake-source-shim`** — the shim is a Python proxy that strips JSON-Schema fields (`exclusiveMaximum`, `const`, `oneOf`, `allOf`, `$schema`) that Gemini's function-calling API rejects. LibreChat connects to the shim, not the upstream MCP.
 - **`bigquery-source`** (Google MCP toolbox) — `bigquery-list-dataset-ids`, `bigquery-list-table-ids`, `bigquery-get-table-info`, plus `INFORMATION_SCHEMA` access.
+- **`databricks-mcp`** (`docker/databricks-mcp`, purpose-built in-repo) — `list_catalogs`, `list_schemas`, `list_tables`, `describe_table`, `run_select_query`. Databricks publishes no introspect-and-SELECT MCP for SQL warehouses (their own `databricks-mcp` package is an OAuth helper for the hosted UC-functions / vector-search / Genie servers, not this), so this one is authored in-repo, in the same spirit as `clickhousectl-mcp`. Because we author its tool schemas directly, it needs no Gemini shim — unlike `snowflake-source`.
 
 **Target MCP — write-enabled:**
 
@@ -77,7 +91,7 @@ The components fall into five groups:
 - **`postgres`** — PostgreSQL 16 with `ecommerce` (~10M rows) and optional `tpch` (SF1) datasets.
 - **`clickhouse-oss`** — ClickHouse OSS with `analytics` (web events, ~12.2M rows) and optional `tpch` (SF1) datasets.
 
-Snowflake and BigQuery don't have bundled databases — the source MCPs connect to partner-provided cloud accounts.
+Snowflake, BigQuery, and Databricks don't have bundled databases — the source MCPs connect to partner-provided cloud accounts.
 
 ---
 
@@ -87,7 +101,7 @@ Snowflake and BigQuery don't have bundled databases — the source MCPs connect
 
 ### MCP tools
 
-Exposed via SSE to LibreChat. All four agents attach this MCP.
+Exposed via SSE to LibreChat. All five agents attach this MCP.
 
 | Tool | Use for |
 |---|---|
@@ -97,7 +111,7 @@ Exposed via SSE to LibreChat. All four agents attach this MCP.
 | `write_workspace_file(path, content)` | Writes a file under `/workspace/`. The agent uses this to persist the migration script before dispatching it. |
 | `read_workspace_file(path)` / `list_workspace_files()` | Read-only file ops on `/workspace/`. |
 
-**Why dispatch + ONE tail instead of polling:** every `tail_python_job` call replays the full conversation context to the LLM — repeated polling burns tokens quadratically with no UX benefit. The dashboard's Migration tab already streams per-table progress via SSE; the agent's job is to dispatch + stop, and the partner watches the dashboard. This is enforced in every source's `sources/<id>/prompts/02-migrate-data.md` and in the system prompts at `librechat/sources/{snowflake,bigquery}-instructions.md`.
+**Why dispatch + ONE tail instead of polling:** every `tail_python_job` call replays the full conversation context to the LLM — repeated polling burns tokens quadratically with no UX benefit. The dashboard's Migration tab already streams per-table progress via SSE; the agent's job is to dispatch + stop, and the partner watches the dashboard. This is enforced in every source's `sources/<id>/prompts/02-migrate-data.md` and in the system prompts at `librechat/sources/{snowflake,bigquery,databricks}-instructions.md`.
 
 ### FastAPI HTTP surface
 
@@ -135,7 +149,7 @@ The Python library inside the runner that handles data movement. Critical pieces
 ```python
 from migrationkit import (
     Migrator, Validator, Benchmarker,
-    PostgresSource, SnowflakeSource, BigQuerySource, ClickHouseOssSource,
+    PostgresSource, SnowflakeSource, BigQuerySource, DatabricksSource, ClickHouseOssSource,
     ClickHouseTarget,
     S3Stage, GCSStage,
 )
@@ -361,7 +375,12 @@ volumes:
   <source-name>-data:
 ```
 
-> **Port allocation:** Postgres MCP uses host port `8001`, ClickHouse OSS MCP uses `8002`. Use the next available port (e.g. `8003`) for a third source to avoid conflicts.
+> **Port allocation:** currently in use — `8001` Postgres MCP, `8002`
+> ClickHouse OSS MCP, `8003` clickhousectl MCP, `8004` Snowflake source,
+> `8005`/`8006` migration-runner (MCP / HTTP API), `8007` BigQuery
+> source, `8008` Databricks MCP, `8014` Snowflake's Gemini-compat shim.
+> Use the next available port (e.g. `8009`) for a new source to avoid
+> conflicts.
 
 Also add the new MCP service to LibreChat's `depends_on`:
 
@@ -428,6 +447,7 @@ Do **not** add the cloud MCP to LibreChat's `depends_on` with `service_healthy`
 | SQLite | `@modelcontextprotocol/server-sqlite` | Wraps with supergateway |
 | Snowflake | `@datawizardinc/mcp-snowflake-server` | Wraps with supergateway |
 | BigQuery | `@ergut/mcp-bigquery-server` | Wraps with supergateway |
+| Databricks | *(none suitable)* | Databricks publishes no introspect-and-SELECT MCP for SQL warehouses; see `docker/databricks-mcp` for a purpose-built one |
 | Redshift | use Postgres MCP with Redshift endpoint | Standard psycopg2 connection |
 
 > MCP package availability and names change frequently. Check [npmjs.com](https://www.npmjs.com) and [glama.ai/mcp/servers](https://glama.ai/mcp/servers) for the latest options before wiring up a new source.
@@ -623,11 +643,12 @@ The agent's behaviour is controlled by a set of modular instruction files. Edit
 
 | File | Purpose |
 |---|---|
-| [librechat/clickhouse-cloud-instructions.md](../librechat/clickhouse-cloud-instructions.md) | Base ClickHouse Cloud rules — injected into `mcpServers.clickhousectl.serverInstructions` (shared by all four agents). |
+| [librechat/clickhouse-cloud-instructions.md](../librechat/clickhouse-cloud-instructions.md) | Base ClickHouse Cloud rules — injected into `mcpServers.clickhousectl.serverInstructions` (shared by all five agents). |
 | `agent-skills/.../AGENTS.md` | ClickHouse best-practices skill (cloned from [ClickHouse/agent-skills](https://github.com/ClickHouse/agent-skills) as a submodule). Appended to the same `clickhousectl` instructions. |
 | [librechat/sources/postgres-instructions.md](../librechat/sources/postgres-instructions.md) | Postgres-specific rules. |
 | [librechat/sources/snowflake-instructions.md](../librechat/sources/snowflake-instructions.md) | Snowflake-specific rules. |
 | [librechat/sources/bigquery-instructions.md](../librechat/sources/bigquery-instructions.md) | BigQuery-specific rules. |
+| [librechat/sources/databricks-instructions.md](../librechat/sources/databricks-instructions.md) | Databricks-specific rules. |
 | [librechat/sources/clickhouse-oss-instructions.md](../librechat/sources/clickhouse-oss-instructions.md) | ClickHouse OSS-specific rules. |
 
 Each pre-built agent attaches exactly the MCPs for its source, so it transparently receives only the relevant `serverInstructions` — no per-agent `instructions` field is set. `make setup` rebuilds the injected blocks idempotently. **Don't edit anything below the `--- Migration Rules (auto-injected …) ---` marker in `librechat.yaml`**; the MCP-purpose blurb above the marker IS hand-editable.
@@ -658,15 +679,19 @@ make setup                 # first-time setup (submodules + agent skills + .env
 make up                    # start the playground (Postgres + ClickHouse OSS sources)
 make up-snowflake          # also start the Snowflake source MCP + Gemini shim
 make up-bigquery           # also start the BigQuery source MCP
+make up-databricks         # also start the Databricks source MCP (databricks-mcp)
 make snowflake-setup       # set up MIGRATION_DEMO.RETAIL workload in existing Snowflake (Path A)
 make snowflake-provision   # provision a fresh Snowflake demo env with Terraform (Path B)
+make databricks-setup      # seed migration_demo.tpch in an existing Databricks workspace (manual entry path)
+make databricks-provision  # provision the demo catalog/schema/warehouse into an existing workspace with Terraform
+make databricks-provision-workspace # provision a fresh serverless workspace, then chain into databricks-provision
 make tpch-data             # generate TPC-H SF1 .tbl files in workloads/tpch/data/sf1/
 make tpch-load-bigquery    # load TPC-H + augmentations into BigQuery
 make tpch-load-postgres    # load TPC-H into Postgres
 make tpch-load-clickhouse-oss # load TPC-H into the bundled ClickHouse OSS
 make down                  # stop without removing data
 make reset                 # destroy volumes and start fresh
-make reset-agent           # delete + recreate the four pre-built agents (after AGENT_PROVIDER/AGENT_MODEL changes in .env)
+make reset-agent           # delete + recreate the five pre-built agents (after AGENT_PROVIDER/AGENT_MODEL changes in .env)
 make health                # check all services are healthy
 make migration-status      # check progress of a running migration script (target row counts)
 make logs                  # tail all service logs
diff --git a/docs/architecture.mmd b/docs/architecture.mmd
index 84beb86..f8e86cd 100644
--- a/docs/architecture.mmd
+++ b/docs/architecture.mmd
@@ -42,6 +42,7 @@ flowchart TB
             sf_shim["snowflake-source-shim\n(Gemini schema-strip proxy)"]
             sf_mcp["snowflake-source\n(Snowflake-Labs MCP)"]
             bq_mcp["bigquery-source\n(Google MCP toolbox)"]
+            dbx_mcp["databricks-mcp\n(purpose-built, in-repo)"]
             chctl["clickhousectl-mcp\nrun_query · run_command\n(write-enabled CH Cloud MCP)"]
             sf_shim --> sf_mcp
         end
@@ -61,6 +62,7 @@ flowchart TB
             direction LR
             sf_acct[("Snowflake account")]
             bq_proj[("BigQuery project")]
+            dbx_ws[("Databricks workspace")]
         end
         subgraph staging["Optional object-storage staging"]
             direction LR
@@ -86,6 +88,7 @@ flowchart TB
     librechat <-->|"SSE"| ch_oss_mcp
     librechat <-->|"SSE"| sf_shim
     librechat <-->|"SSE"| bq_mcp
+    librechat <-->|"SSE"| dbx_mcp
     librechat <-->|"SSE"| chctl
 
     %% migrationkit data plane (read source, write target, write state)
@@ -95,6 +98,7 @@ flowchart TB
     migrationkit -->|"read"| ch_oss
     migrationkit -->|"read"| sf_acct
     migrationkit -->|"read"| bq_proj
+    migrationkit -->|"read"| dbx_ws
     migrationkit -->|"HTTPS INSERT"| ch_cloud
 
     %% Source-MCP backing-DB connections
@@ -102,6 +106,7 @@ flowchart TB
     ch_oss_mcp <--> ch_oss
     sf_mcp <-->|"snowflake-connector"| sf_acct
     bq_mcp <-->|"google-cloud-bigquery"| bq_proj
+    dbx_mcp <-->|"databricks-sql-connector"| dbx_ws
     chctl <-->|"HTTPS"| ch_cloud
 
     %% Optional staging paths (dashed)
@@ -119,10 +124,10 @@ flowchart TB
     classDef dbBox      fill:#f3e8ff,stroke:#9333ea,stroke-width:1.5px,color:#3b0764
     classDef stagingBox fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e
 
-    class llm,ch_cloud,sf_acct,bq_proj cloudBox
+    class llm,ch_cloud,sf_acct,bq_proj,dbx_ws cloudBox
     class s3,gcs stagingBox
     class partner hostNode
     class nginx,dashboard,librechat,mongo uiBox
     class runner_mcp,runner_api,runner_state,migrationkit runnerBox
-    class pg_mcp,ch_oss_mcp,sf_mcp,sf_shim,bq_mcp,chctl mcpBox
+    class pg_mcp,ch_oss_mcp,sf_mcp,sf_shim,bq_mcp,dbx_mcp,chctl mcpBox
     class pg,ch_oss dbBox
diff --git a/docs/architecture.png b/docs/architecture.png
index a39515d..f1682a7 100644
Binary files a/docs/architecture.png and b/docs/architecture.png differ
diff --git a/docs/migration-checklist.md b/docs/migration-checklist.md
index f29bcce..84b1de6 100644
--- a/docs/migration-checklist.md
+++ b/docs/migration-checklist.md
@@ -5,8 +5,8 @@ to track progress on a source → ClickHouse Cloud migration. The phases
 map 1:1 to the dashboard's six steps and to each source's
 `sources/<source>/prompts/01..06-*.md` files.
 
-This checklist is shared across all four supported sources (Snowflake,
-BigQuery, Postgres, ClickHouse OSS). The type-mapping table in Phase 2
+This checklist is shared across all five supported sources (Snowflake,
+BigQuery, Databricks, Postgres, ClickHouse OSS). The type-mapping table in Phase 2
 is written with **Postgres-specific** types as a concrete example;
 other source engines have analogous mappings — see the per-source
 prompts and `librechat/sources/<source>-instructions.md` for the
@@ -20,6 +20,7 @@ authoritative lists.
 - [ ] Query patterns analysed — WHERE / GROUP BY / JOIN columns identified
 - [ ] Source-engine-specific features listed for translation
       (VARIANT / Streams / Dynamic Tables for Snowflake; STRUCT / Materialized Views for BigQuery;
+       VARIANT / liquid clustering / deletion vectors for Databricks;
        JSONB / arrays / ENUMs for Postgres; AggregatingMergeTree / MVs for CH OSS)
 
 ## Phase 2 — ClickHouse Schema Design
diff --git a/librechat/librechat.yaml b/librechat/librechat.yaml
index 57ae809..a8d9cc6 100644
--- a/librechat/librechat.yaml
+++ b/librechat/librechat.yaml
@@ -22,6 +22,7 @@ mcpSettings:
     - snowflake-source
     - snowflake-source-shim
     - bigquery-source
+    - databricks-mcp
     - migration-runner
 mcpServers:
   postgres-source:
@@ -1519,18 +1520,256 @@ mcpServers:
 
       Bytes scanned during a migration session shows up on the partner's
       GCP bill — flag if the workload is large enough that this matters.
+  databricks-source:
+    type: sse
+    url: http://databricks-mcp:8000/sse
+    timeout: 60000
+    serverInstructions: |-
+      SOURCE Databricks SQL warehouse. Read-only — statements are guarded
+      so only SELECT / WITH / SHOW / DESCRIBE / EXPLAIN reach the
+      warehouse. Unity Catalog is three-level (catalog.schema.table); the
+      schema is unknown ahead of time, so discover it dynamically with
+      list_catalogs, list_schemas, list_tables, describe_table, and
+      run_select_query. Use this MCP — not migration-runner — for all
+      source introspection.
+
+      --- Migration Rules (auto-injected, do not edit below) ---
+
+      ## Databricks Source — Migration Instructions
+
+      This section applies when the SOURCE database is Databricks.
+
+      ---
+
+      ## Unity Catalog is Three-Level — Always Fully Qualify
+
+      Databricks names objects `catalog.schema.table`. ClickHouse has two levels
+      (`database.table`).
+
+      - **Always fully qualify** source tables in generated SQL and in
+        `migrationkit` `source_query=` values. A bare `orders` resolves against
+        whatever the connection's default namespace happens to be, which may not
+        be the namespace the partner selected.
+      - The playground's "source database" is the `catalog.schema` pair as one
+        dotted string (`DATABRICKS_NAMESPACE`, e.g. `migration_demo.tpch`). When
+        you see a single dotted value in a prompt, that is what it is.
+      - Identifiers are case-insensitive and stored lower-case. Quote with
+        backticks when a name needs it — never double quotes.
+
+      ---
+
+      ## Schema Discovery — Don't Assume Anything
+
+      Never assume column names, table names, types, or that any particular
+      Databricks feature is or is not in use. Discover the real schema at
+      runtime via the `databricks-source` MCP.
+
+      **Use `databricks-source` (not `migration-runner`) for all schema
+      discovery and read-only inspection.** `migration-runner`'s `run_python` is
+      **only** for data movement once the schema is understood. Reasons:
+
+      - `databricks-source` is workspace-scoped: `list_catalogs` returns every
+        catalog the principal can see, not just one default namespace.
+      - `migration-runner` inherits env vars from the playground's `.env` via
+        `env_file:`. A stale `DATABRICKS_NAMESPACE` there silently scopes a
+        connector session to the wrong catalog/schema and your inventory
+        quietly misses everything else.
+      - The MCP is guarded read-only, so introspection cannot mutate the source
+        even by accident.
+
+      **The discovery checklist for every Databricks migration:**
+
+      1. **List catalogs and schemas:**
+         `list_catalogs()` then `list_schemas(catalog)`.
+
+      2. **List tables with sizes:**
+         `list_tables(catalog, schema)` — returns `table_type`, `comment`,
+         `sizeInBytes`, `numFiles`. It deliberately does **not** return row
+         counts: Delta metadata doesn't carry them and a per-table `COUNT(*)`
+         would make the call slow.
+
+      3. **Get row counts in ONE query**, not one call per table:
+         ```sql
+         SELECT 'orders' AS t, count(*) AS n FROM <catalog>.<schema>.orders
+         UNION ALL SELECT 'lineitem', count(*) FROM <catalog>.<schema>.lineitem
+         ORDER BY n DESC
+         ```
+
+      4. **Full schema plus Delta detail per table:**
+         `describe_table(catalog, schema, table)`. Read all three sections of
+         the response — `describe_extended` for columns, `detail` for
+         clustering/partition columns and table features, `history` for whether
+         the table is actively mutated. Clustering columns and deletion-vector
+         state live only in `detail`.
+
+      5. **Inventory the source-specific features you actually found:**
+         ```sql
+         -- VARIANT / nested columns, generated columns, identity columns
+         SELECT column_name, full_data_type, is_nullable, generation_expression
+         FROM system.information_schema.columns
+         WHERE table_catalog = '<catalog>' AND table_schema = '<schema>'
+         ORDER BY table_name, ordinal_position
+         ```
+         ```sql
+         -- Materialized views and streaming tables are separate object types;
+         -- a table listing alone misses them.
+         SELECT table_name, table_type
+         FROM system.information_schema.tables
+         WHERE table_catalog = '<catalog>' AND table_schema = '<schema>'
+         ```
+
+      6. **Sample data and check nullability + cardinality** for every column
+         before choosing types. This is what tells you whether a column is
+         `Nullable(T)`, whether a string is a `LowCardinality(String)`
+         candidate, and whether a `DECIMAL` needs full precision:
+         ```sql
+         SELECT * FROM <catalog>.<schema>.<table> LIMIT 5
+         SELECT count(*), count(<col>), count(DISTINCT <col>) FROM <catalog>.<schema>.<table>
+         ```
+
+      7. **Read the partner's queries.** `ORDER BY` key selection on the
+         ClickHouse side comes from the columns in WHERE / JOIN / GROUP BY of
+         the actual workload — **not** from the source's `CLUSTER BY` columns.
+
+      Produce a migration inventory before generating any target schema.
+
+      ---
+
+      ## Databricks → ClickHouse Type Mapping
+
+      | Databricks | ClickHouse | Notes |
+      |---|---|---|
+      | `BOOLEAN` | `Bool` | |
+      | `TINYINT` / `SMALLINT` / `INT` / `BIGINT` | `Int8` / `Int16` / `Int32` / `Int64` | Databricks integers are always signed |
+      | `FLOAT` / `DOUBLE` | `Float32` / `Float64` | |
+      | `DECIMAL(p, s)` | `Decimal(p, s)` | **Never** `Float64` — TPC-H money columns need exact arithmetic |
+      | `STRING` | `String`, or `LowCardinality(String)` | Use `LowCardinality` below ~10k distinct values |
+      | `BINARY` | `String` | |
+      | `DATE` | `Date32` | `Date` only reaches 2149 and starts at 1970 |
+      | `TIMESTAMP` | `DateTime64(6, 'UTC')` | Databricks `TIMESTAMP` is instant-with-timezone; normalise to UTC at the source |
+      | `TIMESTAMP_NTZ` | `DateTime64(6)` | No timezone — do **not** attach one |
+      | `INTERVAL` | `Int64` seconds, or `String` | No native equivalent; state the unit in a comment |
+      | `ARRAY<T>` | `Array(T)` | |
+      | `MAP<K, V>` | `Map(K, V)` | Missing-key lookup returns the type default, not NULL |
+      | `STRUCT<a: T, …>` | named `Tuple(a T, …)` | Positional in ClickHouse — field order matters |
+      | `ARRAY<STRUCT<…>>` | `Nested(...)` or `Array(Tuple(...))` | `Nested` is easier to query; `Array(Tuple)` is easier to insert |
+      | `VARIANT` | `JSON`, or hot keys extracted to typed columns | Extracting the 2–3 keys the workload filters on usually beats a whole `JSON` column |
+      | generated column | `MATERIALIZED` or `ALIAS` | `MATERIALIZED` stores it, `ALIAS` recomputes on read |
+      | identity column | `Int64` + no auto-generation | ClickHouse has no identity; the migrated values are what you keep |
+
+      **Nullability:** `system.information_schema.columns.is_nullable` is
+      authoritative. Either declare `Nullable(<T>)` on the target, or declare
+      non-Nullable with an explicit `DEFAULT` **and** map `None` to that default
+      in a step-2 `transform=`. A non-Nullable target column with neither fails
+      mid-batch on the first NULL.
+
+      ---
+
+      ## Delta / Unity Catalog Objects — Migration Patterns
+
+      ### Liquid clustering (`CLUSTER BY`)
+      Not an index and not a sort order you can copy. Treat it as a hint about
+      which columns the workload filters on, then choose the ClickHouse
+      `ORDER BY` from the actual queries. Say in chat when your choice differs
+      from the source clustering and why.
+
+      ### Deletion vectors
+      Deletes are recorded as vectors rather than rewritten files, so a table can
+      report rows that a `SELECT` won't return. Two consequences: source
+      `COUNT(*)` is the only trustworthy count (never sum file statistics), and a
+      table being actively deleted from can legitimately change count mid-run.
+
+      ### Time travel (`VERSION AS OF` / `TIMESTAMP AS OF`)
+      No ClickHouse equivalent. Use it to pin a consistent read for the
+      migration itself (`SELECT * FROM t VERSION AS OF <v>`) so a concurrent
+      write doesn't skew validation. Do not try to reproduce the history.
+
+      ### Materialized views and streaming tables
+      Recreate as a ClickHouse Materialized View over an `AggregatingMergeTree`,
+      and **backfill** it from the base table after loading — an MV only sees
+      rows inserted after it exists. Get the defining query from
+      `describe_table`'s extended output.
+
+      ### Change Data Feed (`delta.enableChangeDataFeed`)
+      Ongoing CDC is out of scope for a one-shot migration. If the partner needs
+      it, the answer is ClickPipes or a `ReplacingMergeTree` with a version
+      column — say so and move on rather than half-building it.
+
+      ### Unity Catalog volumes and external locations
+      Only relevant to the S3 staging path. A `/Volumes/...` path is not
+      readable by ClickHouse; the staged unload writes to `s3://` directly.
+
+      ---
+
+      ## Migration Script Rules
+
+      - Connect with `DatabricksSource.from_env()`. Never construct
+        `databricks.sql.connect(...)` by hand in a generated script — the
+        helper owns namespace splitting and host normalisation.
+      - Fully qualify every `source_query=`.
+      - Row dict keys are **lower-case**; `iter_batches` lowercases them.
+      - `batch_size` ~100k narrow, ~25–50k for rows carrying VARIANT or
+        `ARRAY<STRUCT>`. Never above 500k.
+      - **S3 staging requires a Unity Catalog external location** over the
+        staging bucket with `WRITE FILES` granted. `unload_to_s3` raises a
+        message saying exactly that; fall back to `add_table()` per table.
+      - **Target column order must match the source** for staged tables — that
+        path is `INSERT INTO … SELECT * FROM s3(...)`, which is positional.
+      - The staged path supports neither `batch_size` nor `transform`. Any
+        table needing per-row transformation uses the direct path.
+
+      ---
+
+      ## Query Rewriting Notes
+
+      | Databricks | ClickHouse |
+      |---|---|
+      | `QUALIFY <pred>` | subquery + `WHERE` over the window |
+      | `LATERAL VIEW explode(arr) AS x` | `ARRAY JOIN` / `arrayJoin(arr)` |
+      | `transform(arr, x -> f(x))` | `arrayMap(x -> f(x), arr)` (order flips) |
+      | `filter(arr, x -> p(x))` | `arrayFilter(x -> p(x), arr)` (order flips) |
+      | `aggregate(arr, 0, (a, x) -> a + x)` | `arraySum(arr)` / `arrayReduce('sum', arr)` |
+      | `v:a.b` / `variant_get(v, '$.a')` | `JSONExtract*(v, 'a')`, or `v.a` on a `JSON` column |
+      | `named_struct('a', 1)` | `tuple(1)` — positional |
+      | `try_divide(a, b)` | `if(b = 0, NULL, a / b)` — `/` returns `inf`, not NULL |
+      | `try_cast(x AS t)` | `accurateCastOrNull(x, 't')` |
+      | `datediff(a, b)` | `dateDiff('day', b, a)` — order flips |
+      | `date_trunc('month', d)` | `toStartOfMonth(d)` |
+      | `SEMI JOIN` / `ANTI JOIN` | `LEFT SEMI JOIN` / `LEFT ANTI JOIN` |
+      | `catalog.schema.table` | `database.table` |
+
+      State `NULLS FIRST` / `NULLS LAST` explicitly — the engines' defaults differ.
+
+      ---
+
+      ## Known Gotchas
+
+      - **Cold warehouse.** A stopped SQL warehouse takes 30s+ to serve its
+        first statement. Never present that as query latency; run a throwaway
+        `SELECT 1` before benchmarking.
+      - **`samples` catalog is read-only.** Copy out of it, never into it.
+      - **`VARIANT` needs DBSQL 2024.35+ / DBR 15.3+.** On older runtimes the
+        column type simply doesn't exist.
+      - **`system.query.history` can lag** by minutes and may be disabled, so
+        `server_ms` is sometimes `None`. Report wall-clock as wall-clock.
+      - **Auto-stopped warehouse mid-migration.** A long direct-path migration
+        keeps the connection busy, but a paused run can let the warehouse stop;
+        resuming pays cold-start again. Expected, not a bug.
   migration-runner:
     type: sse
     url: http://migration-runner:8000/sse
     timeout: 900000
     serverInstructions: |-
       Execute Python migration scripts inside the playground. Pre-installed:
-      snowflake-connector-python, psycopg2, clickhouse-connect, pyarrow.
+      snowflake-connector-python, psycopg2, clickhouse-connect, pyarrow,
+      databricks-sql-connector.
       Reachable hosts: postgres:5432, clickhouse-oss:8123, Snowflake (via
-      SNOWFLAKE_* env vars), ClickHouse Cloud (via CLICKHOUSE_CLOUD_*).
+      SNOWFLAKE_* env vars), Databricks (via DATABRICKS_* env vars),
+      ClickHouse Cloud (via CLICKHOUSE_CLOUD_*).
       Tools:
         - run_python(code, timeout_seconds=600) -> {stdout, stderr, exit_code, duration_seconds}
         - write_workspace_file(path, content) / read_workspace_file(path) / list_workspace_files()
-      Use this when the source is Snowflake (see snowflake-instructions.md).
+      Use this for any source's migration scripts (see that source's
+      *-instructions.md).
       Stream long outputs to the user. On errors, surface the full traceback
       and propose a fix before retrying.
diff --git a/librechat/sources/databricks-instructions.md b/librechat/sources/databricks-instructions.md
new file mode 100644
index 0000000..e4b76d3
--- /dev/null
+++ b/librechat/sources/databricks-instructions.md
@@ -0,0 +1,220 @@
+## Databricks Source — Migration Instructions
+
+This section applies when the SOURCE database is Databricks.
+
+---
+
+## Unity Catalog is Three-Level — Always Fully Qualify
+
+Databricks names objects `catalog.schema.table`. ClickHouse has two levels
+(`database.table`).
+
+- **Always fully qualify** source tables in generated SQL and in
+  `migrationkit` `source_query=` values. A bare `orders` resolves against
+  whatever the connection's default namespace happens to be, which may not
+  be the namespace the partner selected.
+- The playground's "source database" is the `catalog.schema` pair as one
+  dotted string (`DATABRICKS_NAMESPACE`, e.g. `migration_demo.tpch`). When
+  you see a single dotted value in a prompt, that is what it is.
+- Identifiers are case-insensitive and stored lower-case. Quote with
+  backticks when a name needs it — never double quotes.
+
+---
+
+## Schema Discovery — Don't Assume Anything
+
+Never assume column names, table names, types, or that any particular
+Databricks feature is or is not in use. Discover the real schema at
+runtime via the `databricks-source` MCP.
+
+**Use `databricks-source` (not `migration-runner`) for all schema
+discovery and read-only inspection.** `migration-runner`'s `run_python` is
+**only** for data movement once the schema is understood. Reasons:
+
+- `databricks-source` is workspace-scoped: `list_catalogs` returns every
+  catalog the principal can see, not just one default namespace.
+- `migration-runner` inherits env vars from the playground's `.env` via
+  `env_file:`. A stale `DATABRICKS_NAMESPACE` there silently scopes a
+  connector session to the wrong catalog/schema and your inventory
+  quietly misses everything else.
+- The MCP is guarded read-only, so introspection cannot mutate the source
+  even by accident.
+
+**The discovery checklist for every Databricks migration:**
+
+1. **List catalogs and schemas:**
+   `list_catalogs()` then `list_schemas(catalog)`.
+
+2. **List tables with sizes:**
+   `list_tables(catalog, schema)` — returns `table_type`, `comment`,
+   `sizeInBytes`, `numFiles`. It deliberately does **not** return row
+   counts: Delta metadata doesn't carry them and a per-table `COUNT(*)`
+   would make the call slow.
+
+3. **Get row counts in ONE query**, not one call per table:
+   ```sql
+   SELECT 'orders' AS t, count(*) AS n FROM <catalog>.<schema>.orders
+   UNION ALL SELECT 'lineitem', count(*) FROM <catalog>.<schema>.lineitem
+   ORDER BY n DESC
+   ```
+
+4. **Full schema plus Delta detail per table:**
+   `describe_table(catalog, schema, table)`. Read all three sections of
+   the response — `describe_extended` for columns, `detail` for
+   clustering/partition columns and table features, `history` for whether
+   the table is actively mutated. Clustering columns and deletion-vector
+   state live only in `detail`.
+
+5. **Inventory the source-specific features you actually found:**
+   ```sql
+   -- VARIANT / nested columns, generated columns, identity columns
+   SELECT column_name, full_data_type, is_nullable, generation_expression
+   FROM system.information_schema.columns
+   WHERE table_catalog = '<catalog>' AND table_schema = '<schema>'
+   ORDER BY table_name, ordinal_position
+   ```
+   ```sql
+   -- Materialized views and streaming tables are separate object types;
+   -- a table listing alone misses them.
+   SELECT table_name, table_type
+   FROM system.information_schema.tables
+   WHERE table_catalog = '<catalog>' AND table_schema = '<schema>'
+   ```
+
+6. **Sample data and check nullability + cardinality** for every column
+   before choosing types. This is what tells you whether a column is
+   `Nullable(T)`, whether a string is a `LowCardinality(String)`
+   candidate, and whether a `DECIMAL` needs full precision:
+   ```sql
+   SELECT * FROM <catalog>.<schema>.<table> LIMIT 5
+   SELECT count(*), count(<col>), count(DISTINCT <col>) FROM <catalog>.<schema>.<table>
+   ```
+
+7. **Read the partner's queries.** `ORDER BY` key selection on the
+   ClickHouse side comes from the columns in WHERE / JOIN / GROUP BY of
+   the actual workload — **not** from the source's `CLUSTER BY` columns.
+
+Produce a migration inventory before generating any target schema.
+
+---
+
+## Databricks → ClickHouse Type Mapping
+
+| Databricks | ClickHouse | Notes |
+|---|---|---|
+| `BOOLEAN` | `Bool` | |
+| `TINYINT` / `SMALLINT` / `INT` / `BIGINT` | `Int8` / `Int16` / `Int32` / `Int64` | Databricks integers are always signed |
+| `FLOAT` / `DOUBLE` | `Float32` / `Float64` | |
+| `DECIMAL(p, s)` | `Decimal(p, s)` | **Never** `Float64` — TPC-H money columns need exact arithmetic |
+| `STRING` | `String`, or `LowCardinality(String)` | Use `LowCardinality` below ~10k distinct values |
+| `BINARY` | `String` | |
+| `DATE` | `Date32` | `Date` only reaches 2149 and starts at 1970 |
+| `TIMESTAMP` | `DateTime64(6, 'UTC')` | Databricks `TIMESTAMP` is instant-with-timezone; normalise to UTC at the source |
+| `TIMESTAMP_NTZ` | `DateTime64(6)` | No timezone — do **not** attach one |
+| `INTERVAL` | `Int64` seconds, or `String` | No native equivalent; state the unit in a comment |
+| `ARRAY<T>` | `Array(T)` | |
+| `MAP<K, V>` | `Map(K, V)` | Missing-key lookup returns the type default, not NULL |
+| `STRUCT<a: T, …>` | named `Tuple(a T, …)` | Positional in ClickHouse — field order matters |
+| `ARRAY<STRUCT<…>>` | `Nested(...)` or `Array(Tuple(...))` | `Nested` is easier to query; `Array(Tuple)` is easier to insert |
+| `VARIANT` | `JSON`, or hot keys extracted to typed columns | Extracting the 2–3 keys the workload filters on usually beats a whole `JSON` column |
+| generated column | `MATERIALIZED` or `ALIAS` | `MATERIALIZED` stores it, `ALIAS` recomputes on read |
+| identity column | `Int64` + no auto-generation | ClickHouse has no identity; the migrated values are what you keep |
+
+**Nullability:** `system.information_schema.columns.is_nullable` is
+authoritative. Either declare `Nullable(<T>)` on the target, or declare
+non-Nullable with an explicit `DEFAULT` **and** map `None` to that default
+in a step-2 `transform=`. A non-Nullable target column with neither fails
+mid-batch on the first NULL.
+
+---
+
+## Delta / Unity Catalog Objects — Migration Patterns
+
+### Liquid clustering (`CLUSTER BY`)
+Not an index and not a sort order you can copy. Treat it as a hint about
+which columns the workload filters on, then choose the ClickHouse
+`ORDER BY` from the actual queries. Say in chat when your choice differs
+from the source clustering and why.
+
+### Deletion vectors
+Deletes are recorded as vectors rather than rewritten files, so a table can
+report rows that a `SELECT` won't return. Two consequences: source
+`COUNT(*)` is the only trustworthy count (never sum file statistics), and a
+table being actively deleted from can legitimately change count mid-run.
+
+### Time travel (`VERSION AS OF` / `TIMESTAMP AS OF`)
+No ClickHouse equivalent. Use it to pin a consistent read for the
+migration itself (`SELECT * FROM t VERSION AS OF <v>`) so a concurrent
+write doesn't skew validation. Do not try to reproduce the history.
+
+### Materialized views and streaming tables
+Recreate as a ClickHouse Materialized View over an `AggregatingMergeTree`,
+and **backfill** it from the base table after loading — an MV only sees
+rows inserted after it exists. Get the defining query from
+`describe_table`'s extended output.
+
+### Change Data Feed (`delta.enableChangeDataFeed`)
+Ongoing CDC is out of scope for a one-shot migration. If the partner needs
+it, the answer is ClickPipes or a `ReplacingMergeTree` with a version
+column — say so and move on rather than half-building it.
+
+### Unity Catalog volumes and external locations
+Only relevant to the S3 staging path. A `/Volumes/...` path is not
+readable by ClickHouse; the staged unload writes to `s3://` directly.
+
+---
+
+## Migration Script Rules
+
+- Connect with `DatabricksSource.from_env()`. Never construct
+  `databricks.sql.connect(...)` by hand in a generated script — the
+  helper owns namespace splitting and host normalisation.
+- Fully qualify every `source_query=`.
+- Row dict keys are **lower-case**; `iter_batches` lowercases them.
+- `batch_size` ~100k narrow, ~25–50k for rows carrying VARIANT or
+  `ARRAY<STRUCT>`. Never above 500k.
+- **S3 staging requires a Unity Catalog external location** over the
+  staging bucket with `WRITE FILES` granted. `unload_to_s3` raises a
+  message saying exactly that; fall back to `add_table()` per table.
+- **Target column order must match the source** for staged tables — that
+  path is `INSERT INTO … SELECT * FROM s3(...)`, which is positional.
+- The staged path supports neither `batch_size` nor `transform`. Any
+  table needing per-row transformation uses the direct path.
+
+---
+
+## Query Rewriting Notes
+
+| Databricks | ClickHouse |
+|---|---|
+| `QUALIFY <pred>` | subquery + `WHERE` over the window |
+| `LATERAL VIEW explode(arr) AS x` | `ARRAY JOIN` / `arrayJoin(arr)` |
+| `transform(arr, x -> f(x))` | `arrayMap(x -> f(x), arr)` (order flips) |
+| `filter(arr, x -> p(x))` | `arrayFilter(x -> p(x), arr)` (order flips) |
+| `aggregate(arr, 0, (a, x) -> a + x)` | `arraySum(arr)` / `arrayReduce('sum', arr)` |
+| `v:a.b` / `variant_get(v, '$.a')` | `JSONExtract*(v, 'a')`, or `v.a` on a `JSON` column |
+| `named_struct('a', 1)` | `tuple(1)` — positional |
+| `try_divide(a, b)` | `if(b = 0, NULL, a / b)` — `/` returns `inf`, not NULL |
+| `try_cast(x AS t)` | `accurateCastOrNull(x, 't')` |
+| `datediff(a, b)` | `dateDiff('day', b, a)` — order flips |
+| `date_trunc('month', d)` | `toStartOfMonth(d)` |
+| `SEMI JOIN` / `ANTI JOIN` | `LEFT SEMI JOIN` / `LEFT ANTI JOIN` |
+| `catalog.schema.table` | `database.table` |
+
+State `NULLS FIRST` / `NULLS LAST` explicitly — the engines' defaults differ.
+
+---
+
+## Known Gotchas
+
+- **Cold warehouse.** A stopped SQL warehouse takes 30s+ to serve its
+  first statement. Never present that as query latency; run a throwaway
+  `SELECT 1` before benchmarking.
+- **`samples` catalog is read-only.** Copy out of it, never into it.
+- **`VARIANT` needs DBSQL 2024.35+ / DBR 15.3+.** On older runtimes the
+  column type simply doesn't exist.
+- **`system.query.history` can lag** by minutes and may be disabled, so
+  `server_ms` is sometimes `None`. Report wall-clock as wall-clock.
+- **Auto-stopped warehouse mid-migration.** A long direct-path migration
+  keeps the connection busy, but a paused run can let the warehouse stop;
+  resuming pays cold-start again. Expected, not a bug.
diff --git a/scripts/build-librechat-runtime.sh b/scripts/build-librechat-runtime.sh
index d2ead10..cf274e4 100755
--- a/scripts/build-librechat-runtime.sh
+++ b/scripts/build-librechat-runtime.sh
@@ -15,6 +15,7 @@
 # Optional sources (gated by Compose profile -> only included when profile is active):
 #   snowflake-source -> profile "snowflake"
 #   bigquery-source  -> profile "bigquery"
+#   databricks-source -> profile "databricks"
 # All other MCPs are unconditional.
 
 set -euo pipefail
@@ -74,6 +75,14 @@ else
     removed+=("bigquery-source")
 fi
 
+# databricks-source: MCP key "databricks-source", host is databricks-mcp
+if is_active databricks; then
+    kept+=("databricks-source")
+else
+    drop_mcp "databricks-source" "databricks-mcp"
+    removed+=("databricks-source")
+fi
+
 echo "Runtime librechat config: $RUNTIME_FILE"
 echo "  Active profiles: ${profiles_csv:-<none>}"
 if [ ${#kept[@]} -gt 0 ]; then
diff --git a/scripts/reset-agent.sh b/scripts/reset-agent.sh
index a801d17..3d27229 100755
--- a/scripts/reset-agent.sh
+++ b/scripts/reset-agent.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Delete the four pre-built migration agents from MongoDB and re-run
+# Delete the five pre-built migration agents from MongoDB and re-run
 # librechat-init to recreate them. Use after changing AGENT_PROVIDER /
 # AGENT_MODEL (or any AGENT_PROVIDER_<SOURCE>) in .env, since the init
 # container's idempotency check skips agents that already match.
@@ -12,6 +12,7 @@ AGENTS=(
     "Snowflake → ClickHouse Cloud"
     "BigQuery → ClickHouse Cloud"
     "ClickHouse OSS → ClickHouse Cloud"
+    "Databricks → ClickHouse Cloud"
 )
 
 echo "This will delete these agents from MongoDB:"
@@ -27,7 +28,8 @@ docker compose exec -T mongodb mongosh "mongodb://mongodb:27017/LibreChat" --qui
             "Postgres → ClickHouse Cloud",
             "Snowflake → ClickHouse Cloud",
             "BigQuery → ClickHouse Cloud",
-            "ClickHouse OSS → ClickHouse Cloud"
+            "ClickHouse OSS → ClickHouse Cloud",
+            "Databricks → ClickHouse Cloud"
         ]}
     })
 '
@@ -47,6 +49,9 @@ if [ -z "${COMPOSE_PROFILES:-}" ]; then
     if grep -q '^bigquery-source$' <<<"$running"; then
         detected="${detected:+$detected,}bigquery"
     fi
+    if grep -q '^databricks-mcp$' <<<"$running"; then
+        detected="${detected:+$detected,}databricks"
+    fi
     export COMPOSE_PROFILES="$detected"
     echo "Detected active profiles: ${COMPOSE_PROFILES:-<none>}"
 fi
diff --git a/sources/databricks/GUIDE.md b/sources/databricks/GUIDE.md
new file mode 100644
index 0000000..27e64f7
--- /dev/null
+++ b/sources/databricks/GUIDE.md
@@ -0,0 +1,432 @@
+# Migration Guide — Databricks → ClickHouse Cloud
+
+This guide walks you through a complete Databricks → ClickHouse Cloud
+migration using the **MigrationRoom** dashboard. The dashboard
+orchestrates the work: you pick a source, click six step buttons in
+order, and watch the AI agent do each step live. The agent has MCP
+connections to your Databricks source (`databricks-mcp`, host port
+`8008`, Compose profile `databricks`), your ClickHouse Cloud target,
+an in-chat Python runtime, and the `migrationkit` Python library that
+handles data movement.
+
+**Demo workload:** `migration_demo.tpch` — TPC-H tables downsampled
+from the `samples.tpch` catalog every Databricks workspace ships with.
+`samples.tpch` is scale factor 1000 (~1 TB, ~6 billion `lineitem`
+rows); `setup_workload.sql`'s predicates cut it to SF1-equivalent
+cardinality (~6M `lineitem` rows), so this runs in minutes and the
+eventual ClickHouse Cloud migration moves megabytes, not terabytes.
+Eight Databricks-specific augmentations are layered on top so the agent
+has to make real decisions instead of a mechanical type-for-type copy:
+
+| Source object | ClickHouse decision |
+|---|---|
+| `orders.o_metadata` (VARIANT) | `JSON` column, or extract hot keys to typed columns |
+| `lineitem.l_shipping_events` (`ARRAY<STRUCT>`) | `Nested(...)`, or `Array(Tuple(...))` |
+| `lineitem.l_attributes` (`MAP<STRING, STRING>`) | `Map(String, String)` |
+| `lineitem.l_committed_at` / `l_committed_at_ntz` (`TIMESTAMP` / `TIMESTAMP_NTZ`) | `DateTime64(6, 'UTC')` / `DateTime64(6)` |
+| `lineitem` liquid clustering (`CLUSTER BY`) | `ORDER BY (...)` chosen from the actual queries |
+| `lineitem` deletion vectors | No equivalent; `ReplacingMergeTree`, ClickPipes, or defer |
+| `orders.o_orderyear` (`GENERATED ALWAYS AS`) | `MATERIALIZED` (stored) or `ALIAS` (computed) column |
+| `daily_order_summary` (materialized view, serverless-only) | ClickHouse Materialized View on `AggregatingMergeTree` |
+
+**Total time:** ~60 minutes including setup (estimate — see the
+Honesty section below; this flow has not been timed end-to-end
+against a live workspace).
+**Workflow:** the dashboard's six step buttons drive the migration. The
+prompt files in [prompts/](prompts/) are what each button fires — you
+don't need to paste them by hand.
+
+---
+
+## Phase 0 — Databricks setup (~5–20 min depending on path, estimate)
+
+Pick the entry point that matches what you already have. All three end
+with the same `migration_demo.tpch` workload sitting in a Databricks
+workspace and the four `DATABRICKS_*` variables in `.env`.
+
+### New Databricks environment
+
+You have no Databricks workspace at all. Terraform provisions a
+**serverless** workspace, then chains straight into the demo-object
+module below — one command, no copy-pasting a workspace URL between
+two applies.
+
+The one manual step: create a Databricks **account** (if you don't
+have one) and, in the account console
+(`accounts.cloud.databricks.com` → Settings → Identity and access →
+Service principals), an **account-admin** service principal. Terraform
+authenticates *as* this service principal, so it cannot also create
+it. Generate an OAuth secret and note the client ID and account UUID.
+
+```bash
+cd sources/databricks/terraform/workspace
+cp terraform.tfvars.example terraform.tfvars
+# Edit: databricks_account_id, databricks_client_id, databricks_client_secret
+
+cd ../../../..
+make databricks-provision-workspace
+```
+
+`make databricks-provision-workspace` runs the `workspace` module,
+then the `demo` module against the workspace it just created, then
+prints where to capture the `.env` block:
+
+```bash
+cd sources/databricks/terraform/demo && terraform output -raw env_block >> ../../../../.env
+```
+
+If the region has no Unity Catalog metastore yet (rare, but possible
+for a brand-new account), the chained `demo` apply fails outright
+because there's nothing for the new workspace to attach to. Set
+`create_metastore = true` in `terraform/workspace/terraform.tfvars`
+and re-run — see
+[terraform/workspace/README.md](terraform/workspace/README.md#create_metastore)
+for how to tell in advance whether you need it. This is the most
+likely first failure of this "one command" path.
+
+See [terraform/workspace/README.md](terraform/workspace/README.md)
+and [terraform/demo/README.md](terraform/demo/README.md) for what each
+module creates and why account-admin (not workspace-admin) is required.
+
+### Existing workspace, provision the demo objects
+
+You already have a Databricks workspace with Unity Catalog. Terraform
+creates the catalog/schema, a dedicated serverless SQL warehouse, a
+demo service principal + token, and (optionally) the S3 staging path,
+then seeds the workload for you.
+
+```bash
+cd sources/databricks/terraform/demo
+cp terraform.tfvars.example terraform.tfvars
+# Edit: workspace_url, databricks_token
+# (this module creates a catalog, and CREATE CATALOG is a metastore-level
+# privilege, not a workspace-level one — see the README's Prerequisites
+# for what the PAT's principal needs)
+
+cd ../../../..
+make databricks-provision
+```
+
+```bash
+cd sources/databricks/terraform/demo && terraform output -raw env_block >> ../../../../.env
+```
+
+See [terraform/demo/README.md](terraform/demo/README.md) — in
+particular the **re-apply caveat** if you set `enable_s3_staging =
+true`: IAM propagation can make the first `apply` fail on
+`databricks_external_location.staging`; running `terraform apply`
+again succeeds once IAM catches up.
+
+### Existing workspace, workload only (fully manual)
+
+You want to do everything by hand instead of running Terraform. This
+enumerates every step the two modules above automate.
+
+This path needs **two identities**, mirroring the Terraform `demo`
+module's design (`terraform/demo/main.tf`'s provisioner deliberately
+runs the seeding script as the admin PAT, not as the demo principal's
+read-only token): a **setup** principal with write access, used only
+to provision and seed, and a **runtime** principal with read-only
+access, whose token is the one that ends up in `.env`.
+
+1. Create a Unity Catalog **catalog** and **schema**. The namespace
+   must be **exactly** `migration_demo.tpch` — `setup_workload.sql`
+   hard-codes that name in all 25 of its statements, so any other
+   catalog/schema name fails at the first one.
+2. Create a **serverless** SQL warehouse. Serverless is required for
+   the `daily_order_summary` materialized-view augmentation — a
+   classic warehouse works for everything else, but skips that one
+   object (see the Troubleshooting entry below).
+3. Create a **personal access token for the setup principal** — the
+   identity you'll run step 7 as. It needs write access: `CREATE
+   CATALOG` at the **metastore** (not workspace) level, plus `CREATE
+   SCHEMA`, `CREATE TABLE`, and `MODIFY` (covers `ALTER TABLE`,
+   `UPDATE`, `DELETE`) on the catalog from step 1. An existing
+   workspace-admin/account-admin PAT works fine here too.
+4. Grant `USE CATALOG`, `USE SCHEMA`, and `SELECT` on the demo catalog,
+   **and** on the built-in `samples` catalog — the workload
+   `CREATE TABLE ... AS SELECT` copies out of `samples.tpch` — to a
+   **separate, read-only principal**. This is the identity that ends
+   up in `.env` for the playground to actually run as.
+5. *(Optional, only for the S3-staged migration path)* create a Unity
+   Catalog **external location** over your staging bucket with
+   `WRITE FILES` granted.
+6. Put the **setup** principal's token from step 3 in `.env` as
+   `DATABRICKS_TOKEN` — temporarily, just for the next step:
+   ```bash
+   DATABRICKS_HOST=https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
+   DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/xxxxxxxxxxxxxxxx
+   DATABRICKS_TOKEN=dapi................................
+   DATABRICKS_NAMESPACE=migration_demo.tpch
+   ```
+7. Seed the workload:
+   ```bash
+   make databricks-setup
+   ```
+   `databricks-setup` installs `databricks-sql-connector`, then runs
+   `sources/databricks/scripts/setup_workload.py`, which executes
+   `setup_workload.sql` against your warehouse — the 8 TPC-H tables
+   plus the eight augmentations above. **Once this succeeds, replace
+   `DATABRICKS_TOKEN` in `.env` with the read-only principal's token
+   from step 4** before starting the playground in Phase 1 — the
+   runtime identity does not need, and should not have, write access.
+
+---
+
+## Phase 1 — Launch the playground (~5 min)
+
+```bash
+make up-databricks
+```
+
+`make up-databricks` regenerates `librechat.runtime.yaml` for the
+`databricks` profile, pulls/builds images, and starts every service
+including `databricks-mcp`. Default `make up` skips it — like
+Snowflake and BigQuery, the Databricks MCP is profile-gated because it
+needs account credentials in `.env`.
+
+Check `docker compose ps` — `databricks-mcp` should show `healthy`
+alongside the rest of the stack. Its healthcheck only probes that the
+SSE endpoint responds; the actual Databricks connection is opened
+lazily per tool call, so a healthy container does **not** by itself
+prove your credentials are valid (see Troubleshooting).
+
+Open **<https://localhost/dashboard/>** (accept the self-signed cert)
+and sign in (`admin@playground.local` / `playground`). You'll land on
+the **MigrationRoom** dashboard with the chat panel on the right.
+
+In the **SETUP** card at the top:
+
+- **Source**: pick `Databricks`. The chat panel auto-switches to the
+  `Databricks → ClickHouse Cloud` agent.
+- **Source database**: the `catalog.schema` pair, e.g.
+  `migration_demo.tpch`.
+- **Queries**: open **Edit · N OLAP** and confirm the OLAP queries are
+  loaded (steps 1 and 4 use them, for schema design and rewrite).
+
+---
+
+## Phase 2 — Run the migration (~45 min, estimate)
+
+The dashboard has **six step buttons** at the top of the **STEPS**
+panel. Click each in order. All six are clickable at any time, so you
+can re-fire a step (e.g. re-run validation after fixing the schema).
+
+### Step 1 — Discover & Design Schema
+
+Agent introspects the source via the `databricks-source` MCP
+(`list_catalogs`, `list_schemas`, `list_tables`, `describe_table`,
+`run_select_query` — never `run_python` for discovery), reads the OLAP
+queries to drive `ORDER BY` choices, proposes the ClickHouse target
+schema, and runs the DDL via `clickhousectl`.
+
+**Watch in chat** for the agent's decisions: `Decimal(15, 2)` for
+money, `Date32` for dates, `DateTime64(6, 'UTC')` vs `DateTime64(6)`
+for the `TIMESTAMP` / `TIMESTAMP_NTZ` pair, `JSON` (not `String`) for
+`o_metadata`, `Nested(...)` vs `Array(Tuple(...))` for
+`l_shipping_events`, and an explicit call on `MATERIALIZED` vs `ALIAS`
+for `o_orderyear`. **Confirm the target database name** when the agent
+asks (default suggestion `migration_demo`).
+
+### Step 2 — Migrate Data
+
+Agent writes a short Python script using the `migrationkit` library,
+dispatches it as a background job via `migration-runner`, issues
+ONE `tail_python_job` to confirm `status=running`, then stops. The
+dashboard's **Migration** tab streams live progress: rows/sec, ETA,
+per-table progress bars, milestone events.
+
+Large tables (over ~1M rows) can also take the S3-stage path if
+`STAGING_S3_*` is set — the agent picks direct vs staged per table.
+
+**This step is meant to look quiet in chat.** The agent dispatches and
+stops by design (see [`docs/adding-a-source.md`](../../docs/adding-a-source.md)
+on why polling isn't used); silence in the conversation while the
+dashboard streams progress bars is expected, not stuck.
+
+### Step 3 — Validate
+
+Agent runs `Validator(...).validate()` — row count parity per table,
+source vs target. Results land on the dashboard's **Validation** tab.
+If anything mismatches the agent **stops and reports** in chat — fix
+the schema and re-fire step 2, don't ask the agent to patch the target
+by hand.
+
+### Step 4 — Rewrite Queries
+
+Agent translates each OLAP query from Databricks SQL to ClickHouse SQL
+**in chat**. No script — this is a reasoning step. Walk through each
+rewrite, push back on unfamiliar substitutions (`QUALIFY` → subquery,
+`LATERAL VIEW explode` → `ARRAY JOIN`, `aggregate`/`filter` →
+`arrayReduce`/`arrayFilter`, etc.).
+
+### Step 5 — Benchmark
+
+Agent runs `Benchmarker(...).benchmark(queries=[...])` — each query on
+source and target, server-side timing on both. Results land on the
+**Benchmark** tab as `source_ms / target_ms / speedup` per query.
+
+Databricks timing comes from the SQL query-history REST API, with
+`system.query.history` as a fallback; if neither is available
+`server_ms` is `None` and wall-clock is shown instead — the agent
+should say so rather than presenting wall time as server time. The
+first query in a session also pays Databricks warehouse cold-start;
+expect a throwaway `SELECT 1` before the real numbers.
+
+### Step 6 — Optimize
+
+Agent proposes ClickHouse-Cloud-specific optimizations for the
+slowest queries: Materialized Views on `AggregatingMergeTree`,
+Projections, codec adjustments. Iterate in chat — once you apply an
+optimization, re-fire step 5 to confirm the speedup.
+
+---
+
+## Validation
+
+Compare the agent's final state against:
+
+- **Schema:** [queries/expected_ch_schema.sql](queries/expected_ch_schema.sql)
+- **Queries:** [queries/expected_ch_queries.sql](queries/expected_ch_queries.sql)
+- **Checklist:** [../../docs/migration-checklist.md](../../docs/migration-checklist.md)
+
+Bit-for-bit identity isn't expected — what matters is that the agent
+made defensible choices: `Decimal` (not `Float`) for money, `Date32`
+for dates, `JSON` (not a bare `String`) for `o_metadata`, a
+`Nested`/`Map` decision for the nested lineitem columns, and a clear
+call on the generated column and the materialized view.
+
+**Row-count parity has one legitimate exception.** `lineitem` has
+deletion vectors enabled, and `setup_workload.sql` deletes 500 rows
+from it as part of seeding a real history to time-travel over. If a
+partner (or another process) deletes more rows from the source table
+**while step 2 is running**, the source count can legitimately drop
+mid-migration — that's not a migration bug, and step 3's `Validator`
+output should be read with that in mind rather than assumed to be
+stale.
+
+---
+
+## Teardown and cost
+
+Everything provisioned in Phase 0 bills against your own
+Databricks/AWS account, not against MigrationRoom.
+
+```bash
+cd sources/databricks/terraform/demo && terraform destroy
+cd ../workspace && terraform destroy   # only if you used the workspace path
+```
+
+Destroy `demo` before `workspace` — the workspace module has no
+`demo` in scope and destroying it first takes everything `demo`
+created (catalog, warehouse, tokens) down with it regardless of order,
+but destroying in `demo` → `workspace` order lets each module report
+what it removed cleanly.
+
+- The serverless SQL warehouse's `auto_stop_minutes` defaults to 10
+  minutes of idle time before it suspends — an idle warehouse still
+  bills, so don't raise this casually.
+- If you enabled S3 staging, the staging bucket has a 7-day lifecycle
+  expiry on staged objects, and both the catalog/schema and the bucket
+  are created with `force_destroy = true` so `terraform destroy` won't
+  wedge on leftover demo tables or objects.
+
+---
+
+## Troubleshooting
+
+**`databricks-mcp` shows healthy but every tool call errors:**
+Credentials are checked lazily, per call — not at container startup —
+so a healthy container proves the SSE endpoint responds, not that
+`DATABRICKS_HOST` / `DATABRICKS_HTTP_PATH` / `DATABRICKS_TOKEN` are
+valid. Check `docker compose logs databricks-mcp`, fix `.env`, then
+`docker compose --profile databricks restart databricks-mcp`.
+
+**Chained `demo` apply fails because the workspace has no metastore:**
+Some regions/accounts have no Unity Catalog metastore auto-provisioned
+yet. Set `create_metastore = true` in
+`terraform/workspace/terraform.tfvars` and re-apply — see
+[terraform/workspace/README.md](terraform/workspace/README.md#create_metastore)
+for how to check in advance whether you need it. This is the most
+likely first failure of the "one command" new-environment path.
+
+**`databricks_grants.samples` fails on the first `terraform apply`:**
+The built-in `samples` catalog is often owned by a different metastore
+admin than the identity running Terraform. If the grant fails, either
+apply again after getting the metastore admin to grant ownership (or
+`SELECT`/`USE CATALOG`/`USE SCHEMA` on `samples.tpch` directly) to your
+provisioning principal, or run the grant by hand once and re-apply —
+this is a per-account permission quirk, not a bug in the module.
+
+**`setup_workload.sql` fails on the hand-written `orders` table (`CREATE
+OR REPLACE TABLE migration_demo.tpch.orders`):**
+That DDL's column types were written without a live workspace to test
+against and may not exactly match `samples.tpch.orders` on yours. Run
+`DESCRIBE TABLE samples.tpch.orders`, compare against the column list
+in `setup_workload.sql`, adjust the mismatched types, then re-run
+`make databricks-setup`.
+
+**First query of the session is slow:**
+A stopped SQL warehouse takes 30s+ to serve its first statement. This
+is warehouse cold-start, not a ClickHouse-vs-Databricks comparison —
+run a throwaway `SELECT 1` before benchmarking, or note that query 1's
+number includes cold-start.
+
+**`VARIANT` column rejected / type doesn't exist:**
+Needs DBSQL 2024.35+ or DBR 15.3+. Upgrade the SQL warehouse's channel
+to Current, or use a newer runtime, then re-run `make databricks-setup`.
+
+**Staged unload refused:**
+The S3 path needs a Unity Catalog **external location** over the
+staging bucket with `WRITE FILES` granted. `unload_to_s3` raises an
+error saying exactly that; either provision the external location
+(`enable_s3_staging=true` in the `demo` module) or let the agent fall
+back to the direct path for that table.
+
+**`terraform apply` on the `demo` module fails once on
+`databricks_external_location.staging`, then succeeds on retry:**
+Expected, not a bug. The external location validates itself by
+assuming the freshly created IAM role, and IAM is eventually
+consistent — a role that was just created can fail to assume for a
+few seconds even after Terraform reports the attachment done. Just
+run `terraform apply` again; don't delete the role or the storage
+credential.
+
+**`daily_order_summary` (and sample query 7) missing:**
+The materialized-view augmentation is `@optional` in
+`setup_workload.sql` — it needs a serverless SQL warehouse, and is
+silently skipped on a classic one, which is a perfectly reasonable
+demo environment otherwise. If it's absent, drop sample query 7 (and
+its rewrite in `expected_ch_queries.sql`) rather than treating the
+setup as broken.
+
+**Serverless egress control blocking the staging bucket:**
+If the workspace has a network connectivity configuration (NCC)
+restricting serverless egress, the staging bucket's endpoint must be
+added to the allowed list, or the serverless warehouse can't read or
+write staged Parquet through the external location. This is a
+workspace-level network setting outside Terraform's control here —
+check with whoever manages the workspace's NCC.
+
+---
+
+## Honesty about what's been verified
+
+No live migration has been run end-to-end against a real Databricks
+workspace as part of building this source — that needs a workspace, a
+SQL warehouse, and a token, none of which exist in the environment
+this guide was written in. `terraform apply` has **not** been run for
+either Terraform module; `terraform validate` proves the configuration
+is well-formed, not that an apply succeeds. See each module's README
+(["workspace"](terraform/workspace/README.md),
+["demo"](terraform/demo/README.md)) for the specific attributes most
+likely to need adjustment on first contact with a real account.
+
+Likewise, `make up-databricks` — Phase 1's very first command — has
+not actually been run in this environment: the `databricks-mcp` image
+has not been built, and none of the Compose services have been booted
+under the `databricks` profile. What's been verified is static: the
+Dockerfile, compose service definition, and profile gating are
+consistent with the other sources' equivalents, and `docker compose
+config` accepts them. Whether the image builds cleanly and the
+container reaches `healthy` has not been exercised.
diff --git a/sources/databricks/manifest.json b/sources/databricks/manifest.json
new file mode 100644
index 0000000..7c8116e
--- /dev/null
+++ b/sources/databricks/manifest.json
@@ -0,0 +1,6 @@
+{
+  "label": "Databricks",
+  "default_database_env": "DATABRICKS_NAMESPACE",
+  "default_database_fallback": "migration_demo.tpch",
+  "agent_name": "Databricks → ClickHouse Cloud"
+}
diff --git a/sources/databricks/prompts/01-discover-and-design.md b/sources/databricks/prompts/01-discover-and-design.md
new file mode 100644
index 0000000..30a4765
--- /dev/null
+++ b/sources/databricks/prompts/01-discover-and-design.md
@@ -0,0 +1,88 @@
+# Step 1 — Discover the source and design the ClickHouse Cloud target schema
+
+You are migrating from `{source}` to ClickHouse Cloud.
+
+- **Source namespace** (where the data lives today): `{database}` — a
+  Unity Catalog `catalog.schema` pair, selected by the partner in the
+  dashboard. Use it as-is.
+- **Target database** (where the data will land in ClickHouse Cloud): not
+  chosen yet. Propose a name in this step and confirm with the partner.
+
+If the partner has told you in this conversation to use a different
+namespace, follow their chat instruction instead.
+
+## Source
+
+Use the `databricks-source` MCP — **not** `run_python`. Its five tools are
+`list_catalogs`, `list_schemas`, `list_tables`, `describe_table`, and
+`run_select_query`.
+
+1. `list_tables(catalog, schema)` for the namespace above. It returns
+   `sizeInBytes` and `numFiles` per table but **no row counts** — Delta
+   metadata doesn't carry them.
+2. Get row counts in ONE query rather than one per table:
+   ```sql
+   SELECT 'orders' AS t, count(*) AS n FROM migration_demo.tpch.orders
+   UNION ALL SELECT 'lineitem', count(*) FROM migration_demo.tpch.lineitem
+   -- … one line per table
+   ORDER BY n DESC
+   ```
+3. `describe_table(catalog, schema, table)` for every table. Read the
+   `detail` and `history` sections too, not just the columns — that is
+   where clustering columns, partition columns, table features, and
+   deletion-vector state live.
+4. Inventory the Databricks-specific features you actually find. Do not
+   assume any are present: VARIANT columns, `ARRAY<STRUCT>` / `MAP` /
+   `STRUCT`, generated columns, liquid clustering (`CLUSTER BY`),
+   deletion vectors, `TIMESTAMP` vs `TIMESTAMP_NTZ`, materialized views,
+   streaming tables.
+5. Sample rows and check cardinality before designing types:
+   ```sql
+   SELECT * FROM <catalog>.<schema>.<table> LIMIT 5
+   SELECT count(*), count(<col>), count(DISTINCT <col>) FROM <catalog>.<schema>.<table>
+   ```
+6. Identify fact vs dimension tables and the join graph.
+
+## Analytical workload
+
+The partner will run these against the migrated data. Use them to choose
+`ORDER BY` keys, partitioning, and projections — the ordering should come
+from the columns in WHERE / JOIN / GROUP BY here, **not** from the source's
+clustering columns:
+
+```sql
+{olap_queries}
+```
+
+## Target
+
+Use the `clickhousectl` MCP to:
+
+1. Create the target database (suggested default `migration_demo`; confirm
+   first).
+2. `CREATE TABLE` for every source table, following the ClickHouse Cloud
+   best-practice rules attached to **clickhousectl**. Justify each engine,
+   `ORDER BY`, `PARTITION BY`, and codec choice in chat.
+3. Map Databricks types — the full table is in your Databricks source
+   instructions. The decisions worth surfacing to the partner:
+   - `VARIANT` → `JSON`, or extract hot keys into typed columns
+   - `ARRAY<STRUCT<…>>` → `Nested(...)` or `Array(Tuple(...))`
+   - `MAP<STRING, STRING>` → `Map(String, String)`
+   - `DECIMAL(p, s)` → `Decimal(p, s)`, never `Float64`
+   - `TIMESTAMP` → `DateTime64(6, 'UTC')`; `TIMESTAMP_NTZ` → `DateTime64(6)`
+   - generated column → `MATERIALIZED` (stored) or `ALIAS` (computed)
+4. **Column order must match the source table's column order** for every
+   table you plan to migrate through S3 staging in step 2 — that path does
+   `INSERT INTO … SELECT * FROM s3(...)`, which is positional.
+5. **Handle nullable columns deliberately.** `describe_table` reports
+   nullability. For each nullable column either declare
+   `Nullable(<T>)`, or declare it non-Nullable with an explicit `DEFAULT`
+   AND add a `transform=` lambda in step 2 mapping `None` to that default.
+   A non-Nullable column with neither will fail mid-batch on the first NULL.
+6. Verify with `SHOW TABLES`.
+
+## When you're done
+
+Summarise the source namespace, target database name, and the key schema
+decisions in chat — later steps refer back to them. Do **not** insert any
+data; that is step 2.
diff --git a/sources/databricks/prompts/02-migrate-data.md b/sources/databricks/prompts/02-migrate-data.md
new file mode 100644
index 0000000..3a69d19
--- /dev/null
+++ b/sources/databricks/prompts/02-migrate-data.md
@@ -0,0 +1,115 @@
+# Step 2 — Migrate data using `migrationkit`
+
+The target schema from step 1 is in place. Copy the data from Databricks
+into ClickHouse Cloud with the `migrationkit` library — it handles
+batching, per-batch checkpointing, pause/resume/cancel, and the live
+progress events the dashboard renders.
+
+## Pick a path per table
+
+| Path | Use when | API |
+|---|---|---|
+| **Direct** | `total_rows ≤ 1_000_000` | `m.add_table(...)` |
+| **S3 staging** | `total_rows > 1_000_000` AND `STAGING_S3_BUCKET` is set | `m.add_table_via_s3(name=..., stage=S3Stage.from_env())` |
+
+```python
+import os
+USE_S3 = bool(os.environ.get("STAGING_S3_BUCKET"))
+```
+
+If `USE_S3` is False, use the direct path for every table and note in chat
+that the partner hasn't configured S3 staging. Don't fail the migration —
+direct works at any size, it's just slower.
+
+**The S3 path additionally needs a Unity Catalog external location** over
+the staging bucket with `WRITE FILES` granted. If `unload_to_s3` raises,
+the error says so; fall back to `add_table()` for that table and tell the
+partner.
+
+## What to write
+
+One Python script (~25 lines), dispatched with `run_python_background`,
+confirmed with ONE `tail_python_job` call.
+
+```python
+import os
+import time
+from migrationkit import Migrator, DatabricksSource, ClickHouseTarget, S3Stage
+
+USE_S3 = bool(os.environ.get("STAGING_S3_BUCKET"))
+stage = S3Stage.from_env() if USE_S3 else None
+
+m = Migrator(
+    run_id=f"migrate-databricks-{int(time.time())}",
+    source=DatabricksSource.from_env(),
+    target=ClickHouseTarget.from_env(),
+    # REQUIRED: the ClickHouse Cloud database from step 1.
+    target_database="<target-db-from-step-1>",
+)
+
+# Direct path: dimensions and small facts. `target_table` is a BARE name —
+# never `db.table`; the Migrator owns the database via target_database=.
+m.add_table(
+    name="<dim_table>",
+    source_query="SELECT * FROM <catalog>.<schema>.<dim_table>",
+    target_table="<dim_table>",
+    batch_size=100_000,
+)
+
+# S3-staged path: large facts, only when stage is set.
+if stage is not None:
+    m.add_table_via_s3(name="<fact_table>", target_table="<fact_table>", stage=stage)
+else:
+    m.add_table(
+        name="<fact_table>",
+        source_query="SELECT * FROM <catalog>.<schema>.<fact_table>",
+        target_table="<fact_table>",
+        batch_size=50_000,
+    )
+
+# … one m.add_table(...) or m.add_table_via_s3(...) per source table.
+
+m.run()
+```
+
+Chat-side flow:
+
+```text
+1.  call: write_workspace_file(path="migrate.py", content=<script above>)
+2.  call: run_python_background(code=<the script>)            ← capture job_id
+3.  call: tail_python_job(job_id=..., max_wait_seconds=5)     ← ONE call, confirm status=running
+4.  reply in chat: "Migration <run_id> is running — watch the dashboard."
+```
+
+**No polling loop after that.** The dashboard streams progress over SSE.
+
+## Rules
+
+- Always pass `target_database=` to `Migrator(...)` and bare names to
+  `target_table`. A qualified `db.table` raises `ValueError` at
+  registration.
+- Source queries must be **fully qualified** (`catalog.schema.table`).
+  Unity Catalog is three-level and the connection's default namespace may
+  not be what you assume.
+- **Row dict keys are lowercase** — `iter_batches` lowercases column
+  names. Write any `transform=` lambda in lowercase.
+- `batch_size`: ~100k for narrow tables, ~25–50k for tables carrying
+  VARIANT or `ARRAY<STRUCT>` columns. Never above 500k.
+- VARIANT values arrive as Python strings or dicts depending on the
+  connector version. `json.dumps(...)` them if the target column is
+  `String`; pass through unchanged if it is `JSON`.
+- `ARRAY<STRUCT>` arrives as a list of dicts. For a ClickHouse `Nested`
+  target you must pivot it into parallel arrays in a `transform=`; for
+  `Array(Tuple(...))` convert each dict to a tuple in field order.
+- S3 staging supports neither `batch_size` nor `transform` — it is
+  `INSERT OVERWRITE DIRECTORY` → `INSERT FROM s3()`. Any table needing
+  per-row transformation must use the direct path.
+- If `S3Stage.from_env()` raises a missing-env error, tell the partner to
+  set `STAGING_S3_*` (see `docs/object-storage-staging.md`) or accept the
+  direct path.
+
+## When you're done
+
+Say which path each table took and why, tell the partner the migration is
+**running** (not "complete"), and point at the dashboard. Step 3 runs when
+they click it.
diff --git a/sources/databricks/prompts/03-validate.md b/sources/databricks/prompts/03-validate.md
new file mode 100644
index 0000000..942dc1d
--- /dev/null
+++ b/sources/databricks/prompts/03-validate.md
@@ -0,0 +1,44 @@
+# Step 3 — Validate row-count parity
+
+The migration from step 2 has finished (the dashboard's Migration tab shows
+every table `done`). Confirm the target matches the source before anyone
+rewrites a query against it.
+
+`Validator` reads the tables registered in the run's `run_tables` rows, so
+you don't re-list them — pass the same `run_id`.
+
+```python
+from migrationkit import Validator, DatabricksSource, ClickHouseTarget
+
+v = Validator(
+    run_id="<run_id-from-step-2>",
+    source=DatabricksSource.from_env(),
+    target=ClickHouseTarget.from_env(),
+    target_database="<target-db-from-step-1>",
+)
+result = v.validate()
+print(result)
+```
+
+This is a short script — dispatch it with `run_python` (not
+`run_python_background`); it returns in seconds.
+
+## Rules
+
+- Use the **same `run_id`** as step 2. A new one has no `run_tables` rows
+  and validates nothing.
+- Do not hand-write per-table `count()` comparisons; `Validator` writes
+  the `validations` rows the dashboard's Validation tab reads. Ad-hoc
+  counts leave that tab empty.
+- If a table mismatches, **stop and report it**. Do not re-run the
+  migration for that table without telling the partner — a partial
+  re-insert without a `TRUNCATE` first duplicates rows.
+- A deliberate caveat for this source: if the source table has deletion
+  vectors enabled and rows were deleted after step 2 started, the source
+  count can legitimately drop mid-run. Re-check the source count before
+  calling it a migration bug.
+
+## When you're done
+
+Report per-table parity in chat and point at the Validation tab. Step 4
+(Rewrite Queries) runs when the partner clicks it.
diff --git a/sources/databricks/prompts/04-rewrite-queries.md b/sources/databricks/prompts/04-rewrite-queries.md
new file mode 100644
index 0000000..45e4d93
--- /dev/null
+++ b/sources/databricks/prompts/04-rewrite-queries.md
@@ -0,0 +1,56 @@
+# Step 4 — Rewrite the analytical queries for ClickHouse
+
+Data is migrated and validated. Translate the partner's Databricks SQL to
+ClickHouse SQL. **This step is chat-only — write no Python.** Use
+`clickhousectl` `run_query` to check that each rewritten query runs and
+returns sensible results.
+
+## The queries
+
+```sql
+{olap_queries}
+```
+
+## Rewrite each one
+
+For every query: show the original, the ClickHouse version, and a one-line
+note on what changed and why. Then run the ClickHouse version and report
+the row count returned.
+
+## Databricks → ClickHouse dialect differences
+
+| Databricks | ClickHouse | Note |
+|---|---|---|
+| `QUALIFY <pred>` | subquery + `WHERE` over the window | No `QUALIFY` in ClickHouse |
+| `LATERAL VIEW explode(arr) AS x` | `ARRAY JOIN` or `arrayJoin(arr)` | `ARRAY JOIN` is usually clearer |
+| `explode(m)` on a MAP | `arrayJoin(mapKeys(m))` + lookup | Maps explode to key/value pairs |
+| `transform(arr, x -> f(x))` | `arrayMap(x -> f(x), arr)` | Argument order flips |
+| `filter(arr, x -> p(x))` | `arrayFilter(x -> p(x), arr)` | Argument order flips |
+| `aggregate(arr, 0, (a, x) -> a + x)` | `arraySum(arr)` / `arrayReduce('sum', arr)` | Prefer the specific function |
+| `v:field`, `v:a.b`, `variant_get(v, '$.a')` | `JSONExtractString(v, 'a')`, `v.a` on a `JSON` column | Depends on whether you mapped to `JSON` or `String` |
+| `named_struct('a', 1)` | `tuple(1)` / named `Tuple` | ClickHouse tuples are positional |
+| `m['k']` on a MAP | `m['k']` | Same syntax; missing key returns the type default, not NULL |
+| `try_divide(a, b)` | `if(b = 0, NULL, a / b)` | ClickHouse `/` by zero returns `inf`, not NULL |
+| `try_cast(x AS t)` | `toTypeOrNull(x)` / `accurateCastOrNull` | |
+| `ilike` | `ILIKE` | Supported |
+| `date_trunc('month', d)` | `toStartOfMonth(d)` | ClickHouse also has `date_trunc` |
+| `datediff(a, b)` | `dateDiff('day', b, a)` | Argument order flips |
+| `catalog.schema.table` | `database.table` | Three levels collapse to two |
+| `SEMI JOIN` / `ANTI JOIN` | `LEFT SEMI JOIN` / `LEFT ANTI JOIN` | Join kind precedes strictness in ClickHouse |
+| Implicit `NULL` ordering | `NULLS FIRST` / `NULLS LAST` explicit | Defaults differ — state it |
+
+## Rules
+
+- Do not change the *meaning* of a query to make it run. If a rewrite
+  can't be exact, say so and explain the difference.
+- Where the schema decisions from step 1 make a query simpler (a hot
+  VARIANT key extracted to a typed column, for instance), use the simpler
+  form and point out the win.
+- Keep the result shape identical — same columns, same order, same names —
+  so step 5 can benchmark source against target fairly.
+
+## When you're done
+
+Present the rewritten set as a single SQL block the partner can copy, and
+paste it into the dashboard's OLAP queries editor so step 5 benchmarks the
+same statements.
diff --git a/sources/databricks/prompts/05-benchmark.md b/sources/databricks/prompts/05-benchmark.md
new file mode 100644
index 0000000..014e46e
--- /dev/null
+++ b/sources/databricks/prompts/05-benchmark.md
@@ -0,0 +1,54 @@
+# Step 5 — Benchmark source vs target
+
+Run the same analytical workload on Databricks and on ClickHouse Cloud and
+compare server-side execution time.
+
+`Benchmarker` pairs each source query with its target rewrite, times both,
+and writes the `benchmarks` rows the dashboard's Benchmark tab reads.
+
+```python
+from migrationkit import Benchmarker, DatabricksSource, ClickHouseTarget
+
+b = Benchmarker(
+    run_id="<run_id-from-step-2>",
+    source=DatabricksSource.from_env(),
+    target=ClickHouseTarget.from_env(),
+    target_database="<target-db-from-step-1>",
+)
+result = b.benchmark(queries=[
+    {
+        "name": "Q1: <short description>",
+        "source_sql": "<databricks query 1>",
+        "target_sql": "<clickhouse query 1>",
+    },
+    # … one dict per query from step 4. `name` is optional (defaults to Q1, Q2, …);
+    # either SQL may be omitted to time only one side.
+])
+print(result)
+```
+
+Dispatch with `run_python_background` if the workload has more than a
+couple of queries (a cold Databricks warehouse can take 30s+ on the first
+statement), then ONE `tail_python_job` to confirm it started. Otherwise
+`run_python` is fine.
+
+## Rules
+
+- Use the **same `run_id`** as step 2 so the dashboard associates the
+  benchmark with the migration.
+- Pass the step-4 rewrites verbatim. Benchmarking a hand-tuned target
+  query against an untuned source query is not a comparison.
+- Fully qualify the Databricks side (`catalog.schema.table`).
+- **The first Databricks query in a session pays warehouse start-up cost.**
+  Run one throwaway `SELECT 1` first, or say plainly that query 1's number
+  includes cold-start.
+- `server_ms` for Databricks comes from the SQL query-history API, with
+  `system.query.history` as a fallback. If both are unavailable it is
+  `None` and the dashboard shows wall-clock instead — say so rather than
+  presenting wall time as server time.
+
+## When you're done
+
+Report the per-query comparison and the aggregate speed-up, and point at
+the Benchmark tab. Be honest about queries where ClickHouse is slower —
+those are step 6's input.
diff --git a/sources/databricks/prompts/06-optimize.md b/sources/databricks/prompts/06-optimize.md
new file mode 100644
index 0000000..5f31930
--- /dev/null
+++ b/sources/databricks/prompts/06-optimize.md
@@ -0,0 +1,20 @@
+# Step 6 — Optimize the slow queries
+
+Step 5 produced a per-query comparison. Take the queries where ClickHouse
+Cloud did **not** win, or won by less than you'd expect, and improve them.
+
+This step is chat reasoning plus DDL through `clickhousectl` — no
+`migrationkit` script.
+
+1. For each underperforming query, run `EXPLAIN indexes = 1` and read
+   which parts and granules were scanned.
+2. Diagnose: wrong `ORDER BY` prefix, missing projection, a partition key
+   that prunes nothing, a `Nullable` column in the sort key, or a codec
+   choice inflating reads.
+3. Propose one change at a time, apply it with `run_query`, and re-time
+   the query.
+4. When you're done, tell the partner to click **Benchmark** again so the
+   dashboard records the improved numbers against the same run.
+
+Explain each change in terms of what ClickHouse does differently, not just
+what you typed — the partner is evaluating the engine, not the syntax.
diff --git a/sources/databricks/queries/expected_ch_queries.sql b/sources/databricks/queries/expected_ch_queries.sql
new file mode 100644
index 0000000..2eba810
--- /dev/null
+++ b/sources/databricks/queries/expected_ch_queries.sql
@@ -0,0 +1,129 @@
+-- Reference ClickHouse rewrites of sources/databricks/queries/sample_olap_queries.sql.
+--
+-- Same order, same numbering, one comment per query naming the dialect
+-- transformation applied. These run against the schema in
+-- expected_ch_schema.sql — that is the point of shipping them alongside it,
+-- not a hand-wavy translation exercise. If sample query 7's source
+-- (daily_order_summary) doesn't exist because the demo ran on a
+-- non-serverless warehouse, drop query 7 here too — see
+-- expected_ch_schema.sql's note on that table.
+
+-- 1. Revenue by ship date and priority.
+--    Transformation: three-level `catalog.schema.table` → two-level
+--    `database.table` naming; otherwise unchanged — this is standard SQL
+--    on both engines.
+SELECT
+    l_shipdate,
+    o_orderpriority,
+    count(*)                                AS line_count,
+    sum(l_extendedprice * (1 - l_discount)) AS revenue
+FROM migration_demo.lineitem l
+JOIN migration_demo.orders   o ON l.l_orderkey = o.o_orderkey
+WHERE l_shipdate BETWEEN '1994-01-01' AND '1994-12-31'
+GROUP BY l_shipdate, o_orderpriority
+ORDER BY l_shipdate, o_orderpriority;
+
+-- 2. Top customers by lifetime revenue.
+--    Transformation: three-level → two-level naming only; the multi-table
+--    join and LIMIT are identical on both engines.
+SELECT
+    c.c_custkey,
+    c.c_name,
+    n.n_name                    AS nation,
+    count(o.o_orderkey)         AS order_count,
+    sum(o.o_totalprice)         AS lifetime_revenue
+FROM migration_demo.orders   o
+JOIN migration_demo.customer c ON o.o_custkey = c.c_custkey
+JOIN migration_demo.nation   n ON c.c_nationkey = n.n_nationkey
+GROUP BY c.c_custkey, c.c_name, n.n_name
+ORDER BY lifetime_revenue DESC
+LIMIT 50;
+
+-- 3. VARIANT extraction.
+--    Transformation: `o_metadata:channel::string` and
+--    `o_metadata:fulfilment.warehouse::string` (Databricks colon-path syntax
+--    over VARIANT) → `JSONExtractString(o_metadata, 'channel')` and a
+--    two-key `JSONExtractString(o_metadata, 'fulfilment', 'warehouse')`
+--    (nested-path drill-down) over the `JSON` column.
+SELECT
+    JSONExtractString(o_metadata, 'channel')                    AS channel,
+    JSONExtractString(o_metadata, 'fulfilment', 'warehouse')    AS warehouse,
+    count(*)                                                    AS order_count,
+    sum(o_totalprice)                                           AS revenue
+FROM migration_demo.orders
+WHERE o_orderdate >= '1995-01-01'
+GROUP BY channel, warehouse
+ORDER BY revenue DESC;
+
+-- 4. Nested-type access.
+--    Transformation: `LATERAL VIEW explode(l_shipping_events) AS event` over
+--    an ARRAY<STRUCT> → `ARRAY JOIN` over the parallel arrays ClickHouse's
+--    `Nested` type produces (`l_shipping_events.status`,
+--    `l_shipping_events.location`); the MAP subscript
+--    `l_attributes['carrier']` is unchanged — same syntax on both engines.
+SELECT
+    event_status                        AS status,
+    l.l_shipmode                        AS ship_mode,
+    l.l_attributes['carrier']           AS carrier,
+    count(*)                            AS event_count
+FROM migration_demo.lineitem AS l
+ARRAY JOIN l.l_shipping_events.status AS event_status
+GROUP BY event_status, l.l_shipmode, l.l_attributes['carrier']
+ORDER BY event_count DESC;
+
+-- 5. Window function with QUALIFY.
+--    Transformation: `QUALIFY revenue_rank <= 3` (ClickHouse has no
+--    QUALIFY) → the window predicate moves into an outer `WHERE` over a
+--    subquery. Also reads `o_orderyear`, the `MATERIALIZED` mirror of the
+--    source's `GENERATED ALWAYS AS` column.
+SELECT *
+FROM
+(
+    SELECT
+        o_orderyear,
+        o_orderpriority,
+        sum(o_totalprice)                   AS revenue,
+        rank() OVER (
+            PARTITION BY o_orderyear
+            ORDER BY sum(o_totalprice) DESC
+        )                                    AS revenue_rank
+    FROM migration_demo.orders
+    GROUP BY o_orderyear, o_orderpriority
+)
+WHERE revenue_rank <= 3
+ORDER BY o_orderyear, revenue_rank;
+
+-- 6. Higher-order function over an array.
+--    Transformation: `filter(arr, e -> pred)` → `arrayFilter(e -> pred, arr)`
+--    (argument order flips); `aggregate(arr, 0, (acc, e) -> acc + 1)` (a
+--    manual count-fold) → `arrayReduce('count', ...)` over the filtered
+--    array — ClickHouse has a named aggregate combinator for this instead
+--    of a manual fold.
+SELECT
+    l_shipmode,
+    count(*)                                                            AS line_count,
+    avg(
+        arrayReduce('count', arrayFilter(x -> x != 'CANCELLED', l_shipping_events.status))
+    )                                                                    AS avg_live_events
+FROM migration_demo.lineitem
+GROUP BY l_shipmode
+ORDER BY line_count DESC;
+
+-- 7. Pre-aggregated read against the materialized view.
+--    Transformation: the source reads a Databricks MATERIALIZED VIEW
+--    directly as finished rows. Its ClickHouse mirror is an
+--    AggregatingMergeTree holding *partial aggregate states*
+--    (see expected_ch_schema.sql), so reading it back requires the
+--    `-Merge` combinator (`countMerge`, `sumMerge`) to finalize
+--    `order_count` / `daily_revenue` — a plain SELECT would return opaque
+--    state blobs, not numbers. Drop this query if daily_order_summary
+--    doesn't exist because the source ran without a serverless warehouse.
+SELECT
+    order_day,
+    o_orderpriority,
+    countMerge(order_count)   AS order_count,
+    sumMerge(daily_revenue)   AS daily_revenue
+FROM migration_demo.daily_order_summary
+WHERE order_day BETWEEN '1995-01-01' AND '1995-12-31'
+GROUP BY order_day, o_orderpriority
+ORDER BY order_day, o_orderpriority;
diff --git a/sources/databricks/queries/expected_ch_schema.sql b/sources/databricks/queries/expected_ch_schema.sql
new file mode 100644
index 0000000..a23888a
--- /dev/null
+++ b/sources/databricks/queries/expected_ch_schema.sql
@@ -0,0 +1,207 @@
+-- Reference target schema — Databricks migration_demo.tpch → ClickHouse Cloud.
+--
+-- This is the schema a good agent should arrive at during Step 1 (Discover
+-- & Design Schema). It is a comparison artifact for demos, NOT executed by
+-- any tooling in this repo — nothing runs this file automatically.
+--
+-- COLUMN ORDER IS DELIBERATE AND MUST MATCH THE SOURCE. The S3-staged
+-- migration path (`m.add_table_via_s3(...)`, see
+-- sources/databricks/prompts/02-migrate-data.md) does
+-- `INSERT INTO ... SELECT * FROM s3(...)`, which binds columns positionally,
+-- not by name. Reordering a column here — even one that still exists on
+-- both sides — silently scrambles data for any table migrated through
+-- that path. Column order below matches `samples.tpch.*` /
+-- `sources/databricks/scripts/setup_workload.sql`: most augmented
+-- columns are appended at the end in the order they were added by
+-- `ALTER TABLE`, except `o_orderyear`, which `setup_workload.sql`
+-- declares at `CREATE TABLE` time and so sits at source position 10,
+-- immediately before `o_metadata` — not at the end.
+--
+-- `o_orderyear` is the one exception worth flagging: it is `MATERIALIZED`,
+-- so ClickHouse excludes it from `SELECT *` and from the implicit column
+-- list of a column-less `INSERT INTO ... SELECT * FROM s3(...)` — unlike
+-- Databricks' `GENERATED ALWAYS AS`, which is a normal stored column that
+-- SELECT * does return. This is not a problem in practice: `unload_to_s3`
+-- always does `SELECT * FROM {fq_table}` — it has no `source_query`
+-- parameter, and `Migrator` never forwards one to it — and ClickHouse's
+-- `s3()` / `file()` table functions push the target's structure into the
+-- read and match Parquet columns by name, not position. An 11-column
+-- source Parquet file (10 insertable columns plus `o_orderyear`) loads
+-- correctly into this 10-insertable-column `orders`: the extra column is
+-- ignored, not misaligned into a neighboring one.
+--
+-- Source: sources/databricks/scripts/setup_workload.sql (the workload)
+--         sources/databricks/queries/sample_olap_queries.sql (the ORDER BY
+--         justifications below)
+--         librechat/sources/databricks-instructions.md (the type-mapping
+--         table this schema follows)
+
+CREATE DATABASE IF NOT EXISTS migration_demo;
+
+-- ── Dimensions ─────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS migration_demo.region
+(
+    r_regionkey Int32,
+    r_name      LowCardinality(String),
+    r_comment   String
+)
+ENGINE = MergeTree
+ORDER BY r_regionkey;
+
+CREATE TABLE IF NOT EXISTS migration_demo.nation
+(
+    n_nationkey Int32,
+    n_name      LowCardinality(String),
+    n_regionkey Int32,
+    n_comment   String
+)
+ENGINE = MergeTree
+ORDER BY n_nationkey;
+
+-- customer: joined by c_custkey (query 2) and grouped by c_custkey/c_name.
+CREATE TABLE IF NOT EXISTS migration_demo.customer
+(
+    c_custkey    Int64,
+    c_name       String,
+    c_address    String,
+    c_nationkey  Int32,
+    c_phone      String,
+    c_acctbal    Decimal(15, 2),
+    c_mktsegment LowCardinality(String),
+    c_comment    String
+)
+ENGINE = MergeTree
+ORDER BY c_custkey;
+
+CREATE TABLE IF NOT EXISTS migration_demo.supplier
+(
+    s_suppkey   Int64,
+    s_name      String,
+    s_address   String,
+    s_nationkey Int32,
+    s_phone     String,
+    s_acctbal   Decimal(15, 2),
+    s_comment   String
+)
+ENGINE = MergeTree
+ORDER BY s_suppkey;
+
+CREATE TABLE IF NOT EXISTS migration_demo.part
+(
+    p_partkey     Int64,
+    p_name        String,
+    p_mfgr        LowCardinality(String),
+    p_brand       LowCardinality(String),
+    p_type        String,
+    p_size        Int32,
+    p_container   LowCardinality(String),
+    p_retailprice Decimal(15, 2),
+    p_comment     String
+)
+ENGINE = MergeTree
+ORDER BY p_partkey;
+
+CREATE TABLE IF NOT EXISTS migration_demo.partsupp
+(
+    ps_partkey    Int64,
+    ps_suppkey    Int64,
+    ps_availqty   Int32,
+    ps_supplycost Decimal(15, 2),
+    ps_comment    String
+)
+ENGINE = MergeTree
+ORDER BY (ps_partkey, ps_suppkey);
+
+-- ── Facts ────────────────────────────────────────────────────────────
+
+-- orders: augmented with o_metadata (VARIANT → JSON) and o_orderyear
+-- (GENERATED ALWAYS AS (year(o_orderdate)) on the source → MATERIALIZED
+-- here, since the source computes and stores it too, not on every read).
+-- ORDER BY starts with o_orderdate: query 5 filters/groups by o_orderyear
+-- (derived from it) and the daily_order_summary MV (below) groups by
+-- o_orderdate; o_orderpriority as the second key serves both query 2's
+-- and query 5's GROUP BY.
+CREATE TABLE IF NOT EXISTS migration_demo.orders
+(
+    o_orderkey      Int64,
+    o_custkey       Int64,
+    o_orderstatus   LowCardinality(String),
+    o_totalprice    Decimal(18, 2),
+    o_orderdate     Date32,
+    o_orderpriority LowCardinality(String),
+    o_clerk         String,
+    o_shippriority  Int32,
+    o_comment       String,
+    o_metadata      JSON,
+    o_orderyear     Int32 MATERIALIZED toYear(o_orderdate)
+)
+ENGINE = MergeTree
+ORDER BY (o_orderdate, o_orderpriority);
+
+-- lineitem: augmented with l_shipping_events (ARRAY<STRUCT> → Nested),
+-- l_attributes (MAP<STRING,STRING> → Map(String,String)), the
+-- TIMESTAMP/TIMESTAMP_NTZ pair, and liquid clustering on
+-- (l_shipdate, l_suppkey). ORDER BY keeps the source's clustering intent
+-- but is chosen from the actual workload, not copied blindly: query 1
+-- filters and groups by l_shipdate; l_orderkey second because it's the
+-- join key against orders (query 1) and the FK most other predicates hang
+-- off of.
+CREATE TABLE IF NOT EXISTS migration_demo.lineitem
+(
+    l_orderkey         Int64,
+    l_partkey          Int64,
+    l_suppkey          Int64,
+    l_linenumber       Int32,
+    l_quantity         Decimal(15, 2),
+    l_extendedprice    Decimal(15, 2),
+    l_discount         Decimal(15, 2),
+    l_tax              Decimal(15, 2),
+    l_returnflag       LowCardinality(String),
+    l_linestatus       LowCardinality(String),
+    l_shipdate         Date32,
+    l_commitdate       Date32,
+    l_receiptdate      Date32,
+    l_shipinstruct     String,
+    l_shipmode         LowCardinality(String),
+    l_comment          String,
+    l_shipping_events Nested
+    (
+        status   String,
+        event_ts DateTime64(6),
+        location String
+    ),
+    l_attributes       Map(String, String),
+    l_committed_at     DateTime64(6, 'UTC'),
+    l_committed_at_ntz DateTime64(6)
+)
+ENGINE = MergeTree
+ORDER BY (l_shipdate, l_orderkey);
+
+-- ── Materialized aggregate (mirrors the @optional daily_order_summary MV) ──
+--
+-- The source's daily_order_summary is a Databricks MATERIALIZED VIEW,
+-- created only on a serverless SQL warehouse (see setup_workload.sql's
+-- `@optional` directive). If it doesn't exist on the source, drop sample
+-- query 7 and these two objects together — they are the ClickHouse mirror
+-- of that same optional feature, not an independent design choice.
+CREATE TABLE IF NOT EXISTS migration_demo.daily_order_summary
+(
+    order_day       Date32,
+    o_orderpriority LowCardinality(String),
+    order_count     AggregateFunction(count),
+    daily_revenue   AggregateFunction(sum, Decimal(15, 2))
+)
+ENGINE = AggregatingMergeTree
+ORDER BY (order_day, o_orderpriority);
+
+CREATE MATERIALIZED VIEW IF NOT EXISTS migration_demo.daily_order_summary_mv
+TO migration_demo.daily_order_summary
+AS
+SELECT
+    o_orderdate                    AS order_day,
+    o_orderpriority,
+    countState()                   AS order_count,
+    sumState(o_totalprice)         AS daily_revenue
+FROM migration_demo.orders
+GROUP BY o_orderdate, o_orderpriority;
diff --git a/sources/databricks/queries/sample_olap_queries.sql b/sources/databricks/queries/sample_olap_queries.sql
new file mode 100644
index 0000000..297e8a4
--- /dev/null
+++ b/sources/databricks/queries/sample_olap_queries.sql
@@ -0,0 +1,105 @@
+-- Sample OLAP queries for the migration_demo.tpch workload.
+-- Classic TPC-H analytical patterns plus queries that hit the
+-- Databricks-specific augmentations (VARIANT, STRUCT/ARRAY/MAP,
+-- liquid clustering, generated column, materialized view).
+--
+-- The dashboard substitutes this file into the step-1 prompt, where the
+-- agent uses it to choose ORDER BY keys, partitioning, and codecs.
+
+-- 1. Revenue by ship date and priority — the bread-and-butter rollup.
+--    Drives the ORDER BY choice on the migrated lineitem table.
+SELECT
+    l_shipdate,
+    o_orderpriority,
+    count(*)                                   AS line_count,
+    sum(l_extendedprice * (1 - l_discount))    AS revenue
+FROM migration_demo.tpch.lineitem l
+JOIN migration_demo.tpch.orders   o ON l.l_orderkey = o.o_orderkey
+WHERE l_shipdate BETWEEN DATE '1994-01-01' AND DATE '1994-12-31'
+GROUP BY l_shipdate, o_orderpriority
+ORDER BY l_shipdate, o_orderpriority;
+
+-- 2. Top customers by lifetime revenue — multi-table join where the
+--    GROUP BY columns live in dimensions, not the fact table.
+SELECT
+    c.c_custkey,
+    c.c_name,
+    n.n_name                    AS nation,
+    count(o.o_orderkey)         AS order_count,
+    sum(o.o_totalprice)         AS lifetime_revenue
+FROM migration_demo.tpch.orders   o
+JOIN migration_demo.tpch.customer c ON o.o_custkey = c.c_custkey
+JOIN migration_demo.tpch.nation   n ON c.c_nationkey = n.n_nationkey
+GROUP BY c.c_custkey, c.c_name, n.n_name
+ORDER BY lifetime_revenue DESC
+LIMIT 50;
+
+-- 3. VARIANT extraction — reads the o_metadata column with Databricks'
+--    colon path syntax. On ClickHouse this becomes JSONExtract* over a
+--    JSON column, or a typed column if the agent extracted hot keys.
+SELECT
+    o_metadata:channel::string           AS channel,
+    o_metadata:fulfilment.warehouse::string AS warehouse,
+    count(*)                             AS order_count,
+    sum(o_totalprice)                    AS revenue
+FROM migration_demo.tpch.orders
+WHERE o_orderdate >= DATE '1995-01-01'
+GROUP BY channel, warehouse
+ORDER BY revenue DESC;
+
+-- 4. Nested-type access — explodes the ARRAY<STRUCT> shipping events and
+--    reads the MAP. `explode` becomes arrayJoin on ClickHouse; the MAP
+--    subscript becomes a Map(String, String) lookup.
+SELECT
+    event.status                        AS status,
+    l.l_shipmode                        AS ship_mode,
+    l.l_attributes['carrier']           AS carrier,
+    count(*)                            AS event_count
+FROM migration_demo.tpch.lineitem l
+LATERAL VIEW explode(l.l_shipping_events) AS event
+GROUP BY event.status, l.l_shipmode, l.l_attributes['carrier']
+ORDER BY event_count DESC;
+
+-- 5. Window function with QUALIFY — Databricks supports QUALIFY, ClickHouse
+--    does not, so this must be rewritten as a subquery with WHERE.
+--    Also reads o_orderyear, the GENERATED ALWAYS AS column.
+SELECT
+    o_orderyear,
+    o_orderpriority,
+    sum(o_totalprice)                   AS revenue,
+    rank() OVER (
+        PARTITION BY o_orderyear
+        ORDER BY sum(o_totalprice) DESC
+    )                                   AS revenue_rank
+FROM migration_demo.tpch.orders
+GROUP BY o_orderyear, o_orderpriority
+QUALIFY revenue_rank <= 3
+ORDER BY o_orderyear, revenue_rank;
+
+-- 6. Higher-order function — `aggregate` and `filter` over an array have no
+--    direct ClickHouse syntax; they map to arrayReduce / arrayFilter.
+SELECT
+    l_shipmode,
+    count(*)                            AS line_count,
+    avg(
+        aggregate(
+            filter(l_shipping_events, e -> e.status <> 'CANCELLED'),
+            0,
+            (acc, e) -> acc + 1
+        )
+    )                                   AS avg_live_events
+FROM migration_demo.tpch.lineitem
+GROUP BY l_shipmode
+ORDER BY line_count DESC;
+
+-- 7. Pre-aggregated read against the materialized view (skipped by the
+--    setup script on non-serverless warehouses — if daily_order_summary
+--    does not exist, drop this query).
+SELECT
+    order_day,
+    o_orderpriority,
+    order_count,
+    daily_revenue
+FROM migration_demo.tpch.daily_order_summary
+WHERE order_day BETWEEN DATE '1995-01-01' AND DATE '1995-12-31'
+ORDER BY order_day, o_orderpriority;
diff --git a/sources/databricks/scripts/merge_workspace_tfvars.py b/sources/databricks/scripts/merge_workspace_tfvars.py
new file mode 100644
index 0000000..cc42f43
--- /dev/null
+++ b/sources/databricks/scripts/merge_workspace_tfvars.py
@@ -0,0 +1,130 @@
+"""
+MigrationRoom — merge `workspace` module outputs into `demo`'s auto-tfvars.
+
+Invoked by `make databricks-provision-workspace` between the two `terraform
+apply` calls. Reads the just-applied workspace module's `terraform output
+-json` (captured to a file by the Makefile) plus the OAuth credentials from
+`workspace/terraform.tfvars`, and writes
+sources/databricks/terraform/demo/workspace.auto.tfvars.json — which
+Terraform auto-loads, so the chained `demo` apply picks up the new
+workspace URL and OAuth credentials with no copy-paste step.
+
+This logic originally lived as a Python heredoc inline in the Makefile
+recipe. It was pulled out to its own file because a heredoc spanning
+multiple Makefile recipe lines only works under GNU Make's `.ONESHELL`
+(added in 3.82); the `make` on this machine is 3.81, which invokes a
+separate shell per recipe line by default and silently mis-splits the
+heredoc body into standalone (failing) commands. A single-line
+`python3 path/to/script.py` call has no such dependency on Make version.
+
+Usage:
+    python3 sources/databricks/scripts/merge_workspace_tfvars.py <workspace-output.json>
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+WORKSPACE_DIR = REPO_ROOT / "sources/databricks/terraform/workspace"
+DEMO_DIR = REPO_ROOT / "sources/databricks/terraform/demo"
+
+# Only matches a single-line, double-quoted value (`name = "value"`). A
+# heredoc-style (`<<EOT`) or single-quoted tfvars value for either OAuth
+# field will not be found — that hits the same "not present" guard below
+# (loud, not silent), so it fails safely rather than writing an empty
+# secret, but it's worth knowing this parser doesn't attempt to handle it.
+_TFVAR_RE = r'^\s*{name}\s*=\s*"([^"]*)"'
+
+
+def tfvar(tfvars_text, name):
+    """Return the value of `name` from tfvars_text, or None if not found
+    as a single-line double-quoted assignment (see module docstring above
+    _TFVAR_RE). None, not "", signals "couldn't extract" — the caller
+    decides whether that's fatal."""
+    m = re.search(_TFVAR_RE.format(name=re.escape(name)), tfvars_text, re.M)
+    return m.group(1) if m else None
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("usage: merge_workspace_tfvars.py <workspace-output.json>", file=sys.stderr)
+        return 1
+
+    out_path = Path(sys.argv[1])
+    try:
+        out = json.loads(out_path.read_text())
+    except FileNotFoundError:
+        print(
+            f"error: workspace output file not found: {out_path}\n"
+            "This is meant to be produced by `terraform output -json` in "
+            "sources/databricks/terraform/workspace/ (the Makefile does this "
+            "for you via `make databricks-provision-workspace`). Run that "
+            "first, or pass the correct path.",
+            file=sys.stderr,
+        )
+        return 1
+
+    tfvars_path = WORKSPACE_DIR / "terraform.tfvars"
+    try:
+        tfvars_text = tfvars_path.read_text()
+    except FileNotFoundError:
+        print(
+            f"error: {tfvars_path.relative_to(REPO_ROOT)} not found.\n"
+            "This merge step reads the OAuth credentials from that file — "
+            "it does not see TF_VAR_* environment variables. Run "
+            "`cp terraform.tfvars.example terraform.tfvars` in "
+            "sources/databricks/terraform/workspace/ and fill in "
+            "databricks_client_id / databricks_client_secret there.",
+            file=sys.stderr,
+        )
+        return 1
+
+    client_id = tfvar(tfvars_text, "databricks_client_id")
+    client_secret = tfvar(tfvars_text, "databricks_client_secret")
+
+    # Fail loudly rather than writing an empty OAuth credential. The
+    # realistic trigger: a partner keeps the secret out of the plaintext
+    # tfvars file and supplies it via TF_VAR_databricks_client_secret
+    # instead. `workspace/`'s own apply succeeds — Terraform reads env
+    # vars natively — but this script reads only the FILE, so without this
+    # check it would silently write "" here. demo/'s
+    # `!= "" ? x : null` then treats that as "client_id set, secret
+    # unset" and the chained apply dies with an opaque OAuth error, far
+    # from the actual cause.
+    missing = [
+        name
+        for name, value in (
+            ("databricks_client_id", client_id),
+            ("databricks_client_secret", client_secret),
+        )
+        if not value
+    ]
+    if missing:
+        print(
+            "error: could not read the following variable(s) from "
+            f"{tfvars_path.relative_to(REPO_ROOT)}: {', '.join(missing)}\n"
+            "This merge step reads workspace/terraform.tfvars directly — it "
+            "does NOT see TF_VAR_* environment variables, even though "
+            "`terraform apply` in workspace/ does. If you supplied these via "
+            "the environment rather than the file, add them to "
+            "workspace/terraform.tfvars as well (or move them there "
+            "entirely) so this script can hand them to the demo module.",
+            file=sys.stderr,
+        )
+        return 1
+
+    payload = {
+        "workspace_url": out["workspace_url"]["value"],
+        "databricks_client_id": client_id,
+        "databricks_client_secret": client_secret,
+    }
+
+    dest = DEMO_DIR / "workspace.auto.tfvars.json"
+    dest.write_text(json.dumps(payload, indent=2))
+    print(f"Wrote {dest.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/sources/databricks/scripts/requirements.txt b/sources/databricks/scripts/requirements.txt
new file mode 100644
index 0000000..944e7fc
--- /dev/null
+++ b/sources/databricks/scripts/requirements.txt
@@ -0,0 +1 @@
+databricks-sql-connector>=4.0
diff --git a/sources/databricks/scripts/setup_workload.py b/sources/databricks/scripts/setup_workload.py
new file mode 100644
index 0000000..9f852a7
--- /dev/null
+++ b/sources/databricks/scripts/setup_workload.py
@@ -0,0 +1,137 @@
+"""
+MigrationRoom — Databricks workload setup.
+
+Reads DATABRICKS_* credentials from the environment and executes
+setup_workload.sql against the partner's SQL warehouse. Copies the built-in
+samples.tpch tables into migration_demo.tpch and adds Databricks-specific
+decorations (VARIANT, generated column, ARRAY<STRUCT>, MAP,
+TIMESTAMP/TIMESTAMP_NTZ, liquid clustering, deletion vectors,
+materialized view).
+
+No data download — TPC-H is already inside every Databricks workspace.
+
+Usage:
+    pip install -r sources/databricks/scripts/requirements.txt
+    set -a; source .env; set +a
+    python3 sources/databricks/scripts/setup_workload.py
+
+Environment:
+    DATABRICKS_HOST         required — workspace URL or bare hostname
+    DATABRICKS_HTTP_PATH    required — e.g. /sql/1.0/warehouses/abc123
+    DATABRICKS_TOKEN        required
+"""
+import os
+import re
+import sys
+from pathlib import Path
+
+SQL_FILE = Path(__file__).parent / "setup_workload.sql"
+
+DIRECTIVE = re.compile(r"^\s*--\s*@(optional|requires)\b[:\s]*(.*)$", re.I)
+COMMENT = re.compile(r"^\s*--")
+
+
+def require_env(key: str) -> str:
+    value = os.environ.get(key)
+    if not value:
+        print(f"❌ Missing required env var: {key}", file=sys.stderr)
+        sys.exit(2)
+    return value
+
+
+def normalize_host(raw: str) -> str:
+    host = raw.strip()
+    return host.removeprefix("https://").removeprefix("http://").rstrip("/")
+
+
+def parse_statements(sql: str) -> list[tuple[str, str, str]]:
+    """Split the script into (statement, kind, hint) triples.
+
+    `kind` is 'required' when the statement was preceded by a
+    `-- @requires:` directive, 'optional' for `-- @optional:`, else
+    'plain'. A directive applies to the next statement only.
+
+    Naive by design: the setup script has no embedded semicolons in
+    string literals and no procedural blocks.
+    """
+    statements: list[tuple[str, str, str]] = []
+    buffer: list[str] = []
+    kind, hint = "plain", ""
+
+    for line in sql.splitlines():
+        directive = DIRECTIVE.match(line)
+        if directive:
+            kind = "optional" if directive.group(1).lower() == "optional" else "required"
+            hint = directive.group(2).strip()
+            continue
+        if COMMENT.match(line):
+            continue
+        buffer.append(line)
+        if line.rstrip().endswith(";"):
+            statement = "\n".join(buffer).strip().rstrip(";").strip()
+            if statement:
+                statements.append((statement, kind, hint))
+            buffer, kind, hint = [], "plain", ""
+
+    tail = "\n".join(buffer).strip().rstrip(";").strip()
+    if tail:
+        statements.append((tail, kind, hint))
+    return statements
+
+
+def first_line(statement: str, limit: int = 80) -> str:
+    for line in statement.splitlines():
+        line = line.strip()
+        if line:
+            return line[:limit] + ("…" if len(line) > limit else "")
+    return ""
+
+
+def main() -> int:
+    from databricks import sql as dbsql
+
+    host = normalize_host(require_env("DATABRICKS_HOST"))
+    http_path = require_env("DATABRICKS_HTTP_PATH")
+    token = require_env("DATABRICKS_TOKEN")
+
+    statements = parse_statements(SQL_FILE.read_text(encoding="utf-8"))
+    print(f"Loaded {len(statements)} statements from {SQL_FILE.name}.")
+    print(f"Connecting to {host} ({http_path})…")
+
+    skipped: list[str] = []
+    with dbsql.connect(
+        server_hostname=host, http_path=http_path, access_token=token
+    ) as conn:
+        cur = conn.cursor()
+        try:
+            for i, (statement, kind, hint) in enumerate(statements, 1):
+                print(f"  [{i:>2}/{len(statements)}] {first_line(statement)}", flush=True)
+                try:
+                    cur.execute(statement)
+                except Exception as exc:
+                    if kind == "optional":
+                        print(f"      ⚠️  skipped: {hint or exc}", flush=True)
+                        skipped.append(first_line(statement, 60))
+                        continue
+                    if kind == "required":
+                        print(f"\n❌ {hint}", file=sys.stderr)
+                        print(f"   Statement: {first_line(statement)}", file=sys.stderr)
+                        print(f"   Error: {exc}", file=sys.stderr)
+                        return 3
+                    print(f"\n❌ Statement failed: {first_line(statement)}", file=sys.stderr)
+                    print(f"   Error: {exc}", file=sys.stderr)
+                    return 1
+        finally:
+            cur.close()
+
+    print("\n✅ Workload setup complete. migration_demo.tpch is ready.")
+    if skipped:
+        print(f"⚠️  {len(skipped)} optional statement(s) skipped:")
+        for label in skipped:
+            print(f"     - {label}")
+    print("   Set DATABRICKS_NAMESPACE=migration_demo.tpch in .env.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/sources/databricks/scripts/setup_workload.sql b/sources/databricks/scripts/setup_workload.sql
new file mode 100644
index 0000000..0b8ccf6
--- /dev/null
+++ b/sources/databricks/scripts/setup_workload.sql
@@ -0,0 +1,203 @@
+-- MigrationRoom — Databricks demo workload.
+--
+-- Builds migration_demo.tpch from the read-only `samples.tpch` catalog that
+-- ships with every Databricks workspace, then adds Databricks-specific
+-- decoration so the migration agent has to make real decisions rather than
+-- a mechanical type-for-type copy. `samples.tpch` itself is scale factor
+-- 1000 (~1 TB, ~6 billion lineitem rows, ~1.5 billion orders rows); the
+-- table-population predicates below downsample it to SF1-equivalent
+-- cardinality (~6M lineitem rows, no download) so this script runs in
+-- minutes and the eventual ClickHouse Cloud migration moves megabytes, not
+-- terabytes.
+--
+-- Directives read by setup_workload.py:
+--   -- @requires: <hint>   abort with <hint> if the next statement fails
+--   -- @optional: <hint>   warn and continue if the next statement fails
+--
+-- Why TPC-H rather than a bespoke workload: see docs/adding-a-source.md.
+-- Reusing it lets partners compare Databricks, Snowflake, and BigQuery
+-- migrations side by side — same tables, only the decoration differs.
+
+CREATE CATALOG IF NOT EXISTS migration_demo;
+
+CREATE SCHEMA IF NOT EXISTS migration_demo.tpch;
+
+-- ── The 8 TPC-H tables, downsampled from the built-in samples catalog ──
+--
+-- samples.tpch is scale factor 1000 (~1 TB total). The predicates below cut
+-- every table down to SF1-equivalent cardinality so this script runs in
+-- minutes and the demo migrates megabytes, not terabytes, into ClickHouse
+-- Cloud. Do NOT remove them:
+--   - orders and lineitem share the same key range (o_orderkey /
+--     l_orderkey <= 6000000) on purpose, so every kept line item's order
+--     still exists — a LIMIT or TABLESAMPLE on either would orphan rows.
+--   - customer is derived from the orders that were actually kept, so
+--     every kept order's customer still exists too.
+--   - region, nation are tiny at any scale factor and are copied whole.
+--   - part, partsupp, supplier are not joined by any demo query, so a
+--     cheap independent key-range slice is fine.
+
+CREATE OR REPLACE TABLE migration_demo.tpch.region AS SELECT * FROM samples.tpch.region;
+CREATE OR REPLACE TABLE migration_demo.tpch.nation AS SELECT * FROM samples.tpch.nation;
+
+CREATE OR REPLACE TABLE migration_demo.tpch.supplier AS
+SELECT * FROM samples.tpch.supplier WHERE s_suppkey <= 10000;
+
+CREATE OR REPLACE TABLE migration_demo.tpch.part AS
+SELECT * FROM samples.tpch.part WHERE p_partkey <= 200000;
+
+CREATE OR REPLACE TABLE migration_demo.tpch.partsupp AS
+SELECT * FROM samples.tpch.partsupp WHERE ps_partkey <= 200000;
+
+-- orders is declared explicitly (rather than `CREATE TABLE ... AS SELECT`)
+-- because o_orderyear is a generated column, and Databricks' ALTER TABLE
+-- ADD COLUMN grammar has no GENERATED clause — only CREATE TABLE's
+-- column_properties does. This is also augmentation "generated column on
+-- orders": it forces a decision between a MATERIALIZED column and an ALIAS
+-- column on ClickHouse.
+
+-- @requires: This hard-coded orders schema may not exactly match samples.tpch.orders's column types on this workspace (untested without a live workspace). If this fails, run DESCRIBE TABLE samples.tpch.orders and adjust the column list below to match, then rerun.
+CREATE OR REPLACE TABLE migration_demo.tpch.orders (
+    o_orderkey      BIGINT,
+    o_custkey       BIGINT,
+    o_orderstatus   STRING,
+    o_totalprice    DECIMAL(18,2),
+    o_orderdate     DATE,
+    o_orderpriority STRING,
+    o_clerk         STRING,
+    o_shippriority  INT,
+    o_comment       STRING,
+    o_orderyear     INT GENERATED ALWAYS AS (year(o_orderdate))
+);
+
+INSERT INTO migration_demo.tpch.orders (
+    o_orderkey, o_custkey, o_orderstatus, o_totalprice, o_orderdate,
+    o_orderpriority, o_clerk, o_shippriority, o_comment
+)
+SELECT o_orderkey, o_custkey, o_orderstatus, o_totalprice, o_orderdate,
+       o_orderpriority, o_clerk, o_shippriority, o_comment
+FROM samples.tpch.orders
+WHERE o_orderkey <= 6000000;
+
+CREATE OR REPLACE TABLE migration_demo.tpch.customer AS
+SELECT * FROM samples.tpch.customer
+WHERE c_custkey IN (SELECT o_custkey FROM migration_demo.tpch.orders);
+
+CREATE OR REPLACE TABLE migration_demo.tpch.lineitem AS
+SELECT * FROM samples.tpch.lineitem WHERE l_orderkey <= 6000000;
+
+-- ── Augmentation 1: VARIANT on orders ────────────────────────────────
+-- Forces a decision: map to ClickHouse JSON, or extract hot keys into
+-- typed columns? VARIANT is native from DBSQL 2024.35 / DBR 15.3.
+
+-- @requires: VARIANT requires DBSQL 2024.35+ or DBR 15.3+. Upgrade the SQL warehouse channel to Current, or use a newer runtime.
+ALTER TABLE migration_demo.tpch.orders ADD COLUMN o_metadata VARIANT;
+
+UPDATE migration_demo.tpch.orders
+SET o_metadata = parse_json(
+    concat(
+        '{"channel":"',
+        element_at(array('web', 'retail', 'partner', 'phone'), cast(pmod(o_orderkey, 4) + 1 AS INT)),
+        '","fulfilment":{"warehouse":"WH-',
+        cast(pmod(o_orderkey, 7) + 1 AS STRING),
+        '","expedited":',
+        CASE WHEN o_orderpriority LIKE '1-URGENT%' THEN 'true' ELSE 'false' END,
+        '},"discount_codes":["',
+        element_at(array('NONE', 'SPRING10', 'LOYALTY5'), cast(pmod(o_orderkey, 3) + 1 AS INT)),
+        '"]}'
+    )
+);
+
+-- ── Augmentation 2: nested types on lineitem ──────────────────────────
+-- ARRAY<STRUCT> and MAP. Forces a decision between ClickHouse Nested,
+-- Array(Tuple(...)), and Map(String, String).
+
+ALTER TABLE migration_demo.tpch.lineitem
+ADD COLUMNS (
+    l_shipping_events ARRAY<STRUCT<status: STRING, event_ts: TIMESTAMP, location: STRING>>,
+    l_attributes      MAP<STRING, STRING>
+);
+
+UPDATE migration_demo.tpch.lineitem
+SET l_shipping_events = array(
+        named_struct(
+            'status', 'PACKED',
+            'event_ts', cast(l_shipdate AS TIMESTAMP),
+            'location', concat('WH-', cast(pmod(l_orderkey, 7) + 1 AS STRING))
+        ),
+        named_struct(
+            'status', CASE
+                          WHEN pmod(l_orderkey, 10) = 0 THEN 'CANCELLED'
+                          WHEN l_returnflag = 'R'       THEN 'RETURNED'
+                          ELSE 'DELIVERED'
+                      END,
+            'event_ts', cast(l_receiptdate AS TIMESTAMP),
+            'location', concat('DC-', cast(pmod(l_partkey, 5) + 1 AS STRING))
+        )
+    ),
+    l_attributes = map(
+        'carrier', element_at(array('UPS', 'FEDEX', 'DHL', 'USPS'), cast(pmod(l_orderkey, 4) + 1 AS INT)),
+        'fragile', CASE WHEN pmod(l_partkey, 11) = 0 THEN 'true' ELSE 'false' END
+    );
+
+-- ── Augmentation 3: TIMESTAMP vs TIMESTAMP_NTZ on lineitem ────────────
+-- Forces UTC normalisation and a DateTime64 precision choice.
+
+-- @requires: TIMESTAMP_NTZ requires DBSQL 2023.35+ or DBR 13.3+.
+ALTER TABLE migration_demo.tpch.lineitem
+ADD COLUMNS (
+    l_committed_at     TIMESTAMP,
+    l_committed_at_ntz TIMESTAMP_NTZ
+);
+
+UPDATE migration_demo.tpch.lineitem
+SET l_committed_at     = cast(l_commitdate AS TIMESTAMP),
+    l_committed_at_ntz = cast(cast(l_commitdate AS TIMESTAMP) AS TIMESTAMP_NTZ);
+
+-- ── Augmentation 4: liquid clustering on lineitem ─────────────────────
+-- Forces a deliberate ClickHouse ORDER BY choice rather than copying a key.
+
+-- @requires: Liquid clustering (CLUSTER BY) requires DBR 13.3+ / DBSQL 2023.40+.
+ALTER TABLE migration_demo.tpch.lineitem
+CLUSTER BY (l_shipdate, l_suppkey);
+
+-- ── Augmentation 5: deletion vectors + a real history to time-travel ──
+-- No ClickHouse equivalent — the agent has to reason about
+-- ReplacingMergeTree, ClickPipes, or deferring CDC entirely.
+
+-- @requires: Deletion vectors require DBR 12.2+ / DBSQL 2023.10+.
+ALTER TABLE migration_demo.tpch.lineitem
+SET TBLPROPERTIES (delta.enableDeletionVectors = true);
+
+DELETE FROM migration_demo.tpch.lineitem
+WHERE l_orderkey IN (
+    SELECT l_orderkey FROM migration_demo.tpch.lineitem LIMIT 500
+);
+
+-- ── Augmentation 6: materialized view (serverless only) ───────────────
+-- Recreated as a ClickHouse Materialized View on AggregatingMergeTree.
+-- Skipped rather than fatal: materialized views need serverless compute,
+-- and a classic warehouse is a perfectly reasonable demo environment.
+
+-- @optional: Materialized views require a serverless SQL warehouse. Skipping — the demo works without it, and sample query 7 should be removed if absent.
+CREATE OR REPLACE MATERIALIZED VIEW migration_demo.tpch.daily_order_summary AS
+SELECT
+    o_orderdate                 AS order_day,
+    o_orderpriority,
+    count(*)                    AS order_count,
+    sum(o_totalprice)           AS daily_revenue
+FROM migration_demo.tpch.orders
+GROUP BY o_orderdate, o_orderpriority;
+
+-- ── Table comments, so the agent's discovery step has something to read ──
+
+COMMENT ON TABLE migration_demo.tpch.orders IS
+    'TPC-H orders, augmented with a VARIANT metadata column and a generated year column.';
+
+COMMENT ON TABLE migration_demo.tpch.lineitem IS
+    'TPC-H lineitem, augmented with nested shipping events, a MAP of attributes, TIMESTAMP/TIMESTAMP_NTZ pair, liquid clustering, and deletion vectors.';
+
+-- ── Recompute statistics so DESCRIBE DETAIL reports useful sizes ──────
+
+ANALYZE TABLE migration_demo.tpch.orders   COMPUTE STATISTICS;
+ANALYZE TABLE migration_demo.tpch.lineitem COMPUTE STATISTICS;
diff --git a/sources/databricks/terraform/demo/README.md b/sources/databricks/terraform/demo/README.md
new file mode 100644
index 0000000..623f48b
--- /dev/null
+++ b/sources/databricks/terraform/demo/README.md
@@ -0,0 +1,142 @@
+# Databricks Terraform module — `demo` (Setup Path B, existing workspace)
+
+This module provisions the MigrationRoom demo inside a Databricks workspace
+you already have. It creates the Unity Catalog namespace, a dedicated
+serverless SQL warehouse, a demo service principal with its own token, and
+(optionally) an S3 staging path for the bulk-unload migration path — then
+runs `setup_workload.py` to seed TPC-H.
+
+If you don't have a workspace yet, see `../workspace/README.md` instead:
+that module creates a fresh serverless workspace and chains into this one.
+
+## What this module creates
+
+| Resource | Purpose |
+|---|---|
+| `databricks_catalog.demo` | Unity Catalog catalog for the demo (`force_destroy=true`) |
+| `databricks_schema.demo` | Schema inside the catalog; together they form `DATABRICKS_NAMESPACE` |
+| `databricks_sql_endpoint.demo` | Serverless PRO SQL warehouse — serverless is required for the workload's materialized-view augmentation |
+| `databricks_service_principal.demo` | Dedicated principal the playground authenticates as |
+| `databricks_obo_token.demo` | 90-day on-behalf-of token for that principal |
+| `databricks_grants.demo_catalog` / `databricks_grants.samples` | USE_CATALOG/USE_SCHEMA/SELECT on the demo catalog and on `samples` (the workload CTAS-copies from `samples.tpch`) |
+| `databricks_permissions.warehouse_usage` | CAN_USE on the warehouse for the demo principal |
+| `null_resource.setup_workload` | Runs `sources/databricks/scripts/setup_workload.py` against the new warehouse to seed TPC-H |
+| *(optional, `enable_s3_staging=true`)* `aws_s3_bucket.staging` + lifecycle + public-access-block | Disposable staging bucket for staged Parquet unloads (7-day expiry) |
+| *(optional)* `databricks_storage_credential.staging`, `aws_iam_role.staging`, `databricks_external_location.staging` | Unity Catalog external location backing the bucket |
+| *(optional)* `aws_iam_user.staging_reader` + access key | Credentials ClickHouse Cloud's `s3()` table function uses to read the staged Parquet — separate from the Unity Catalog credential, which authenticates via an assumed role, not keys |
+
+## Prerequisites
+
+- An existing Databricks workspace with Unity Catalog enabled.
+- A personal access token (PAT) for a **workspace admin** — used only to
+  provision; the demo principal gets its own token as an output. Set as
+  `databricks_token` in `terraform.tfvars`. Alternatively,
+  `databricks_client_id`/`databricks_client_secret` (OAuth) for a
+  service principal — this is how the chained call from `../workspace`
+  authenticates, since a freshly created workspace has no PAT yet. Supply
+  exactly one of the two.
+- **If chaining from `../workspace`:** this module creates
+  `databricks_catalog.demo`, and `CREATE CATALOG` is a metastore-level
+  privilege, not a workspace-level one. The OAuth identity therefore needs
+  to be the account admin service principal described in
+  `../workspace/README.md` (account admin implies metastore-admin
+  capability) — a principal scoped to only workspace-admin will
+  authenticate but fail at catalog creation.
+- `python3` and `pip` on the machine running `terraform` — the
+  `null_resource.setup_workload` provisioner shells out to
+  `setup_workload.py`.
+- **`databricks_grants.samples` can fail on the first `apply`:** the
+  built-in `samples` catalog is often owned by a different metastore
+  admin than the identity running Terraform, in which case granting on
+  it fails at apply time. If that happens, have the metastore admin
+  grant ownership (or `SELECT`/`USE CATALOG`/`USE SCHEMA` on
+  `samples.tpch` directly) to your provisioning principal and re-apply
+  — this is a per-account permission quirk, not a bug in the module.
+- **Only if `enable_s3_staging=true`:** AWS credentials in the shell
+  (`AWS_PROFILE`, or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`) with
+  permission to create S3 buckets, an IAM role, an IAM user, and policies.
+  This module deliberately does **not** take a `databricks_account_id`
+  variable — the `sts:ExternalId` for the IAM trust policy comes from
+  `databricks_storage_credential.staging[0].aws_iam_role[0].external_id`,
+  which the storage credential generates itself. (The account UUID is
+  only needed by the `workspace` module, for the Databricks account API.)
+
+## Usage
+
+```bash
+cd sources/databricks/terraform/demo
+cp terraform.tfvars.example terraform.tfvars
+# Edit: workspace_url, databricks_token
+
+terraform init
+terraform apply
+
+# Capture the .env block:
+terraform output -raw env_block >> ../../../../.env
+```
+
+To enable S3 staging, set `enable_s3_staging = true` (and optionally
+`aws_region`) in `terraform.tfvars`, or pass
+`-var=enable_s3_staging=true` on the `apply` line, with AWS credentials
+already in the shell.
+
+## The re-apply caveat (IAM propagation)
+
+**This is stated plainly because it looks like a bug and isn't one.**
+When `enable_s3_staging = true`, `databricks_external_location.staging`
+validates itself by actually assuming the freshly-created IAM role. IAM is
+eventually consistent — a role that was just created can fail to assume
+for several seconds after `aws_iam_role_policy_attachment` reports done.
+`time_sleep.iam_propagation` (30s) covers the common case, but if your
+`apply` still fails on `databricks_external_location.staging`:
+
+```bash
+terraform apply
+```
+
+Just run it again. It will succeed once IAM has caught up. Do not delete
+the role or the storage credential to "fix" this — nothing is
+misconfigured, IAM propagation is just slower than 30 seconds sometimes.
+
+The storage-credential/IAM ordering is inherently circular (the credential
+needs the role's ARN, the role's trust policy needs the credential's
+external ID), which is why the credential is created first with
+`skip_validation = true` and a constructed ARN string rather than a normal
+resource reference — there is no way to express this as a straight-line
+dependency chain.
+
+## Cost and teardown
+
+A serverless SQL warehouse and (if enabled) S3 storage bill against the
+partner's Databricks/AWS account, not against MigrationRoom. `auto_stop_mins`
+defaults to 10 minutes of idle time before the warehouse suspends — an idle
+warehouse still bills, so don't raise this casually.
+
+```bash
+terraform destroy
+```
+
+removes everything this module created. The catalog and schema are created
+with `force_destroy = true` and the staging bucket with `force_destroy = true`,
+so destroy won't wedge on leftover demo tables or objects.
+
+## Serverless egress caveat
+
+If the workspace has a network connectivity configuration (NCC) that
+restricts serverless egress, the staging bucket's endpoint must be added
+to the allowed list, or the serverless warehouse won't be able to read or
+write staged Parquet through the external location. This is a workspace-
+level setting outside this module's control — check with whoever manages
+the workspace's network policy if `enable_s3_staging=true` and reads/writes
+through the external location fail with a network error.
+
+## Honesty about what's been verified
+
+`terraform apply` for this module has **not** been run against a real
+workspace as part of building it — there were no Databricks or AWS
+credentials available in the environment that wrote it. What was verified
+is that the configuration is syntactically and structurally valid:
+`terraform fmt -check`, `terraform init -backend=false`, and
+`terraform validate` all pass. Provider-side behavior (grants, the OBO
+token, the storage-credential/IAM dance, serverless warehouse creation)
+has not been exercised end-to-end.
diff --git a/sources/databricks/terraform/demo/main.tf b/sources/databricks/terraform/demo/main.tf
new file mode 100644
index 0000000..cb10bc1
--- /dev/null
+++ b/sources/databricks/terraform/demo/main.tf
@@ -0,0 +1,306 @@
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    databricks = {
+      source  = "databricks/databricks"
+      version = ">= 1.124.0"
+    }
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.5.0"
+    }
+    time = {
+      source  = "hashicorp/time"
+      version = ">= 0.11.0"
+    }
+  }
+}
+
+# Authenticates with either a PAT or OAuth M2M. Unset fields must be null,
+# not "" — the provider treats an empty string as an attempt to use that
+# auth method and then fails on ambiguity.
+provider "databricks" {
+  host          = var.workspace_url
+  token         = var.databricks_token != "" ? var.databricks_token : null
+  client_id     = var.databricks_client_id != "" ? var.databricks_client_id : null
+  client_secret = var.databricks_client_secret != "" ? var.databricks_client_secret : null
+}
+
+# The AWS provider can't be lazy: it resolves credentials at configuration
+# time even when every aws_* resource is count=0. Feed dummy creds when
+# staging is off so the Databricks-only path needs no AWS setup at all.
+provider "aws" {
+  region                      = var.aws_region
+  skip_credentials_validation = true
+  skip_requesting_account_id  = true
+  skip_metadata_api_check     = true
+  access_key                  = var.enable_s3_staging ? null : "AKIAIOSFODNN7EXAMPLE"
+  secret_key                  = var.enable_s3_staging ? null : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+}
+
+locals {
+  namespace         = "${var.catalog_name}.${var.schema_name}"
+  staging_role_name = "migrationroom-uc-staging"
+}
+
+# ── Unity Catalog namespace ──────────────────────────────────────────
+resource "databricks_catalog" "demo" {
+  name    = var.catalog_name
+  comment = "MigrationRoom demo catalog — TPC-H with Databricks-specific augmentations."
+  # Keeps `terraform destroy` from failing on a catalog that still has
+  # tables in it. This is a throwaway demo catalog by construction.
+  force_destroy = true
+}
+
+resource "databricks_schema" "demo" {
+  catalog_name  = databricks_catalog.demo.name
+  name          = var.schema_name
+  comment       = "TPC-H SF1 copied from samples.tpch, plus Delta augmentations."
+  force_destroy = true
+}
+
+# ── Serverless SQL warehouse ─────────────────────────────────────────
+# Serverless matters beyond convenience: the workload's materialized-view
+# augmentation only works on serverless compute.
+resource "databricks_sql_endpoint" "demo" {
+  name                      = var.warehouse_name
+  cluster_size              = var.warehouse_size
+  auto_stop_mins            = var.auto_stop_minutes
+  enable_serverless_compute = true
+  warehouse_type            = "PRO"
+}
+
+# ── Demo principal ───────────────────────────────────────────────────
+resource "databricks_service_principal" "demo" {
+  display_name          = var.service_principal_name
+  allow_cluster_create  = false
+  databricks_sql_access = true
+  workspace_access      = true
+}
+
+# On-behalf-of token, so the playground authenticates as the service
+# principal rather than as whoever ran terraform. Keeps DATABRICKS_TOKEN
+# a machine credential and needs no change to DatabricksSource.
+resource "databricks_obo_token" "demo" {
+  application_id   = databricks_service_principal.demo.application_id
+  comment          = "MigrationRoom playground"
+  lifetime_seconds = 90 * 24 * 60 * 60
+}
+
+# ── Grants: read-only on the demo namespace + the samples catalog ─────
+resource "databricks_grants" "demo_catalog" {
+  catalog = databricks_catalog.demo.name
+  grant {
+    principal  = databricks_service_principal.demo.application_id
+    privileges = ["USE_CATALOG", "USE_SCHEMA", "SELECT"]
+  }
+}
+
+# The workload is built by CTAS out of `samples`, so the principal needs
+# to read it. `samples` is a system catalog and always present.
+resource "databricks_grants" "samples" {
+  catalog = "samples"
+  grant {
+    principal  = databricks_service_principal.demo.application_id
+    privileges = ["USE_CATALOG", "USE_SCHEMA", "SELECT"]
+  }
+}
+
+resource "databricks_permissions" "warehouse_usage" {
+  sql_endpoint_id = databricks_sql_endpoint.demo.id
+  access_control {
+    service_principal_name = databricks_service_principal.demo.application_id
+    permission_level       = "CAN_USE"
+  }
+}
+
+# ── Optional: S3 staging for the bulk-unload path ────────────────────
+resource "random_id" "staging_suffix" {
+  count       = var.enable_s3_staging ? 1 : 0
+  byte_length = 4
+}
+
+resource "aws_s3_bucket" "staging" {
+  count         = var.enable_s3_staging ? 1 : 0
+  bucket        = "migrationroom-databricks-${random_id.staging_suffix[0].hex}"
+  force_destroy = true
+}
+
+resource "aws_s3_bucket_public_access_block" "staging" {
+  count                   = var.enable_s3_staging ? 1 : 0
+  bucket                  = aws_s3_bucket.staging[0].id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+# Staged Parquet is disposable — expire it so a forgotten demo doesn't bill.
+resource "aws_s3_bucket_lifecycle_configuration" "staging" {
+  count  = var.enable_s3_staging ? 1 : 0
+  bucket = aws_s3_bucket.staging[0].id
+  rule {
+    id     = "expire-staged-parquet"
+    status = "Enabled"
+    filter {
+      prefix = "migrationkit/"
+    }
+    expiration {
+      days = 7
+    }
+  }
+}
+
+# The storage credential is created FIRST, with skip_validation, pointing at
+# a role ARN built as a string. This is what breaks the circular dependency:
+# the IAM role's trust policy needs the credential's external ID, and the
+# credential needs the role's ARN. Validation is skipped because the role
+# genuinely does not exist yet at this point.
+resource "databricks_storage_credential" "staging" {
+  count           = var.enable_s3_staging ? 1 : 0
+  name            = local.staging_role_name
+  skip_validation = true
+  aws_iam_role {
+    role_arn = "arn:aws:iam::${data.aws_caller_identity.current[0].account_id}:role/${local.staging_role_name}"
+  }
+  comment = "MigrationRoom staging bucket access (managed by terraform)"
+}
+
+data "aws_caller_identity" "current" {
+  count = var.enable_s3_staging ? 1 : 0
+}
+
+data "databricks_aws_unity_catalog_assume_role_policy" "staging" {
+  count          = var.enable_s3_staging ? 1 : 0
+  aws_account_id = data.aws_caller_identity.current[0].account_id
+  role_name      = local.staging_role_name
+  external_id    = databricks_storage_credential.staging[0].aws_iam_role[0].external_id
+}
+
+data "databricks_aws_unity_catalog_policy" "staging" {
+  count          = var.enable_s3_staging ? 1 : 0
+  aws_account_id = data.aws_caller_identity.current[0].account_id
+  bucket_name    = aws_s3_bucket.staging[0].bucket
+  role_name      = local.staging_role_name
+}
+
+resource "aws_iam_policy" "staging" {
+  count  = var.enable_s3_staging ? 1 : 0
+  name   = "${local.staging_role_name}-policy"
+  policy = data.databricks_aws_unity_catalog_policy.staging[0].json
+}
+
+resource "aws_iam_role" "staging" {
+  count              = var.enable_s3_staging ? 1 : 0
+  name               = local.staging_role_name
+  assume_role_policy = data.databricks_aws_unity_catalog_assume_role_policy.staging[0].json
+}
+
+resource "aws_iam_role_policy_attachment" "staging" {
+  count      = var.enable_s3_staging ? 1 : 0
+  role       = aws_iam_role.staging[0].name
+  policy_arn = aws_iam_policy.staging[0].arn
+}
+
+# IAM is eventually consistent: the external location validates by actually
+# assuming the role, which fails for a few seconds after role creation.
+resource "time_sleep" "iam_propagation" {
+  count           = var.enable_s3_staging ? 1 : 0
+  depends_on      = [aws_iam_role_policy_attachment.staging]
+  create_duration = "30s"
+}
+
+resource "databricks_external_location" "staging" {
+  count           = var.enable_s3_staging ? 1 : 0
+  name            = "migrationroom-staging"
+  url             = "s3://${aws_s3_bucket.staging[0].bucket}/migrationkit"
+  credential_name = databricks_storage_credential.staging[0].name
+  comment         = "MigrationRoom staged Parquet unloads"
+  depends_on      = [time_sleep.iam_propagation]
+}
+
+resource "databricks_grants" "staging_location" {
+  count             = var.enable_s3_staging ? 1 : 0
+  external_location = databricks_external_location.staging[0].id
+  grant {
+    principal  = databricks_service_principal.demo.application_id
+    privileges = ["READ_FILES", "WRITE_FILES", "CREATE_EXTERNAL_TABLE"]
+  }
+}
+
+# An access key for ClickHouse Cloud's s3() table function, which reads the
+# staged Parquet. ClickHouse authenticates with keys, not an assumed role,
+# so this is separate from the Unity Catalog credential above.
+resource "aws_iam_user" "staging_reader" {
+  count = var.enable_s3_staging ? 1 : 0
+  name  = "migrationroom-databricks-staging-reader"
+}
+
+resource "aws_iam_user_policy" "staging_reader" {
+  count = var.enable_s3_staging ? 1 : 0
+  name  = "read-staged-parquet"
+  user  = aws_iam_user.staging_reader[0].name
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = ["s3:GetObject", "s3:ListBucket"]
+        Resource = [
+          aws_s3_bucket.staging[0].arn,
+          "${aws_s3_bucket.staging[0].arn}/*",
+        ]
+      },
+    ]
+  })
+}
+
+resource "aws_iam_access_key" "staging_reader" {
+  count = var.enable_s3_staging ? 1 : 0
+  user  = aws_iam_user.staging_reader[0].name
+}
+
+# ── Workload ─────────────────────────────────────────────────────────
+# The workload script needs a PAT and needs write privileges (CREATE
+# CATALOG), so it runs as the provisioning identity, not as the demo
+# service principal. One hour is ample and limits the blast radius if the
+# state file leaks.
+resource "databricks_token" "provisioner" {
+  count            = var.run_workload_setup ? 1 : 0
+  comment          = "MigrationRoom workload setup (short-lived)"
+  lifetime_seconds = 3600
+}
+
+# Runs the same script as `make databricks-setup`, against the warehouse
+# just created. Triggers on the warehouse id so a recreated warehouse
+# re-seeds.
+resource "null_resource" "setup_workload" {
+  count = var.run_workload_setup ? 1 : 0
+
+  triggers = {
+    warehouse_id = databricks_sql_endpoint.demo.id
+    namespace    = local.namespace
+  }
+
+  provisioner "local-exec" {
+    working_dir = "${path.module}/../../../.."
+    command     = <<-EOT
+      python3 -m pip install --quiet -r sources/databricks/scripts/requirements.txt
+      python3 sources/databricks/scripts/setup_workload.py
+    EOT
+    environment = {
+      DATABRICKS_HOST      = var.workspace_url
+      DATABRICKS_HTTP_PATH = databricks_sql_endpoint.demo.odbc_params[0].path
+      DATABRICKS_TOKEN     = databricks_token.provisioner[0].token_value
+    }
+  }
+
+  depends_on = [
+    databricks_schema.demo,
+    databricks_grants.samples,
+  ]
+}
diff --git a/sources/databricks/terraform/demo/outputs.tf b/sources/databricks/terraform/demo/outputs.tf
new file mode 100644
index 0000000..01f6847
--- /dev/null
+++ b/sources/databricks/terraform/demo/outputs.tf
@@ -0,0 +1,28 @@
+output "env_block" {
+  description = "Paste this block into the project's .env file."
+  sensitive   = true
+  value       = <<EOT
+
+# ── Databricks Source (provisioned by terraform) ──────────────
+DATABRICKS_HOST=${var.workspace_url}
+DATABRICKS_HTTP_PATH=${databricks_sql_endpoint.demo.odbc_params[0].path}
+DATABRICKS_TOKEN=${databricks_obo_token.demo.token_value}
+DATABRICKS_NAMESPACE=${local.namespace}
+${var.enable_s3_staging ? "STAGING_S3_BUCKET=${aws_s3_bucket.staging[0].bucket}\nSTAGING_S3_REGION=${var.aws_region}\nSTAGING_S3_PREFIX=migrationkit\nSTAGING_S3_ACCESS_KEY_ID=${aws_iam_access_key.staging_reader[0].id}\nSTAGING_S3_SECRET_ACCESS_KEY=${aws_iam_access_key.staging_reader[0].secret}" : "# (no S3 staging — set enable_s3_staging=true to provision it)"}
+EOT
+}
+
+output "summary" {
+  description = "Human-readable summary of what was created."
+  value = {
+    workspace_url     = var.workspace_url
+    catalog           = databricks_catalog.demo.name
+    schema            = databricks_schema.demo.name
+    namespace         = local.namespace
+    warehouse         = databricks_sql_endpoint.demo.name
+    warehouse_path    = databricks_sql_endpoint.demo.odbc_params[0].path
+    service_principal = databricks_service_principal.demo.display_name
+    staging_bucket    = var.enable_s3_staging ? aws_s3_bucket.staging[0].bucket : null
+    workload_seeded   = var.run_workload_setup
+  }
+}
diff --git a/sources/databricks/terraform/demo/terraform.tfvars.example b/sources/databricks/terraform/demo/terraform.tfvars.example
new file mode 100644
index 0000000..759fa05
--- /dev/null
+++ b/sources/databricks/terraform/demo/terraform.tfvars.example
@@ -0,0 +1,14 @@
+# Databricks workspace to provision the demo into.
+workspace_url    = "https://dbc-xxxxxxxx-xxxx.cloud.databricks.com"
+databricks_token = "dapi................................"
+
+# Optional overrides.
+# catalog_name   = "migration_demo"
+# schema_name    = "tpch"
+# warehouse_name = "migrationroom-demo"
+# warehouse_size = "2X-Small"
+
+# S3 staging for the bulk-unload path. Needs AWS credentials in the shell
+# (AWS_PROFILE, or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY).
+# enable_s3_staging = true
+# aws_region        = "us-east-1"
diff --git a/sources/databricks/terraform/demo/variables.tf b/sources/databricks/terraform/demo/variables.tf
new file mode 100644
index 0000000..2c8fb39
--- /dev/null
+++ b/sources/databricks/terraform/demo/variables.tf
@@ -0,0 +1,93 @@
+variable "workspace_url" {
+  description = "Databricks workspace URL, e.g. https://dbc-xxxxxxxx-xxxx.cloud.databricks.com. When chaining from the workspace module this is supplied automatically via workspace.auto.tfvars.json."
+  type        = string
+}
+
+variable "databricks_token" {
+  description = "Personal access token for a workspace admin. Alternative to databricks_client_id/secret — supply exactly one of the two. Used only to provision; the demo principal gets its own token as an output."
+  type        = string
+  sensitive   = true
+  default     = ""
+
+  validation {
+    condition     = var.databricks_token != "" || var.databricks_client_id != ""
+    error_message = "Set either databricks_token, or databricks_client_id and databricks_client_secret."
+  }
+}
+
+variable "databricks_client_id" {
+  description = "Application ID of a service principal with workspace-admin on workspace_url. Alternative to databricks_token — supply exactly one of the two."
+  type        = string
+  default     = ""
+}
+
+variable "databricks_client_secret" {
+  description = "OAuth secret matching databricks_client_id."
+  type        = string
+  sensitive   = true
+  default     = ""
+}
+
+variable "catalog_name" {
+  description = "Unity Catalog catalog to create for the demo workload. Not currently customizable: sources/databricks/scripts/setup_workload.sql hard-codes migration_demo.tpch in all of its statements, so changing this value only creates a second, ungranted catalog and leaves the seeded data behind in migration_demo. Templating the SQL is a tracked follow-up, not something to do at this merge gate."
+  type        = string
+  default     = "migration_demo"
+
+  validation {
+    condition     = var.catalog_name == "migration_demo"
+    error_message = "catalog_name must stay \"migration_demo\": sources/databricks/scripts/setup_workload.sql hard-codes the migration_demo.tpch namespace in all 25 of its statements. Changing this variable does not retarget the seeding script — it creates and grants a second, empty catalog while the TPC-H data still lands in migration_demo.tpch, ungranted. Templating setup_workload.sql to honor this variable is a follow-up, not something to change here."
+  }
+}
+
+variable "schema_name" {
+  description = "Schema inside the catalog. Together with catalog_name this becomes DATABRICKS_NAMESPACE. Not currently customizable: sources/databricks/scripts/setup_workload.sql hard-codes migration_demo.tpch in all of its statements, so changing this value only creates a second, ungranted schema and leaves the seeded data behind in tpch. Templating the SQL is a tracked follow-up, not something to do at this merge gate."
+  type        = string
+  default     = "tpch"
+
+  validation {
+    condition     = var.schema_name == "tpch"
+    error_message = "schema_name must stay \"tpch\": sources/databricks/scripts/setup_workload.sql hard-codes the migration_demo.tpch namespace in all 25 of its statements. Changing this variable does not retarget the seeding script — it creates and grants a second, empty schema while the TPC-H data still lands in migration_demo.tpch, ungranted. Templating setup_workload.sql to honor this variable is a follow-up, not something to change here."
+  }
+}
+
+variable "warehouse_name" {
+  description = "Name of the dedicated serverless SQL warehouse."
+  type        = string
+  default     = "migrationroom-demo"
+}
+
+variable "warehouse_size" {
+  description = "SQL warehouse cluster size. 2X-Small is enough for TPC-H SF1."
+  type        = string
+  default     = "2X-Small"
+}
+
+variable "auto_stop_minutes" {
+  description = "Idle minutes before the warehouse stops. Keep low — an idle warehouse bills."
+  type        = number
+  default     = 10
+}
+
+variable "service_principal_name" {
+  description = "Display name of the service principal the playground authenticates as."
+  type        = string
+  default     = "migrationroom-demo-sp"
+}
+
+variable "run_workload_setup" {
+  description = "Run sources/databricks/scripts/setup_workload.py after provisioning to create the TPC-H workload. Requires python3 and pip on the machine running terraform."
+  type        = bool
+  default     = true
+}
+
+variable "enable_s3_staging" {
+  description = "Provision an S3 bucket, IAM role, Unity Catalog storage credential, and external location for the S3-staged migration path. Requires AWS credentials in the shell at apply time — that is a second cloud prerequisite, which is why this defaults to false. Migrations work without it via the direct batch path."
+  type        = bool
+  default     = false
+}
+
+variable "aws_region" {
+  description = "AWS region for the staging bucket. Ignored when enable_s3_staging=false."
+  type        = string
+  default     = "us-east-1"
+}
diff --git a/sources/databricks/terraform/workspace/README.md b/sources/databricks/terraform/workspace/README.md
new file mode 100644
index 0000000..96a1ee5
--- /dev/null
+++ b/sources/databricks/terraform/workspace/README.md
@@ -0,0 +1,123 @@
+# Databricks Terraform module — `workspace` (Setup Path B, new environment)
+
+This module creates a **serverless** Databricks workspace from nothing, then
+chains into `../demo`, which provisions the MigrationRoom demo objects
+inside it. Use this when you don't already have a Databricks workspace; if
+you do, use `../demo` directly — see `../demo/README.md`.
+
+## What this module creates
+
+| Resource | Purpose |
+|---|---|
+| `databricks_mws_workspaces.demo` | A new workspace, `compute_mode = "SERVERLESS"` |
+| `databricks_metastore.demo` *(optional, `create_metastore=true`)* | A Unity Catalog metastore |
+| `databricks_metastore_assignment.demo` *(optional)* | Assigns that metastore to the new workspace |
+| `databricks_mws_permission_assignment.provisioner_admin` | Makes the account service principal a workspace ADMIN, so the chained `demo` apply can authenticate against the new workspace |
+
+Serverless is what makes this path prerequisite-free. A "classic" workspace
+needs a cross-account IAM role, a root S3 bucket, and a VPC provisioned
+before the workspace can even be created — that's the entire reason
+Databricks demos are usually multi-step. `compute_mode = "SERVERLESS"`
+skips all of it: no `credentials_id`, no `storage_configuration_id`, no
+`aws` provider anywhere in this module.
+
+## The one manual prerequisite
+
+You need a Databricks account, and an account-level service principal with
+the **account admin** role, created by hand in the account console
+(`accounts.cloud.databricks.com` → Settings → Identity and access → Service
+principals). Terraform authenticates *as* this service principal, so it
+cannot also create it — that would be the tool provisioning its own
+credential. This is "one console visit, then one command," not zero-touch,
+and this README won't pretend otherwise.
+
+Once created, generate an OAuth secret for the service principal and note
+the application (client) ID and the account UUID (both visible in the
+console under your profile).
+
+**Why account admin specifically, not just workspace admin:** the chained
+`demo` apply creates a Unity Catalog catalog
+(`databricks_catalog.demo`), and `CREATE CATALOG` is a **metastore-level**
+privilege, not a workspace-level one — `provisioner_admin` below only
+grants workspace ADMIN. Nothing in this module grants a metastore
+privilege explicitly, because doing so would need the metastore ID and
+would be redundant if the assumption below already holds. The assumption
+is: an account admin has implicit metastore-admin capability, and
+metastore admins can create catalogs, so authenticating as an account
+admin — which you must do anyway for this module's own provider block —
+is what makes the later `CREATE CATALOG` succeed. A service principal
+scoped to something narrower than account admin will authenticate fine
+here and then fail, confusingly, when `demo` tries to create its catalog.
+
+## Usage
+
+```bash
+cd sources/databricks/terraform/workspace
+cp terraform.tfvars.example terraform.tfvars
+# Edit: databricks_account_id, databricks_client_id, databricks_client_secret
+
+terraform init
+terraform apply
+```
+
+That provisions the workspace only. The recommended entry point is
+`make databricks-provision-workspace` from the repo root, which runs this
+module **and then** the `demo` module in one command — it reads this
+module's `workspace_url` output and this module's own
+`terraform.tfvars` (for the OAuth credentials) and writes them into
+`sources/databricks/terraform/demo/workspace.auto.tfvars.json`, which
+Terraform auto-loads. No copy-pasting a workspace URL between two applies.
+
+## `create_metastore`
+
+Defaults to `false`. Databricks auto-provisions one Unity Catalog metastore
+per region for new accounts, and creating a second metastore in the same
+region fails outright — so the safe default is to assume one already
+exists and let workspace creation attach to it automatically.
+
+To tell whether you need `create_metastore = true`: check the account
+console's Catalog section for an existing metastore in your `aws_region`,
+or just try the chained `demo` apply — if it fails because the workspace
+has no metastore assigned, come back here, set `create_metastore = true`,
+and re-apply.
+
+## Cost and teardown
+
+A serverless workspace bills on use — there's no separate "off" state to
+leave it in, but nothing runs (and nothing bills) until `demo` provisions
+warehouses and workloads inside it. This module has no idle-cost concerns
+of its own.
+
+```bash
+terraform destroy
+```
+
+removes the workspace. Destroy `demo` first, or accept that destroying the
+workspace takes everything `demo` created with it (catalogs, warehouses,
+tokens — all of it lives inside the workspace).
+
+## Cloud support
+
+This module targets AWS only (`aws_region`, `databricks_mws_workspaces`
+with `aws_region` set). GCP serverless workspaces use a `location`
+attribute instead of `aws_region` and would need a different resource
+shape; Azure workspaces are not created through
+`databricks_mws_workspaces` at all — Azure Databricks workspaces are
+provisioned through the `azurerm` provider, not the Databricks account
+API. Neither is implemented here.
+
+## Honesty about what's been verified
+
+`terraform apply` has **not** been run against a real Databricks account
+as part of building this module — there were no Databricks credentials
+available in the environment that wrote it. What was verified is that the
+configuration is syntactically and structurally valid: `terraform fmt
+-check`, `terraform init -backend=false`, and `terraform validate` all
+pass against provider `databricks/databricks` v1.124.0. Provider-side
+behavior (serverless workspace creation, the permission assignment, the
+optional metastore path) has not been exercised end-to-end.
+
+The account-admin → implicit-metastore-admin → `CREATE CATALOG` chain
+described above under "The one manual prerequisite" is **documented, not
+verified against a live account** — the same lack-of-credentials caveat
+applies to it as to everything else in this list.
diff --git a/sources/databricks/terraform/workspace/main.tf b/sources/databricks/terraform/workspace/main.tf
new file mode 100644
index 0000000..62398d7
--- /dev/null
+++ b/sources/databricks/terraform/workspace/main.tf
@@ -0,0 +1,59 @@
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    databricks = {
+      source  = "databricks/databricks"
+      version = ">= 1.124.0"
+    }
+  }
+}
+
+# Account-level provider. Note the host: the account API lives at
+# accounts.cloud.databricks.com, not at a workspace URL.
+provider "databricks" {
+  host          = "https://accounts.cloud.databricks.com"
+  account_id    = var.databricks_account_id
+  client_id     = var.databricks_client_id
+  client_secret = var.databricks_client_secret
+}
+
+# A serverless workspace needs NO prerequisite cloud resources — no
+# cross-account IAM role, no root S3 bucket, no VPC. That is the entire
+# reason the new-environment path is one command: the two arguments that
+# would normally point at that IAM role and root bucket must be left
+# unset entirely for compute_mode=SERVERLESS (the provider rejects them
+# if set).
+resource "databricks_mws_workspaces" "demo" {
+  account_id     = var.databricks_account_id
+  workspace_name = var.workspace_name
+  aws_region     = var.aws_region
+  compute_mode   = "SERVERLESS"
+}
+
+# Optional metastore. Most accounts already have one per region and a
+# second in the same region is rejected, so this is opt-in.
+resource "databricks_metastore" "demo" {
+  count         = var.create_metastore ? 1 : 0
+  name          = var.metastore_name
+  region        = var.aws_region
+  force_destroy = true
+}
+
+resource "databricks_metastore_assignment" "demo" {
+  count        = var.create_metastore ? 1 : 0
+  workspace_id = databricks_mws_workspaces.demo.workspace_id
+  metastore_id = databricks_metastore.demo[0].id
+}
+
+# The account service principal terraform is authenticating as needs to be
+# a workspace admin, otherwise the chained `demo` apply cannot reach the
+# new workspace at all.
+data "databricks_service_principal" "provisioner" {
+  application_id = var.databricks_client_id
+}
+
+resource "databricks_mws_permission_assignment" "provisioner_admin" {
+  workspace_id = databricks_mws_workspaces.demo.workspace_id
+  principal_id = data.databricks_service_principal.provisioner.sp_id
+  permissions  = ["ADMIN"]
+}
diff --git a/sources/databricks/terraform/workspace/outputs.tf b/sources/databricks/terraform/workspace/outputs.tf
new file mode 100644
index 0000000..cc41579
--- /dev/null
+++ b/sources/databricks/terraform/workspace/outputs.tf
@@ -0,0 +1,20 @@
+output "workspace_url" {
+  description = "URL of the created workspace. Feeds the demo module's workspace_url variable."
+  value       = databricks_mws_workspaces.demo.workspace_url
+}
+
+output "workspace_id" {
+  description = "Numeric workspace ID."
+  value       = databricks_mws_workspaces.demo.workspace_id
+}
+
+output "summary" {
+  description = "Human-readable summary of what was created."
+  value = {
+    workspace_name    = databricks_mws_workspaces.demo.workspace_name
+    workspace_url     = databricks_mws_workspaces.demo.workspace_url
+    aws_region        = var.aws_region
+    compute_mode      = "SERVERLESS"
+    metastore_created = var.create_metastore
+  }
+}
diff --git a/sources/databricks/terraform/workspace/terraform.tfvars.example b/sources/databricks/terraform/workspace/terraform.tfvars.example
new file mode 100644
index 0000000..ff7013c
--- /dev/null
+++ b/sources/databricks/terraform/workspace/terraform.tfvars.example
@@ -0,0 +1,14 @@
+# From the Databricks account console (accounts.cloud.databricks.com).
+# The service principal must have the account admin role. Creating it is
+# the one manual step in this path — it is the credential terraform uses,
+# so it cannot provision itself.
+databricks_account_id    = "00000000-0000-0000-0000-000000000000"
+databricks_client_id     = "00000000-0000-0000-0000-000000000000"
+databricks_client_secret = "dose................................"
+
+# Optional overrides.
+# workspace_name = "migrationroom-demo"
+# aws_region     = "us-east-1"
+
+# Only if your account has no Unity Catalog metastore in this region.
+# create_metastore = true
diff --git a/sources/databricks/terraform/workspace/variables.tf b/sources/databricks/terraform/workspace/variables.tf
new file mode 100644
index 0000000..bbb0a5d
--- /dev/null
+++ b/sources/databricks/terraform/workspace/variables.tf
@@ -0,0 +1,39 @@
+variable "databricks_account_id" {
+  description = "Databricks account UUID, from the account console (accounts.cloud.databricks.com) under your profile."
+  type        = string
+}
+
+variable "databricks_client_id" {
+  description = "Application ID of an account-level service principal with the account admin role. Created once by hand in the account console — it is the credential terraform authenticates with, so it cannot be provisioned here."
+  type        = string
+}
+
+variable "databricks_client_secret" {
+  description = "OAuth secret for the account-level service principal."
+  type        = string
+  sensitive   = true
+}
+
+variable "workspace_name" {
+  description = "Name of the workspace to create."
+  type        = string
+  default     = "migrationroom-demo"
+}
+
+variable "aws_region" {
+  description = "AWS region the serverless workspace runs in."
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "create_metastore" {
+  description = "Create a Unity Catalog metastore and assign it to the new workspace. Leave false unless you know the region has none: Databricks auto-provisions one per region for new accounts, and creating a second in the same region fails."
+  type        = bool
+  default     = false
+}
+
+variable "metastore_name" {
+  description = "Name for the metastore when create_metastore=true."
+  type        = string
+  default     = "migrationroom-metastore"
+}
diff --git a/tests/requirements.txt b/tests/requirements.txt
new file mode 100644
index 0000000..5a15428
--- /dev/null
+++ b/tests/requirements.txt
@@ -0,0 +1,2 @@
+pytest>=8.0
+sqlglot>=30.0
diff --git a/tests/test_databricks_source.py b/tests/test_databricks_source.py
new file mode 100644
index 0000000..e840c6b
--- /dev/null
+++ b/tests/test_databricks_source.py
@@ -0,0 +1,147 @@
+"""Unit tests for DatabricksSource's pure helpers.
+
+These are the parts testable without a Databricks workspace. The class
+imports `databricks.sql` lazily inside __init__, so importing the module
+needs no connector installed.
+
+Run from the repo root:
+    python3 -m pytest tests/test_databricks_source.py -v
+"""
+import json
+import sys
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "docker" / "migration-runner"))
+
+from migrationkit.sources.databricks import (  # noqa: E402
+    DatabricksSource,
+    normalize_host,
+    parquet_only,
+    split_namespace,
+)
+
+
+@dataclass
+class FakeObject:
+    key: str
+    size: int
+
+
+def test_split_namespace_returns_catalog_and_schema():
+    assert split_namespace("migration_demo.tpch") == ("migration_demo", "tpch")
+
+
+def test_split_namespace_tolerates_whitespace():
+    assert split_namespace("  migration_demo . tpch ") == ("migration_demo", "tpch")
+
+
+@pytest.mark.parametrize("bad", ["", "   ", "tpch", "a.b.c", ".", "a."])
+def test_split_namespace_rejects_anything_but_two_parts(bad):
+    with pytest.raises(ValueError) as excinfo:
+        split_namespace(bad)
+    assert "DATABRICKS_NAMESPACE" in str(excinfo.value)
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("https://dbc-abc.cloud.databricks.com", "dbc-abc.cloud.databricks.com"),
+        ("http://dbc-abc.cloud.databricks.com/", "dbc-abc.cloud.databricks.com"),
+        ("dbc-abc.cloud.databricks.com", "dbc-abc.cloud.databricks.com"),
+        ("  https://dbc-abc.cloud.databricks.com/  ", "dbc-abc.cloud.databricks.com"),
+    ],
+)
+def test_normalize_host_strips_scheme_and_trailing_slash(raw, expected):
+    assert normalize_host(raw) == expected
+
+
+def test_parquet_only_drops_commit_protocol_markers():
+    objects = [
+        FakeObject("p/run/lineitem/part-00000-abc.snappy.parquet", 1000),
+        FakeObject("p/run/lineitem/part-00001-def.snappy.parquet", 2000),
+        FakeObject("p/run/lineitem/_SUCCESS", 0),
+        FakeObject("p/run/lineitem/_committed_12345", 120),
+        FakeObject("p/run/lineitem/_started_12345", 80),
+    ]
+    kept = parquet_only(objects)
+    assert len(kept) == 2
+    assert sum(o.size for o in kept) == 3000
+
+
+def test_parquet_only_is_case_insensitive():
+    assert len(parquet_only([FakeObject("a/B.PARQUET", 1)])) == 1
+
+
+def _unconnected_source(catalog, schema):
+    """Build a DatabricksSource without touching __init__ (no network,
+    no connector import) — enough to exercise the pure `_fq` logic."""
+    src = DatabricksSource.__new__(DatabricksSource)
+    src.catalog = catalog
+    src.schema = schema
+    return src
+
+
+def test_fq_qualifies_a_bare_table_name():
+    src = _unconnected_source("migration_demo", "tpch")
+    assert src._fq("orders") == "migration_demo.tpch.orders"
+
+
+def test_fq_passes_through_an_already_qualified_name_unchanged():
+    src = _unconnected_source("migration_demo", "tpch")
+    assert src._fq("other_catalog.other_schema.orders") == "other_catalog.other_schema.orders"
+
+
+def test_fq_raises_for_bare_name_without_a_configured_namespace():
+    src = _unconnected_source(None, None)
+    with pytest.raises(ValueError):
+        src._fq("orders")
+
+
+class _FakeHTTPResponse:
+    """Minimal stand-in for what `urllib.request.urlopen` returns — supports
+    the context-manager protocol and the `.read()` that `json.load` uses,
+    without touching the network."""
+
+    def __init__(self, body):
+        self._raw = json.dumps(body).encode()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        return False
+
+    def read(self):
+        return self._raw
+
+
+@pytest.mark.parametrize(
+    "malformed_body",
+    [
+        None,  # null body
+        [],  # bare list body
+        {"res": "not-a-list"},  # res is a string
+        {"res": ["not-a-dict"]},  # res item not a dict
+        {"res": [{"metrics": "not-a-dict"}]},  # metrics not a dict
+    ],
+)
+def test_server_ms_from_history_api_returns_none_on_malformed_response(
+    monkeypatch, malformed_body
+):
+    """Regression test: the response shape is an admitted guess against a
+    live API. If the guess is wrong, this must degrade to None, never
+    raise — an uncaught exception here fails the whole benchmark row
+    instead of falling back to wall_ms."""
+    src = DatabricksSource.__new__(DatabricksSource)
+    src._host = "dbc-abc.cloud.databricks.com"
+    src._token = "fake-token"
+
+    monkeypatch.setattr(
+        urllib.request, "urlopen", lambda *a, **kw: _FakeHTTPResponse(malformed_body)
+    )
+
+    assert src._server_ms_from_history_api("stmt-id-123") is None
diff --git a/tests/test_setup_workload_parser.py b/tests/test_setup_workload_parser.py
new file mode 100644
index 0000000..b4e8e59
--- /dev/null
+++ b/tests/test_setup_workload_parser.py
@@ -0,0 +1,66 @@
+"""Unit tests for the setup-workload SQL statement/directive parser.
+
+Run from the repo root:
+    python3 -m pytest tests/test_setup_workload_parser.py -v
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(
+    0, str(Path(__file__).resolve().parents[1] / "sources" / "databricks" / "scripts")
+)
+
+from setup_workload import parse_statements  # noqa: E402
+
+
+def test_plain_statements_are_parsed():
+    parsed = parse_statements("SELECT 1;\nSELECT 2;\n")
+    assert [(s, k) for s, k, _ in parsed] == [("SELECT 1", "plain"), ("SELECT 2", "plain")]
+
+
+def test_comments_are_dropped():
+    parsed = parse_statements("-- a comment\nSELECT 1;\n")
+    assert len(parsed) == 1
+    assert parsed[0][0] == "SELECT 1"
+
+
+def test_requires_directive_attaches_hint():
+    sql = "-- @requires: VARIANT needs DBSQL 2024.35+\nALTER TABLE t ADD COLUMN v VARIANT;\n"
+    statement, kind, hint = parse_statements(sql)[0]
+    assert kind == "required"
+    assert statement.startswith("ALTER TABLE")
+    assert "2024.35" in hint
+
+
+def test_optional_directive_attaches_hint():
+    sql = "-- @optional: needs serverless\nCREATE MATERIALIZED VIEW v AS SELECT 1;\n"
+    statement, kind, hint = parse_statements(sql)[0]
+    assert kind == "optional"
+    assert "serverless" in hint
+
+
+def test_directive_applies_only_to_the_next_statement():
+    sql = (
+        "-- @optional: first only\n"
+        "SELECT 1;\n"
+        "SELECT 2;\n"
+    )
+    parsed = parse_statements(sql)
+    assert parsed[0][1] == "optional"
+    assert parsed[1][1] == "plain"
+
+
+def test_multiline_statement_is_kept_together():
+    sql = "CREATE TABLE t (\n  a INT,\n  b INT\n);\n"
+    parsed = parse_statements(sql)
+    assert len(parsed) == 1
+    assert "a INT" in parsed[0][0] and "b INT" in parsed[0][0]
+
+
+def test_final_statement_without_semicolon_is_kept():
+    parsed = parse_statements("SELECT 1")
+    assert parsed[0][0] == "SELECT 1"
+
+
+def test_empty_input_yields_nothing():
+    assert parse_statements("\n-- only a comment\n") == []
diff --git a/tests/test_sql_guard.py b/tests/test_sql_guard.py
new file mode 100644
index 0000000..af980cd
--- /dev/null
+++ b/tests/test_sql_guard.py
@@ -0,0 +1,232 @@
+"""Unit tests for the Databricks MCP read-only statement guard.
+
+Run from the repo root:
+    python3 -m pip install -r tests/requirements.txt
+    python3 -m pytest tests/test_sql_guard.py -v
+
+sql_guard.py classifies statements by tokenizing/parsing them with sqlglot's
+Databricks dialect rather than hand-lexing, because three earlier review
+rounds each found a real bypass in the hand-lexed version (CTE-prefixed DML,
+a backtick identifier that blinded the CTE scanner, and comment/string
+lexing that diverged from Spark's grammar). The must-allow/must-reject
+lists below are the cases empirically verified against sqlglot 30.15.0
+during the design of this rewrite, including all three of those bypasses.
+"""
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "docker" / "databricks-mcp"))
+
+from sql_guard import SqlNotAllowed, guard  # noqa: E402
+
+# --- Verified cases -------------------------------------------------------
+#
+# The two entries containing a literal carriage return are written with the
+# "\r" escape below (not a raw CR byte) so they survive editors/git intact;
+# Python turns the escape into an actual CR character at parse time.
+
+MUST_ALLOW = [
+    "SELECT 1",
+    "SELECT 1;",
+    "select c from customer",
+    "(SELECT 1)",
+    "SELECT 1 UNION ALL SELECT 2",
+    "WITH x AS (SELECT 1) SELECT * FROM x",
+    "WITH t (n) AS (VALUES (1)) SELECT * FROM t",
+    "WITH RECURSIVE r (n) AS (VALUES (1) UNION ALL SELECT n+1 FROM r WHERE n<6) SELECT * FROM r",
+    "SELECT 1 FROM `a;b`",
+    "SELECT 'a;b' AS s",
+    "SELECT 1 AS `a--b` FROM t",
+    "SHOW CATALOGS",
+    "DESCRIBE TABLE m.t.o",
+    "DESCRIBE DETAIL m.t.l",
+    "DESCRIBE HISTORY m.t.l LIMIT 5",
+    "DESC DETAIL m.t.l",
+    "EXPLAIN SELECT 1",
+]
+
+MUST_REJECT = [
+    # The first five are the previously-verified bypasses.
+    "WITH x AS (SELECT 1) INSERT INTO orders SELECT * FROM x",
+    "WITH x AS (SELECT 1 AS `a) SELECT 2 AS b` FROM t) INSERT INTO orders SELECT * FROM x",
+    "SHOW TABLES -- x\r; DROP TABLE t",
+    "SELECT 1 -- c\r; INSERT INTO orders VALUES (1)",
+    "SELECT 'a\\' AS x, ' ; DROP TABLE t",
+    "SELECT 1; DROP TABLE t",
+    "INSERT INTO t VALUES (1)",
+    "UPDATE t SET a=1",
+    "DELETE FROM t",
+    "DROP TABLE t",
+    "CREATE TABLE t (a INT)",
+    "ALTER TABLE t ADD COLUMN b INT",
+    "TRUNCATE TABLE t",
+    "COPY INTO t FROM 's3://b/k'",
+    "GRANT SELECT ON TABLE t TO `u`",
+    "MERGE INTO t USING s ON t.a=s.a WHEN MATCHED THEN UPDATE SET t.b=s.b",
+    "WITH x AS (SELECT 1) MERGE INTO t USING x ON t.a=x.a WHEN MATCHED THEN DELETE",
+    "OPTIMIZE m.t.l ZORDER BY (a)",
+    "VACUUM m.t.l",
+    "   ",  # empty / whitespace-only
+]
+
+
+@pytest.mark.parametrize(
+    "sql", MUST_ALLOW, ids=[f"allow-{i:02d}" for i in range(len(MUST_ALLOW))]
+)
+def test_verified_read_only_statements_are_allowed(sql):
+    assert guard(sql)
+
+
+@pytest.mark.parametrize(
+    "sql", MUST_REJECT, ids=[f"reject-{i:02d}" for i in range(len(MUST_REJECT))]
+)
+def test_verified_mutations_and_malformed_input_are_rejected(sql):
+    with pytest.raises(SqlNotAllowed):
+        guard(sql)
+
+
+def test_multi_statement_error_message_mentions_one_statement():
+    with pytest.raises(SqlNotAllowed) as excinfo:
+        guard("SELECT 1; DROP TABLE t")
+    assert "one statement" in str(excinfo.value)
+
+
+def test_mutation_error_message_points_to_clickhousectl():
+    with pytest.raises(SqlNotAllowed) as excinfo:
+        guard("DROP TABLE t")
+    assert "clickhousectl" in str(excinfo.value)
+
+
+def test_trailing_comment_after_semicolon_is_not_a_second_statement():
+    # Regression: sqlglot.parse() emits a synthetic exp.Semicolon node to
+    # carry a comment that trails the terminator. That node is truthy, so
+    # it survived the `if s` None-filter and made this look like two
+    # statements. It must not, since it fails closed either way but a
+    # trailing comment on a query is ordinary input.
+    assert guard("SELECT 1; -- comment") == "SELECT 1\nLIMIT 200"
+
+
+def test_trailing_comment_fix_does_not_widen_the_multi_statement_gate():
+    # Paired negative case: a *real* second statement after the comment
+    # must still be rejected. The exp.Semicolon filter must not swallow
+    # an actual statement, only the content-free placeholder node.
+    with pytest.raises(SqlNotAllowed):
+        guard("SELECT 1; -- comment\nDROP TABLE t")
+
+
+# --- LIMIT injection -------------------------------------------------------
+
+
+def test_limit_word_inside_backtick_alias_gets_exactly_one_real_limit():
+    out = guard("SELECT 1 AS `x LIMIT 5` FROM t")
+    # The backtick alias contains the word LIMIT verbatim; only the
+    # appended clause should introduce a *new* line starting with LIMIT.
+    assert out.count("\nLIMIT") == 1
+    assert out.endswith("LIMIT 200")
+
+
+@pytest.mark.parametrize(
+    "sql",
+    [
+        "SHOW CATALOGS",
+        "DESCRIBE TABLE m.t.o",
+        "DESC DETAIL m.t.l",
+        "EXPLAIN SELECT 1",
+    ],
+)
+def test_show_describe_explain_receive_no_limit(sql):
+    assert "LIMIT" not in guard(sql)
+
+
+def test_limit_is_injected_using_max_rows():
+    assert guard("SELECT * FROM orders", max_rows=50).endswith("LIMIT 50")
+
+
+def test_existing_limit_is_not_doubled():
+    out = guard("SELECT * FROM orders LIMIT 5", max_rows=50)
+    assert out.lower().count("limit") == 1
+
+
+def test_union_without_limit_gets_one_appended():
+    out = guard("SELECT 1 UNION ALL SELECT 2", max_rows=10)
+    assert out.count("\nLIMIT") == 1
+    assert out.endswith("LIMIT 10")
+
+
+def test_union_with_existing_limit_is_not_doubled():
+    out = guard("SELECT 1 UNION ALL SELECT 2 LIMIT 1", max_rows=10)
+    assert out.lower().count("limit") == 1
+
+
+def test_parenthesized_select_without_limit_gets_one_appended():
+    # Regression: a top-level `(SELECT ...)` parses to exp.Subquery, not
+    # exp.Select/exp.Union, and was previously exempted from LIMIT
+    # injection entirely — silently defeating the row cap.
+    out = guard("(SELECT * FROM orders)", max_rows=50)
+    assert out == "(SELECT * FROM orders)\nLIMIT 50"
+
+
+def test_parenthesized_select_with_existing_limit_is_not_doubled():
+    # The existing LIMIT lives on the inner Select, not the outer
+    # Subquery; both slots must be checked or this gets a second LIMIT.
+    out = guard("(SELECT * FROM orders LIMIT 5)", max_rows=50)
+    assert out == "(SELECT * FROM orders LIMIT 5)"
+    assert out.lower().count("limit") == 1
+
+
+def test_parenthesized_union_without_limit_gets_one_appended():
+    out = guard("(SELECT * FROM a UNION ALL SELECT * FROM b)", max_rows=50)
+    assert out == "(SELECT * FROM a UNION ALL SELECT * FROM b)\nLIMIT 50"
+
+
+def test_parenthesized_union_with_existing_limit_is_not_doubled():
+    out = guard(
+        "(SELECT * FROM a UNION ALL SELECT * FROM b LIMIT 5)", max_rows=50
+    )
+    assert out == "(SELECT * FROM a UNION ALL SELECT * FROM b LIMIT 5)"
+    assert out.lower().count("limit") == 1
+
+
+# --- guard returns the original text, never a sqlglot regeneration --------
+
+
+def test_guard_returns_original_text_with_only_limit_appended():
+    sql = "SELECT  1,   `weird  Name` FROM   t"
+    out = guard(sql, max_rows=77)
+    assert out == sql + "\nLIMIT 77"
+
+
+def test_guard_preserves_original_formatting_when_no_limit_is_appended():
+    sql = "SHOW   CATALOGS"
+    assert guard(sql) == sql
+
+
+def test_guard_strips_the_trailing_semicolon_before_appending_limit():
+    out = guard("SELECT 1;", max_rows=5)
+    assert out == "SELECT 1\nLIMIT 5"
+
+
+def test_guard_strips_trailing_semicolon_when_no_limit_is_needed():
+    out = guard("SHOW CATALOGS;")
+    assert out == "SHOW CATALOGS"
+
+
+def test_guard_does_not_double_strip_semicolon_inside_backtick():
+    sql = "SELECT 1 FROM `a;b`"
+    out = guard(sql, max_rows=5)
+    assert out == sql + "\nLIMIT 5"
+
+
+# --- misc -------------------------------------------------------------
+
+
+def test_empty_statement_is_rejected():
+    with pytest.raises(SqlNotAllowed):
+        guard("")
+
+
+def test_whitespace_only_statement_is_rejected():
+    with pytest.raises(SqlNotAllowed):
+        guard("   \n\t  ")
diff --git a/workloads/tpch/README.md b/workloads/tpch/README.md
index 19c0cc5..733c181 100644
--- a/workloads/tpch/README.md
+++ b/workloads/tpch/README.md
@@ -11,7 +11,12 @@ ClickHouse OSS all have loaders under `<source>/`. The Snowflake source
 keeps its existing
 [`SNOWFLAKE_SAMPLE_DATA.TPCH_SF1`](../../sources/snowflake/scripts/setup_workload.sql)
 copy path because Snowflake hosts the data for free — different mechanics,
-same end-state.
+same end-state. The Databricks source likewise keeps its own
+[`setup_workload.sql`](../../sources/databricks/scripts/setup_workload.sql),
+downsampling the built-in `samples.tpch` catalog instead of loading from
+this directory's `.tbl` files — but it implements the same four-item
+augmentation contract in Databricks's idiom (see
+[`augmentations.md`](augmentations.md) for the per-engine breakdown).
 
 The Postgres and ClickHouse OSS loaders create a NEW `tpch` database
 alongside the bundled e-commerce / web-analytics workloads — partners
diff --git a/workloads/tpch/augmentations.md b/workloads/tpch/augmentations.md
index 503df30..a036491 100644
--- a/workloads/tpch/augmentations.md
+++ b/workloads/tpch/augmentations.md
@@ -27,6 +27,7 @@ Add an `order_metadata` column carrying these four keys per order:
 |---------------|-----------------------|
 | Snowflake     | `VARIANT` (populated via `OBJECT_CONSTRUCT`) |
 | BigQuery      | `STRUCT<...>`         |
+| Databricks    | `VARIANT` (populated via `parse_json`) |
 | PostgreSQL    | `JSONB`               |
 | ClickHouse OSS| `Map(String, String)` or `JSON` |
 
@@ -56,6 +57,7 @@ Also: cluster or partition `lineitem` on `l_shipdate` and order on
 |---------------|----------------|
 | Snowflake     | `delivery_at TIMESTAMP_TZ` + `CLUSTER BY (l_orderkey, l_shipdate)` |
 | BigQuery      | `delivery_at TIMESTAMP` + `PARTITION BY DATE(l_shipdate)` + `CLUSTER BY l_orderkey` |
+| Databricks    | `l_committed_at TIMESTAMP` (UTC-normalized) + `l_committed_at_ntz TIMESTAMP_NTZ` (naive) pair + liquid clustering `CLUSTER BY (l_shipdate, l_suppkey)` |
 | PostgreSQL    | `delivery_at TIMESTAMPTZ` + BRIN index on `l_shipdate` |
 | ClickHouse OSS| `delivery_at DateTime64(3, 'America/New_York')` + `ORDER BY (l_shipdate, l_orderkey)` |
 
@@ -75,6 +77,7 @@ Materialise a daily revenue rollup over `orders`, grouped by
 |---------------|------------------------|
 | Snowflake     | `DYNAMIC TABLE daily_order_summary` with `TARGET_LAG = '1 hour'` |
 | BigQuery      | `MATERIALIZED VIEW daily_order_summary` (auto-refresh on commit) |
+| Databricks    | `MATERIALIZED VIEW daily_order_summary` (serverless SQL warehouse only — skipped, not fatal, on a classic warehouse) |
 | PostgreSQL    | `MATERIALIZED VIEW daily_order_summary` (manual `REFRESH`) |
 | ClickHouse OSS| Pre-existing `MATERIALIZED VIEW mv_daily_stats` on `AggregatingMergeTree` |
 
@@ -97,10 +100,13 @@ Per-row generation rule (deterministic from `c_custkey`):
 |---------------|-------------|
 | Snowflake     | `ARRAY` of `OBJECT` (via `VARIANT`) |
 | BigQuery      | `ARRAY<STRUCT<line STRING, city STRING, country STRING>>` |
+| Databricks    | `ARRAY<STRUCT<status STRING, event_ts TIMESTAMP, location STRING>>` + a sibling `MAP<STRING, STRING>` — placed on `lineitem` (`l_shipping_events` / `l_attributes`), not `customer`; Databricks's demo shapes this augmentation as shipping events rather than contact addresses |
 | PostgreSQL    | `JSONB` array of objects |
 | ClickHouse OSS| `Array(Tuple(line String, city String, country String))` |
 
 **Migration decision:** ClickHouse `Array(Tuple(...))` (typed, fast) vs.
-`Array(JSON)` (lazy, flexible). Snowflake has no clean
-`ARRAY<STRUCT>` equivalent — partners migrating from Snowflake may not
-encounter this; that's fine. BigQuery and Postgres partners will.
+`Array(JSON)` (lazy, flexible), plus (for Databricks) a `Map(String,
+String)` vs. `Map(LowCardinality(String), String)` call for the sibling
+MAP column. Snowflake has no clean `ARRAY<STRUCT>` equivalent — partners
+migrating from Snowflake may not encounter this; that's fine. BigQuery,
+Databricks, and Postgres partners will.