MongoDB Database Design: Schema Visualization with Diagrams

A MongoDB database hands you the names of its collections and nothing else. DbSchema fills in the rest by reading the documents: connect, and every collection lands on a diagram as a node listing the fields found inside it, with the nested objects and arrays under them.

How the diagram gets there matters, because it is inferred rather than declared. DbSchema introspects a configurable sample of documents per collection and derives the field names, the BSON types, the nested objects and the arrays from what that sample holds, so the diagram approximates what the sampled documents contain and is never a structure MongoDB enforces. Where a collection carries a validation rule, DbSchema reverse-engineers that rule instead and treats it as the collection's authoritative structure.

The walkthrough below runs from the connection to the exported documentation:

1. Connecting DbSchema to MongoDB
2. Inserting a JSON document
3. What reverse-engineering reads
4. Designing the structure on the canvas
5. Validation rules on collections
6. Virtual relations between collections
7. Browsing related documents
8. Interactive HTML5 documentation
9. Queries, test data and synchronization

From a connection to a diagram

Connecting DbSchema to MongoDB

1. Pick MongoDB from the database list, and DbSchema opens the Connection Dialog preconfigured for it.
2. Fill in the host, the port and the credentials, or paste a connection string.

DbSchema downloads the JDBC driver it needs without being asked. The driver runs on your own machine and talks to the MongoDB server directly, with no DbSchema server between the two.

Inserting a JSON document

A database with no collections yet gives the diagram nothing to draw. DbSchema can write the first documents for you: paste a JSON document, or load one from a file, name the collection it goes into, and execute.

{
  "firstName": "John",
  "age": 28,
  "hobbies": [ { "name": "Swimming" } ]
}

MongoDB creates the collection on that first insert.

What reverse-engineering reads

DbSchema reads a cloud, remote or on-premise MongoDB instance and lays the collections out as interactive diagrams. The hobbies array above arrives as a nested node rather than a single field. A second document carrying a field this one does not appears as another field on the same node, so the node shows what the sample held. Nothing in the database changes while this runs.

Everything on those diagrams, the layout included, is kept in the design model file, an XML file with a .dbs extension that goes into your repository beside the application code.

What you can change on the diagram

Designing the structure on the canvas

Collections are created and rearranged on the diagram with the mouse.

• Drag a field of one collection onto a field of another to declare a relation.
• Add comments and tags to a collection or a field, so the exported documentation has something to say about it.
• Split the schema across several diagrams, so an authentication diagram and an order diagram can both show the users collection.

Two kinds of change go to two different places. Diagram layout, comments, tags and virtual relations are written to the model file alone, so the running application never sees them; creating a collection or editing its validation rule reaches the database as well.

Validation rules

A validation rule is the one thing in MongoDB that makes a collection's structure binding: a JSON description of the expected document, which the server applies to every insert and update. Double-click a collection header in DbSchema to edit the rule, or create a collection and DbSchema generates the rule for it, and either action saves it to the database and to the model file at once.

How strictly the rule bites is decided by two settings on the collection.

• The validation level says how the rule applies to documents that are already stored when an update touches them.
• The validation action decides what MongoDB does with a write that breaks the rule, rejecting it by default, or letting it through and recording the violation in its log.

Virtual relations

A user document that carries the _id of an order is pointing at another collection, and MongoDB neither declares that link nor enforces it. Nothing rejects a write that breaks it and nothing cascades a delete along it. DbSchema records the link anyway as a virtual relation, also called a virtual foreign key. Drag the field of one collection onto the field it points at in another, and DbSchema draws it as a connector line between the two nodes, exactly as a foreign key is drawn in a relational schema. The definition goes into the model file, not into the database, so the relation costs the running application nothing.

What the model is good for

Browsing related documents

The Relational Data Editor reads those virtual relations and opens several collections side by side, and selecting a document in the parent pane refilters every child pane to the documents whose field values match, cascading as many levels deep as the relations go. A user, that user's orders and the line items of the selected order end up on screen together, with no query and no $lookup.

Interactive HTML5 documentation

Diagram → Export HTML5 or PDF Documentation turns the model into something you can send to a colleague who has no database client. The HTML5 output opens in any browser with no server behind it, carries the diagram as a vector image, and makes the comments you wrote on collections and fields readable as mouse-over tooltips, beside a searchable list of the collections. The same dialog writes PDF for printing and Markdown for a repository.

Open the sample below to see that output.

HTML5 Database Documentation

The inferred schema, the validation rule where one exists, the virtual relations, the browsing across them and this HTML5 export are one chain. Other tools cover parts of it, and the combination is what makes a MongoDB database describable to someone who has never opened it.

Queries, test data and synchronization

The rest of DbSchema works from the same diagram and model file.

• The Query Builder assembles a query on the diagram, following a virtual relation into a related collection as you tick fields and add filters.
• The Data Generator fills collections with test data from prepared patterns, reverse regular expressions, or a Groovy script for nested objects and arrays.
• The Query Editor takes native MongoDB syntax, so a db.employees.find() written for mongosh runs unchanged.
• Schema → Compare Model with Database lists what differs between the model file and a live instance, and Schema → Synchronize Model with Database writes the differences you accept into the database.

Download DbSchema at https://dbschema.com/download.html, connect to your MongoDB instance and let it read the collections: the diagram is there before you have written anything. Connecting, reverse-engineering, the interactive diagrams and the Query Editor are in the free Community Edition. Saving the model to a .dbs file, the Relational Data Editor, the Query Builder, the Data Generator, the HTML5 documentation and the synchronization dialog are Pro.