Introduction
A step-by-step guide to take a database from its real schema to corrected data: reverse-engineer the collections, work the editable ER diagram, run the audit with a health score, transform the data through a safety ladder, and finally generate DDL or apply changes back to MongoDB.
How to read this manual
Each step has:
- Do — the exact action (click, type, run such-and-such command).
- See — what should happen on screen. This is your “pass / fail”.
- Why — extra context, only when it helps (skip it if you're in a hurry).
Before you start
Concept
What Data Modeling is
Data Modeling reverse-engineers your live collections into an editable ER diagram, audits it for anti-patterns with a health score, and lets you fix both the model and the data — then generate DDL or apply the changes back to the database.
Heads-up
When a connection is needed
An active connection is required to Generate the model and to write to the database (audit fixes, transforms, Apply to DB). Everything else — editing the canvas, auditing, generating DDL, import/export — works offline.
You will need:
- 1A connected MongoDB deployment with at least one database that has data to sample.
- 2Open the screen from Home → Data Modeling card, or from the menu Tools ▸ Schema & Data ▸ Data Modeling.
- 3Ideally a test database — Stage 4 can write to your data, so practice where a mistake is harmless.
Estimated time for the full walkthrough: ~25 minutes.
Generate the model
Reverse-engineer a live database into an ER diagram and freeze it as the “Observed” baseline.
Open Data Modeling
With a connection active, open the screen from the Home → Data Modeling card, or from the menu Tools ▸ Schema & Data ▸ Data Modeling.
The Data Modeling canvas opens, with a database selector in the toolbar and a Generate button.
Pick the database(s)
In the toolbar selector, choose the database to model — or pick several to build a cross-DB model.
The chosen database(s) are selected, ready to generate from.
Selecting multiple databases lets the inference find relations that cross database boundaries, not just within one DB.
Click Generate
Click Generate to reverse-engineer the model from the connection.
A progress bar runs through the stages LISTING → SAMPLING → ANALYZING → INFERRING → DONE. You can Cancel at any point.
It samples each collection, infers fields and types, reads existing indexes and validators, and infers relations from the sampled data.
Read the inferred relations
Relations are inferred two ways: by FK — fields like *_id / *Id / *Ref that match another collection's _id and are confirmed against the data — and by shared field — the same identifier name appearing across collections.
Concept
Inference, not magic. The tool only proposes a relation when the field name pattern and the sampled values line up with a target _id. You can edit or delete any relation later.
Inspect the ER diagram
The ER diagram appears: collections as cards, fields with badges (PK/FK/UK/NN/ENUM/CK), and relations as lines — blue = FK, amber = shared field, dashed = inferred.
Note the Observed baseline
This generated state becomes the frozen “Observed” baseline that the Diff in Stage 5 compares against.
Everything you edit from here on is measured as a delta against this snapshot — that's how renames and additions are tracked precisely.
Edit the canvas
Arrange, inspect, and shape the model — collections, fields, validation and relations — all offline and undoable.
Move, arrange, zoom and pan
Drag cards to move them (Ctrl/Cmd-click for multi-select); click ✦ Arrange to re-pack the layout; use −/+/%/Fit for zoom; hold Alt+drag or use the middle button to pan.
Cards reposition, the layout re-packs on Arrange, and the viewport zooms and pans smoothly.
Inspect a collection
Double-click a collection card to open the inspector.
The inspector opens showing that collection's fields and indexes.
Edit fields
Use + Add field, rename (Enter), change type, or remove (×). Per field, set Validation (required / enum / checks).
New fields appear; validation produces the badges NN (required), ENUM, and CK (check) on the field.
Add a collection
Click + Add collection and enter the namespace as db.collection. Rename collections the same way.
A new collection card appears on the canvas with the namespace you typed (for example db.orders).
Create and edit relations
Drag from a field's dot (○) to another collection to create a relation. Double-click the line to edit sides/cardinality/note; double-click the arrow to invert direction; drag a waypoint to curve the line; press ×/Delete to remove.
A relation line is drawn between the fields, and editing reflects in its sides, cardinality and shape.
Undo and redo
Use Undo/Redo (↶ ↷) to step backward and forward through your edits.
The canvas reverts or re-applies each edit in order.
Concept
All offline. Editing the canvas never touches the database — it only changes the in-memory model until you explicitly apply a fix, transform or DDL.
Audit + one-click fix
Score the model, read the verdicts by severity, and apply non-destructive fixes to the model, the database, or both.
Run the audit
Click ✓ Audit to open the audit panel.
A health score (A–E) appears, plus verdicts by severity: 🔴 err / 🟡 warn / ℹ️ info. Filters let you show all / errors / warnings / info.
Read the anti-patterns
Detected anti-patterns include: unbounded array, bloated document (too many fields), mixed-type field, date-as-string, FK without index, collection with no validation, and missing `_id`. Each verdict states what was detected, why it matters, and the best practice.
Apply a one-click fix
On a fixable verdict, use the one-click fix — for example create index (for an FK without index) or apply validation ($jsonSchema). Choose the target Model / Database / Both, then click Apply.
The fix is applied non-destructively. If the target includes Database or Both, the write enters the changeset.
These fixes are additive — they create an index or attach a $jsonSchema validator; they never drop data or rewrite documents.
Send a verdict to Transform
Verdicts tagged → Transform (for example date-as-string or mixed-type) open the transformation ladder covered in Stage 4.
Clicking the tag carries the verdict into the transform flow, pre-targeted at the offending field or collection.
Transform data (safety ladder)
This stage fixes the data, not just the model. Every write climbs a four-rung safety ladder before it touches a single document.
Preview the change
Open the ladder from an audit verdict, a model diff, a custom pipeline, or a reference inline. Start with Preview.
Preview shows before / after for the first affected documents — and writes nothing.
Dry-run for counts
Run Dry-run to measure the impact.
Dry-run reports affected / total / bytes, and marks the job “large” when it exceeds 250k docs or 1 GB.
Heads-up
Dry-run does not write
Both Preview and Dry-run are read-only. They compute counts and samples without modifying any document — nothing is written until you reach Apply.
Take a backup
Take a Backup (optional, but forced if the job is large) — a timestamped copy via $out.
A timestamped backup collection is created so you can restore if the transform goes wrong.
Apply the transform
Type the collection name to unlock Apply. Then Apply pipeline in place (idempotent, via $merge) — or run in the background as a Task for large collections.
The documents are transformed. Each write becomes an AppliedChange recorded with its equivalent mongosh command.
The $merge write is idempotent — re-running the same transform converges to the same result instead of double-applying.
Use the variations
Try the variations: a custom pipeline (paste your own aggregation plus a destination — in-place or a new collection) and inline (collapse a referenced collection into the parent via $lookup, with an option to drop the FK field).
Both variations run through the same four-rung ladder — Preview → Dry-run → Backup → Apply.
Observed × Target diff
Compare the edited model against the frozen Observed baseline and turn a delta into a transform.
Open the diff
Click ⇆ Diff (enabled once there are changes) to list the delta since “Observed”.
The diff lists added / removed / changed collections, fields, indexes and validation as +N −M ~L.
Confirm recognized renames
Renames are recognized from the edit log — so a renamed field shows as a rename (not a drop + add), and the data is preserved through the transform.
Generate a transform from a delta
From a delta entry, generate a custom transform and apply it to the database through the ladder.
The transform builder opens pre-filled from the delta, ready to run via Preview → Dry-run → Backup → Apply.
DDL & apply to DB
Generate a mongosh script to recreate the model, or create the missing collections directly — without overwriting what already exists.
Generate the DDL script
Choose File ▸ DDL (mongosh) to generate a script that recreates the model.
The script contains createCollection with $jsonSchema, the indexes, and FK indexes for each relation (with an “include inferred FK” option), generated per database.
Copy or download the script
Use Copy or Download to save the generated DDL.
The full mongosh script is on your clipboard or in your Downloads folder, ready to run.
Apply to DB
Click Apply to DB to create the collections (with validator + indexes) that do not yet exist.
Missing collections are created; existing ones are not overwritten. Each creation enters the changeset.
Heads-up
Apply to DB is additive only. It never overwrites or alters a collection that already exists — it only fills in what's missing.
Import/Export & history
Save and load the model, export a readable report, and review every database write made this session.
Open and save the model
Use File ▸ Open / Save to load or store the model as JSON.
The model is written to / read from a JSON file, so you can version it or share it.
Export a report
Use Export HTML/PDF to produce a readable report of the model.
An HTML or PDF document is generated for sharing or archiving.
Review the change history
Open File ▸ Changes to review the session log of every database write.
Each entry records timestamp · type · namespace · mongosh command — the audit trail of everything this session wrote to the database.
Concept
This is your receipt. Every audit fix, transform, and Apply to DB creation shows up here with the exact mongosh command it ran.
Cleanup (when you're done)
Be honest about what touched the database. Editing, auditing, DDL generation, and import/export are all offline and safe — they never write. The only database writes are the audit fixes, transforms, and Apply to DB creations you explicitly ran.
Open File ▸ Changes to see the complete list of writes made this session.
Every recorded write matches a fix, transform, or DDL apply you triggered on purpose.
Heads-up
If you applied a transform on test data, drop or restore the affected collections as needed — backups taken in Stage 4 are timestamped copies you can restore from.
Summary of what you validated
| Stage | Feature |
|---|---|
| 1 | Generate the ER model from a live database and freeze the Observed baseline |
| 2 | Edit the canvas — arrange, fields, validation badges, collections and relations |
| 3 | Audit with a health score and apply non-destructive one-click fixes |
| 4 | Transform data through the Preview → Dry-run → Backup → Apply safety ladder |
| 5 | Diff Observed × Target and generate a transform from a delta |
| 6 | Generate DDL (mongosh) and Apply to DB without overwriting existing collections |
| 7 | Import/Export the model and review the full change history |