@ddt-tools/cli — Databricks Data Tools

The ddt command: declarative schema management for Databricks Unity Catalog. Author each UC object as a .sql file, compare your project against a live workspace, and deploy with a safety classifier that refuses destructive changes unless you opt in.

🚧 Public Beta — all features free during the 30-day beta. AI features are bring-your-own-API-key. After the beta, the free core stays free forever; Pro features keep working with warnings (no hard paywall).

ddt mirrors the sdt (Snowflake) CLI surface command-for-command — a team that knows one learns the other in a day.

Install

npm i -g @ddt-tools/cli
ddt --help

What it does

You describe the desired state of your Unity Catalog schema as SQL files (CREATE OR REPLACE, the Databricks idiom); ddt computes the deltas against the live workspace, classifies each change (SAFE / DESTRUCTIVE / EXPENSIVE / UNRECOVERABLE), emits a reviewable migration script, and captures a manifest for one-command rollback. DDT understands UC-specific failure modes — streaming-table checkpoint loss, managed-table file deletion — that generic SQL tools miss.

ddt init                # scaffold a .ddtproj
ddt extract --target databricks://workspace   # reverse-engineer a live workspace into .sql files
ddt compare --source ./MyProject.ddtproj --target databricks://workspace   # diff + safety classification
ddt publish --source ./MyProject.ddtproj --target databricks://workspace   # generate / apply migration (gated)

Command overview

The CLI surface is broad; the lifecycle commands below are the core, and ddt --help lists the rest (lineage, diagnose, review, lint, drift, refactor, import, MCP server, AI helpers, and more).

| Command | Purpose | | ------------------------------ | ------------------------------------------------------------------------------ | | ddt init | Scaffold a new .ddtproj. | | ddt extract | Snapshot a live Unity Catalog workspace into a project tree. | | ddt build | Compile a .ddtproj into a .ddtpac artifact. | | ddt compare | Diff any pair of: project, pac, live workspace — with per-change safety class. | | ddt publish | Generate (and optionally apply) a migration script. Destructive ops gated. | | ddt drift | Report when a live workspace has drifted from your project / pac. | | ddt validate | Validate a .ddtproj against the schema (and confirm UC reachability). | | ddt connection | Manage Databricks workspace connection profiles (PAT / OAuth-M2M). | | ddt safety explain <code> | Teaching page for a safety finding: why it's dangerous, safer alternatives. | | ddt revert --manifest <path> | Roll back a captured deploy in one command. | | ddt lint / ddt format | Lint and format project SQL. | | ddt lineage / ddt graph | Column-level lineage and dependency graphs. | | ddt import | Migrate from dbt, Liquibase/Flyway, Atlas, raw .sql, and more. | | ddt mcp | Run the MCP server so agents (Claude, Cursor, Continue) can call the engine. | | ddt feedback | Send feedback / report a bug. |

Full reference: docs/CLI_REFERENCE.md. Connection setup: docs/CONNECTION_SETUP.md. Every flag and .ddtproj option is also searchable in-terminal with ddt explain <name>.

AI features (bring your own key)

AI composes on top of the deterministic engine — useful without it. Supply your own API key for Anthropic, OpenAI, Azure OpenAI, any OpenAI-compatible endpoint, or a self-hosted model (Enterprise can route through Databricks Foundation Models). Examples: ddt compare --explain (plain-English diff narration), ddt sketch <kind> (prose → DDL), ddt safer-alternative. Calls are billed by your provider; ddt adds no markup.

Also available

• VS Code extension — "Databricks Data Tools" on the Marketplace (browse, compare, diagram, review).
• Public repo (issues, docs, pricing): https://github.com/GVOrganization/ddt-tools.

Privacy

Opt-in error reporting only. When enabled, ddt sends sanitized diagnostics (error fingerprints, path-stripped stack traces, command name, version) — never your SQL, identifiers, data, or credentials. Toggle with ddt telemetry. See PRIVACY.md.

DDT is an independent tool and is not affiliated with or endorsed by Databricks Inc.

License: Apache-2.0.