Deployment
MDMongoose deploys as one bundle (databricks.yml). Nothing has to be built beforehand: Databricks Apps
installs the Python and JavaScript dependencies and builds the UI when the app is deployed.
Requirements
- A Databricks workspace with Unity Catalog and serverless compute — Databricks Free Edition works.
- A catalog you can create schemas in (default:
workspace). - A serverless SQL warehouse. By default the bundle uses the one named Serverless Starter Warehouse.
Option A — from a Git folder (no local tools)
- In the workspace, create a Git folder from the MDMongoose repository.
- Open
databricks.ymlin it and open the Deployments panel (rocket icon). - Choose the target free (or your own target) and click Deploy.
- In the same panel, under Bundle resources, run the job mdm_init and wait until it finishes.
- Start the app mdm (Compute → Apps → mdm → Start / Deploy) and open its URL.
Option B — with the Databricks CLI
databricks bundle deploy --var catalog=workspace
databricks bundle run mdm_init # table, system definitions, demo data, grants, first load and export
databricks bundle run mdm # deploys and starts the app
Variables
| Variable | Default | Meaning |
|---|---|---|
catalog | workspace | Catalog for the schemas mdm_core, mdm_staging and mdm_export. |
demo | "true" | Seeds demo data: customers from 3 sources, suppliers, employees and a product hierarchy. Use "false" for a clean install. |
app_name | mdm | Name of the Databricks App. |
warehouse_id | looked up | The SQL warehouse of the app; override with --var warehouse_id=.... |
With a catalog other than workspace, also set MDM_NODES_TABLE in app.yaml to
<catalog>.mdm_core.mdmnodes.
What mdm_init does
- Creates
MDMNodes(or upgrades its layout on an existing deployment, then runsOPTIMIZE). - Seeds the system nodes: PropertyTypes, Actions, NodeTypes, Permissions and the four top-level branches.
- With
demo = "true": creates the demo source tables inmdm_staging(change data feed on), loads them and builds the golden records for Customer, Supplier and Employee. - Grants the app's service principal access to the schemas and the warehouse. If it prints that it could not,
run
sql/grants.sqlonce as a workspace admin. - Runs the export pipeline once, which also builds the lookup index.
mdm_init is safe to run again: it only adds what is missing and never overwrites your edits.
Upgrading
- Pull the new version into the Git folder (or
git pulllocally). - Deploy the bundle again.
- Run mdm_init once — new system definitions are added to the existing NodeTypes, and layout changes are applied.
- Redeploy the app if it was running.
The release notes on the News & blog page say when an upgrade needs mdm_init.
Free Edition notes
For a complete walkthrough on a free account, see Demo on Free Edition.
- Everything is serverless; the app uses the single starter warehouse.
- Apps stop after a while; start the app again from the Apps page — all data stays in Delta.
- Background actions start a serverless job: expect about a minute of start-up. Saves in the UI are direct and take a few seconds.
- Keep the hourly mdm_refresh job paused unless you need scheduled loads (daily compute quota).
Run it locally
For evaluation or development, the repository runs without Databricks, with an in-memory demo:
pip install -e ".[app,dev]"
pytest
scripts/dev.sh # API on :8000 with MDM_LOCAL=1, UI on :5173