Walkthroughs

Document an existing database as an ERD

You bring the tables of an existing database into an ERD (reverse engineering) and turn them into a document with a readable diagram and descriptions. The example is the order-related tables of the demo store database (customer, orders, order_item, product, payment). It depends on the number of tables, but takes about 20 minutes.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

Publishing to the gallery works only in an account project while signed in. All other steps are the same everywhere.

Before you start

Creating an ERD per business area

Do not put a whole schema into one ERD; split ERDs by business area so that tables read together stay together. Nobody reads a diagram with hundreds of tables, and the smaller the scope, the easier it is to bring back in line later. You can put the same table into several ERDs.

  1. In the explorer, right-click the schema to document and choose the Explorer context menuNew ERD... menu. Result: The Create ERD dialog opens with the connection and schema you right-clicked selected.
  2. Enter a business name such as Order management in the ERD Title field (1).
  3. If the diagram needs tables from several schemas, choose the All (allow all schemas) item in the Schema field (3). Result: The ERD is not bound to one schema, so you can place tables from several schemas in it.
  4. Click the OK button (4). Result: An empty ERD tab opens. An ERD bound to one schema accepts only tables of that schema.

Choosing and bringing in tables

  1. In the explorer, expand the schema's Tables group. If there are many tables, type part of a name into the Filter tables... field (3) to narrow them down.
  2. Click a table node (8), then hold Ctrl (Cmd on macOS) and click the other tables to bring in. Hold Shift and click to select a range.
  3. Drag one of the selected tables onto the ERD canvas. Result: NeoSQL reads each table's columns, keys, indexes, foreign keys and comments from the database and places them in the ERD. The tables are placed in a vertical column, and foreign keys between tables brought in together are drawn as relationship lines. The database does not change.
  • Tables already in the ERD are skipped. You can bring in any table you missed the same way at any time.
  • Instead of dragging, you can right-click a table and choose the Explorer context menuAdd to Current ERD menu. It places the table in the middle of the ERD tab in front and saves the ERD right away.
  • The detailed rules for selecting and filtering are covered in Object explorer.

Arranging and grouping automatically

  1. Click the Auto Layout button in the canvas toolbar. Result: The tables are rearranged along their relationships. The layout is information stored in the ERD and has nothing to do with the database.
  2. Drag a few tables to match the order people read them in. For the order flow, place customer → orders → order_item so they read in one line.
  3. If the business area divides further, draw a rectangle with the Add Group button to group those tables (for example, payments). Result: A group appears on the canvas. Like the layout, the group exists only in the ERD and does not change the database.
  4. Use the Fit View button to check that everything fits on one screen.

Auto layout recalculates positions you arranged by hand as well. So run it once after you finish bringing tables in, and fine-tune by hand afterwards. Each tool is described in ERD canvas.

Adding descriptions

For the diagram to read as a document, you need to write down meanings that names alone do not convey. There are three places to write them, and they differ in whether they change the database.

WhereHowDatabase
Logical nameThe logical name field in the table header, and the Logical Name cell of the column gridUnchanged. Stored only in the project
Comment on the canvasPlaced on the canvas with the Add Comment button in the toolbarUnchanged. Exists only in this ERD
Database commentThe Remarks cell of the column grid, and the table comment in the Table detail panelThe database's COMMENT. Editing it creates a change waiting to be applied, and it reaches the database only after you apply it with the Apply Changes to DB... button
  1. Click the Logical mode button (1) in the info panel. Result: The Logical Name cell appears in the column grid.
  2. Click a table to select it and enter logical names for the table and its columns (for example, Order for orders and Order date/time for ordered_at). Result: Logical names do not change the database and are stored only in the project.
  3. Leave anything the reader of the diagram needs to know, such as non-standard abbreviations or business rules, as a comment on the canvas. Result: A canvas comment exists only in this ERD and does not change the database.
  4. If a description should also be visible to people who use the database, write it as a database comment and apply it later. If you cannot change the database, do not edit database comments. Result: Edited database comments are shown in blue as changes waiting to be applied.
  • Comments that already exist in the database come along when the tables are brought in. An unselected table shows its table comment on one line under its name.
  • On a connection with a data dictionary assigned, entering a logical name does not change the name or type of a column that already exists in the database. This keeps documentation from turning into pending changes (Use standard names from a data dictionary).
  • To show logical names in physical mode as well, turn on the Show opposite name on table header item (2). Choose the items to show in the grid in the column item list (3).

Saving

  1. Click the Save button in the info panel, or press Ctrl+S (Cmd+S on macOS). Result: The layout, groups, canvas comments, display mode and logical names are saved to the project. In an account project, the ERD also opens on other devices with the same account.

Exporting an image and sharing

  1. Click the Export Image... button in the toolbar. Result: The Export ERD Image dialog opens.
  2. In the Range item (1), choose the All (All Nodes) item.
  3. In the Format item (2), choose SVG for a document or PNG for a messenger.
  4. Click the Export button (4) to download a file, or for PNG, copy it with the Copy to Clipboard button (3). Result: An image is drawn with the current display mode and column item settings. Export in logical mode for business readers and in physical mode for developers. If you are not signed in, a watermark is added (Export as image).

You can also share in ways other than an image.

MethodWhere it worksDescription
Gallery publishing and embeddingA personal ERD in an account project while signed inUploads a copy of the current state for anyone to see, and embeds it in a blog or wiki as a read-only viewer. Before publishing, check that table names and comments contain no sensitive information (Gallery and embedding)
Team ERDAn account project while signed inTeam members of the same project view and edit it together (Design together with your team)

Bringing the ERD back in line when the database changes

An ERD holds the database as it was when the tables were brought in. If another tool or another person changes the database, the ERD does not follow by itself, so bring it back in line when you revisit the document.

  1. In the explorer, click the schema's refresh button. Result: The table list is read from the database again.
  2. To read the ERD's tables again, select them in the explorer, right-click and choose the Explorer context menuRefresh menu, or select a table in the ERD and click the Refresh button in its node toolbar. Result: The ERD's tables change to the current structure of the database. Logical names, canvas comments and the layout are not in the database, so they stay.
  3. For a table with changes not yet applied to the database (such as an edited comment), you are asked what to do. Click the Replace button to match the database, or the Merge button to keep the unapplied changes.
  4. Drag newly created tables in from the explorer, and remove tables that no longer exist in the database from the ERD with the Remove from ERD button in the info panel. Result: A removed table disappears only from the ERD's diagram, and the database does not change.
  5. Tidy the layout with the Auto Layout button or by hand, then save.
  • The Replace button discards all unapplied changes. To keep edited comments, apply them to the database first or choose the Merge button.
  • To see the structural differences between two databases (for example, development and production), use Schema compare.

What's next