Skip to main content

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)​

  1. In the workspace, create a Git folder from the MDMongoose repository.
  2. Open databricks.yml in it and open the Deployments panel (rocket icon).
  3. Choose the target free (or your own target) and click Deploy.
  4. In the same panel, under Bundle resources, run the job mdm_init and wait until it finishes.
  5. 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​

VariableDefaultMeaning
catalogworkspaceCatalog 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_namemdmName of the Databricks App.
warehouse_idlooked upThe 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 runs OPTIMIZE).
  • Seeds the system nodes: PropertyTypes, Actions, NodeTypes, Permissions and the four top-level branches.
  • With demo = "true": creates the demo source tables in mdm_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.sql once 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​

  1. Pull the new version into the Git folder (or git pull locally).
  2. Deploy the bundle again.
  3. Run mdm_init once — new system definitions are added to the existing NodeTypes, and layout changes are applied.
  4. 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