Teradata to Databricks Migration: What BladeBridge/Lakebridge Automates, and Where It Breaks

By Clayton Severson, Principal Consultant · Published July 6, 2026

Databricks' own migration toolkit — Lakebridge, built on the BladeBridge transpiler it acquired — automates roughly 60–80% of a Teradata migration: standard SQL, functions, types, and views. The other 20–40% — stored procedures, BTEQ, and Teradata-specific constructs — is hand work. And the tool has sharp edges that will stop you cold if you run it the wrong way. Here is what converts automatically, what you rewrite, where the toolchain breaks, and the one-line workaround for when it will not install.

I have been on most sides of this move. I ran Teradata as an analytics platform at a healthcare company, adopted Databricks at a startup, spent time at Databricks itself, and now do migration work in consulting. What follows is the practitioner's version — including the failure modes the marketing pages skip.

What is BladeBridge / Lakebridge?

They are the same toolchain under two names. BladeBridge was a code-conversion company; Databricks acquired it and folded the technology into Lakebridge, the free migration toolkit distributed through Databricks Labs. Inside Lakebridge, "BladeBridge" is now the name of the mature, rule-based transpiler engine — the deterministic converter — sitting next to a newer engine and an LLM-based option. When people say a package "runs under BladeBridge," they mean the layers underneath the Lakebridge CLI wrapper.

What does Lakebridge convert automatically?

Most of the everyday SQL. These are the conversions the transpilers target — the functions, types, and query constructs that have clean Databricks equivalents. Treat the table as what should convert, and verify each in your output: coverage varies by engine and version, and anything the tool does not recognize passes through unchanged rather than raising an error.

Teradata	Databricks	Notes
NULLIFZERO(x)	NULLIF(x, 0)	Function rewrite
ZEROIFNULL(x)	COALESCE(x, 0)	Function rewrite
VARCHAR(n) / CHAR(n)	STRING	Type map
INTEGER	INT	Type map
BYTEINT	TINYINT	Type map
QUALIFY …	QUALIFY …	Native in Databricks SQL (DBR 12+)
SEL	SELECT	Abbreviation expanded
Window functions	Same	Direct equivalent

What do you have to convert by hand?

The Teradata-specific machinery. These constructs either have no Databricks equivalent or need a different pattern entirely, and this is where a migration's real hours go.

Teradata construct	Databricks approach
SET / MULTISET tables	Drop — Delta has no row-uniqueness concept; dedup with MERGE or DISTINCT
PRIMARY INDEX	Drop — cluster with ZORDER or liquid clustering instead
RANGE_N partitioning	PARTITIONED BY / liquid clustering
PERIOD data type	Two DATE/TIMESTAMP columns
COLLECT STATISTICS	ANALYZE TABLE … COMPUTE STATISTICS
BT / ET transactions	Remove — Delta is ACID per statement
Cursors (DECLARE … FETCH)	Set-based MERGE / window functions
EXECUTE IMMEDIATE (dynamic SQL)	Python: spark.sql(f"…")
REPLACE MACRO	Views or SQL/Python functions
BTEQ scripts (.LOGON/.EXPORT/.IF)	Notebooks / Workflows; .EXPORT → COPY INTO or DataFrame write

The three-step workflow: analyze, transpile, reconcile

Once the CLI is installed, the flow is short:

databricks labs install lakebridge
databricks labs lakebridge install-transpile
databricks labs lakebridge analyze   --source-directory ./teradata_sql --report-file ./assessment.xlsx
databricks labs lakebridge transpile --source-directory ./teradata_sql --output-directory ./databricks_sql
databricks labs lakebridge configure-reconcile
databricks labs lakebridge reconcile

analyze produces a spreadsheet that scores every file and statement from LOW to VERY_COMPLEX — read it first and triage, because it tells you exactly how big the manual tail is. transpile writes converted files mirroring your source tree. reconcile compares source and target with row counts, aggregates, and hash matching. When you drive it from a notebook, note that the dialect picker is an interactive menu (select the Teradata source dialect when prompted) — the menu number shifts between versions, so do not hardcode it. The command flags move between Lakebridge releases too — run each with --help rather than copying any guide's exact syntax, including this one.

Where the tool breaks — and how to get past it

This is the part you will not find on the product page, and it is the part that matters. Lakebridge is architected for a developer laptop talking to a workspace. Run it anywhere else — inside a locked-down cluster, behind a corporate firewall — and it fights back.

1. The install hangs on a cluster. On a managed, locked-down cluster, databricks labs install lakebridge downloads the release zipball and then stalls indefinitely at the unpack step:

Debug: Unpacking zipball to: /tmp/.databricks/labs/lakebridge/lib
[hangs — Ctrl+C required]

And a direct pip install of the package imports no better — it expects a project-root layout that a managed cluster does not have:

NotADirectoryError: Cannot find project root

2. The workaround: drop down to the engine. Under the CLI, the actual SQL dialect translation is done by an open-source Python library, sqlglot. It is the piece that does the Teradata-to-Databricks rewriting, and you can call it on its own — no wrapper, no install dance:

import sqlglot
sqlglot.transpile(
    "SELECT NULLIFZERO(balance) FROM customers "
    "QUALIFY ROW_NUMBER() OVER (PARTITION BY id ORDER BY dt DESC) = 1",
    read="teradata", write="databricks")[0]

This is genuinely useful — it gives you dialect translation in exactly the environments where the CLI will not run. But treat the output as a draft, not a finished result. In my own testing, that very snippet came back with NULLIFZERO and the QUALIFY clause unchanged — sqlglot passed the Teradata-specific function straight through, with no warning that it had skipped it. That is the real lesson, and it applies to the whole Lakebridge pipeline: the tools convert most of what they recognize and quietly leave the rest, so the skill is not running the transpiler — it is verifying what it did and did not touch. When the tool won't install, drop to the engine; then read every line it hands back.

3. Firewalled environment: vendor the wheel. If your workspace has no path to PyPI, even pip install sqlglot fails. Commit the wheel into your repo and install it offline, deriving the repo root dynamically so it resolves for any user:

import subprocess
# wheel committed at ./wheels/sqlglot-<version>-py3-none-any.whl
subprocess.check_call(["pip", "install", wheel_path, "--quiet"])
import sqlglot   # now available, no internet required

A few more landmines worth knowing before they cost you an afternoon:

• Serverless can't do it — no Web Terminal and networking limits; use Classic (Photon) compute, or just run the CLI from your laptop.
• /root permission errors on managed clusters — set HOME=/root and call the CLI by its absolute path when scripting it in a subprocess.
• Python 3.13 breaks the installer (SSL certificate issues) — use Python 3.10–3.12 for local installs.
• Interactive prompts hang non-interactive runs — pipe answers in (yes | …, and echo the dialect selection) when calling the CLI from a notebook.
• Unity Catalog with no default storage root blocks CREATE CATALOG — migrate into a pre-existing catalog rather than creating one.

How to replicate this on your own migration

1. Get a source to practice on. If you do not have a spare Teradata system, Teradata's free ClearScape Analytics environment gives you a real instance to load DDL and data into.
2. Install the Databricks CLI locally and configure it (host + token). Run Lakebridge from here, not from inside a cluster.
3. Analyze first. Point lakebridge analyze at your SQL and read the complexity report. Triage LOW → VERY_COMPLEX so you know the size of the manual tail before you commit a timeline.
4. Transpile the bulk. Run install-transpile then transpile, selecting the Teradata dialect. Expect it to nail the standard SQL and flag the rest.
5. Drop to sqlglot when the wrapper won't cooperate — on a cluster, behind a firewall, or in CI. Same conversions, fewer moving parts.
6. Hand-convert the VERY_COMPLEX tail using a simple loop: identify the construct, understand the intent, map it to the Databricks pattern (cursor → MERGE, dynamic SQL → Python, BTEQ → notebook), and test it against the source output.
7. Move the data via Lakehouse Federation, CTAS, deep clone, or MERGE, depending on volume and cutover strategy.
8. Reconcile — counts, aggregates, and hashes per table — and do not call it done until the numbers match.
9. Wrap it in engineering rigor — a validation harness, asset bundles, and CI/CD. This is the step teams skip, and it is the step that separates a migration that holds from one that quietly drifts.

Where migrations actually go wrong

The failure mode is almost never the SQL the tool converts — it is the assumption that the tool converts everything. In practice a Teradata codebase splits roughly into a large majority that is straightforward, a middle band that needs real judgment, and a small but stubborn tail that is genuinely hard: recursive stored procedures, dynamic SQL, BTEQ orchestration, and the Teradata-isms with no clean Databricks analog. Automation eats the majority in an afternoon, which is exactly what lulls teams into underestimating the rest. The engagements that go sideways are the ones that budgeted for the 80% and discovered the 20% in production. The ones that go well treat the transpiler as a fast start on the easy part, and spend their real effort on the hard tail and the validation around it — because a migration is not finished when the code runs, it is finished when the numbers reconcile and a test harness keeps them that way.

Frequently asked questions