What this example shows
A classic blog schema rendered as a Crow’s Foot ER diagram with PK / FK badges, column-row anchored edges, and auto-inferred cardinality glyphs. The canonical scene is the same shape an agent would produce after parsing migration files for a real codebase - the agent applies each migration as typed operations instead of redrawing the diagram from scratch.
When to use it
Reach for this pattern whenever your team’s schema lives in migration files (Prisma, Drizzle, Alembic, Rails, SQLAlchemy, raw SQL). The diagram becomes a derived artifact: agents read migrations, apply typed operations to the persisted scene, and produce a visual diff for each migration. New engineers see the schema as a picture; reviewers see exactly what each migration adds, removes, or changes.
What the agent does
The agent reads the migration files in your repo, parses them into table / column / key / foreign-key changes, fetches the current persisted scene, and applies createNode, updateNode, createEdge, deleteElement operations to bring the scene up to date. It validates structurally (no orphan FKs, no duplicate IDs), renders the updated diagram, and diffs the previous revision against the new one.
The flow is incremental. The persisted scene keeps stable IDs across migrations, so the revision diff names exactly the entities and columns a migration touched. Engineers see “what changed in this migration” rather than “here’s the entire schema again.”
What the output includes
- A compartmented ER diagram with one entity per table, columns shown as labeled rows, PK / FK badges per column, and Crow’s Foot glyphs at every relationship endpoint.
- Auto-inferred cardinality from
pk/fk/unique/nullablecolumn metadata - agents don’t need to hand-set cardinality on most edges. - FK edges that anchor at the named column row (the dbdiagram.io / DBeaver convention) so the relationship is visible at a glance.
- A revision diff showing exactly which entities, columns, or relationships changed since the previous revision.
Rendered diagram
Revision 2 as Zindex saved it, from the edit to revision 1 that Revision diff shows. That edit moved no placed node Revision diff doesn't list, but the Playground draws the scene below from scratch, so its nodes can land elsewhere. Open the scene there to swap themes (clean / dark / blueprint / sketch).
Scene JSON
Raw
The DSP scene of revision 2, without the node positions Zindex saved with it. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview, to draw it from scratch.
{
"schemaVersion": "0.1",
"diagramFamily": "entityRelationship",
"scene": {
"id": "blog-er",
"title": "Blog Entity Relationship",
"brief": "The blog's tables and their keys, built from the database migrations.\nOne entity per table, its columns in migration order with PK and FK marks; a foreign key is a relationship, and a many-to-many join table (such as _PostToTag) is drawn as one edge between its two tables. Update it from each new migration, and name the migration in the edit's message.",
"units": "px",
"canvas": {
"width": 1100,
"height": 600
}
},
"layoutStrategy": {
"direction": "LR",
"nodeSpacing": 60,
"rankSpacing": 140
},
"elements": [
{
"id": "user",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Users",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "username",
"type": "varchar"
},
{
"name": "email",
"type": "varchar"
},
{
"name": "created_at",
"type": "timestamp"
}
]
}
},
{
"id": "post",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Posts",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "author_id",
"type": "int",
"fk": true
},
{
"name": "title",
"type": "varchar"
},
{
"name": "body",
"type": "text"
}
]
}
},
{
"id": "comment",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Comments",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "post_id",
"type": "int",
"fk": true
},
{
"name": "user_id",
"type": "int",
"fk": true
},
{
"name": "body",
"type": "text"
}
]
}
},
{
"id": "tag",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Tags",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "name",
"type": "varchar"
}
]
}
},
{
"id": "e-writes",
"kind": "edge",
"edgeType": "er.relationship",
"from": {
"elementId": "post",
"column": "author_id"
},
"to": {
"elementId": "user"
},
"router": "orthogonal"
},
{
"id": "e-comments",
"kind": "edge",
"edgeType": "er.relationship",
"from": {
"elementId": "comment",
"column": "user_id"
},
"to": {
"elementId": "user"
},
"router": "orthogonal"
},
{
"id": "e-has-comments",
"kind": "edge",
"edgeType": "er.relationship",
"from": {
"elementId": "comment",
"column": "post_id"
},
"to": {
"elementId": "post"
},
"router": "orthogonal"
},
{
"id": "e-tagged",
"kind": "edge",
"edgeType": "er.relationship",
"from": {
"elementId": "post"
},
"to": {
"elementId": "tag",
"cardinality": "many"
},
"router": "orthogonal",
"label": "tagged"
}
]
} Agent workflow
Update a saved ER diagram from database migration files. Parse the new or changed migrations, derive entity / column / FK changes, change the Zindex diagram with typed operations, render it, and share the revision compare with reviewers.
Inputs
- List of new or changed migration files (Prisma / Drizzle / Alembic / Rails)
- The diagram's Zindex key or ID (the diagram is created on the first run)
- A Zindex API key, or an MCP client signed in to Zindex
Outputs
- A new revision of the diagram; earlier revisions are kept unchanged
- Rendered SVG of the new schema
- A compare (JSON) listing which entities and relationships were added, changed or removed
- A summary of schema changes with the rendered diagram, ready to share with reviewers
- 01
Create or read the diagram
On the first run, parse every migration and save the result with
diagram_create: a scene with diagramFamily entityRelationship and an LR hierarchical layoutStrategy, akeysuch asblog-er, and abriefwhose first line says what the diagram shows. Zindex mints the ID; the key is how later runs find the diagram, and the brief's first line is what a search shows. On later runs, read it withdiagram_getinstead. - 02
Parse changed migration files
Read the migration files added or modified since the last revision. Extract the table-level changes: new tables, dropped tables, added columns, renamed columns, dropped columns, new foreign keys, and new indexes. Most ORMs leave a structured trail (Prisma's create/alter blocks, Alembic op.create_table / op.add_column, Rails CreateTable / AddColumn) - parse those rather than free-text SQL.
- 03
Diff the parsed schema against the diagram
Read the diagram with
view: "dsp"to get the scene JSON, since the columns live in each entity'sextensions.columnsand the outline doesn't show them. For each entity, check whether it still exists in the parsed schema. For each column inside each entity, check whether it was added, removed, renamed, or had its type changed. Emit a list of intended ops (createNode / updateNode / deleteElement / createEdge / updateEdge) - do not yet apply them. - 04
Save the changes as one edit
Send the diff as one
diagram_editwithbaseRevisionset to the revision you read and amessagenaming the migration. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Always reuse stable ids (user,post, etc.) so renames produce a true updateNode rather than a delete+create. The element id is the schema's stable handle; do not regenerate it on every run. - 05
Fix what the warnings report
The edit's
warningslist the ER rules the new revision breaks and what drawing it noticed, each with acode, theelementwhen there is one, and a one-linefix. The edit above returns none:e-taggedsetsmanyattag, and itspostend anchors at the primary key, which is inferred asone.FAMILY_ER_MISSING_CARDINALITYnames an end with neither: set its cardinality withupdateEdgein a follow-up edit.EDGE_COLUMN_NOT_FOUNDmeans a relationship names a column its entity doesn't declare, usually a typo or a stale migration. - 06
Render the new revision
Get SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address,
zindex.ai/d/<id>@<revision>, and date, so the image is traceable to its revision without a metadata sidecar file. - 07
Compare with the previous revision
Ask for what changed between the prior revision and the new one. The response lists the element IDs added, changed and removed, and the scene-level fields that changed, so the agent doesn't have to re-derive the change on its own.
- 08
Share the rendered diagram + compare
Share the rendered SVG (or its link, which works for 7 days) and a human-readable summary of the compare with reviewers, for example in the code review.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_createCreate or read the diagram - 02
diagram_getDiff the parsed schema against the diagram - 03
diagram_editSave the changes as one edit - 04
diagram_renderRender the new revision - 05
diagram_historyCompare with the previous revision
Unique tools used: diagram_create, diagram_get, diagram_edit, diagram_render, diagram_history.
Copyable agent prompt
Drop this verbatim into a system prompt for an MCP-connected agent.
The Zindex MCP server at https://api.zindex.ai/mcp exposes
the tools the prompt references (connect a client),
and so does the npm package @zindexai/mcp, which forwards
to it.
You maintain the entity-relationship diagram of the application's database schema that the team keeps in Zindex. When the schema changes, you read the new migrations and change the diagram with typed edits, each with a message naming the migration, without ever drawing the diagram by hand. Every revision is kept, so anyone can open the schema diagram as it was on any date, or compare two dates.
The diagram's Zindex ID is `${SCENE_ID}`. The diagram already exists - do not create a new one. Your job is to compute the smallest valid set of typed operations that move the diagram from its current revision to one that matches the schema after the new migrations.
Steps for each update:
1. Read the migration files added since the diagram's last revision - Prisma `schema.prisma` and `migrations/**`, Drizzle `drizzle/meta/**`, Alembic `alembic/versions/**`, or Rails `db/migrate/**`. Use the migrations rather than free-text SQL: ORMs leave a structured trail you can parse reliably (Prisma's create/alter blocks, Alembic op.create_table / op.add_column, Rails CreateTable / AddColumn). Extract the table-level shape: tables, columns with types, primary keys, foreign keys.
2. Call `diagram_get({ id: "${SCENE_ID}", view: "dsp" })` to read the current revision and the scene JSON; the columns live in each entity's `extensions.columns`, which the default outline doesn't show. Diff what you parsed against the diagram: which entities are new, which were dropped, which had columns added / removed / renamed / retyped, which FK relationships are new.
3. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch of typed operations, `baseRevision` set to the revision you read. The edit is all or nothing: errors return `VALIDATION_FAILED` and nothing is saved. Always reuse stable ids (`user`, `post`, `comment`, …) - element ids are the schema's stable handle; renames must produce `updateNode`, not `deleteElement` + `createNode`, or you will lose the FK edges that anchor on those ids. Pass a meaningful `message` like "add Comments table from migration 20260415_add_comments" so the revision history reads like a git log. If the call returns `REVISION_CONFLICT`, the diagram changed after you read it: the error lists what changed, so re-plan against the new revision.
4. Read the edit's `warnings`. They list the ER rules the new revision breaks and what drawing it noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. Resolve them with a follow-up edit. `FAMILY_ER_MISSING_CARDINALITY` means a relationship end has no cardinality and no `pk` or `fk` column to infer it from: set it with `updateEdge`, or anchor the end at its column. `EDGE_COLUMN_NOT_FOUND` means a relationship references a column its entity doesn't declare, usually a typo or a stale migration. `LABEL_DUPLICATION_DETECTED` means two edges at one entity share a label: rename one.
5. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days, not the image itself. The image prints its address, `zindex.ai/d/<id>@<revision>`, and date, so it is traceable to its revision.
6. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: PREV_REVISION } })` to get what changed: the element IDs added, changed and removed since the previous revision (`to` defaults to the latest). Share it with the people reviewing the schema change so they can read the change at a glance without re-deriving it from the migration.
7. Share one message with the rendered SVG (or its link) and the change summary where the team reviews the change, such as the code review. If the migrations change again before they land, update that message rather than adding another, so reviewers always see the latest snapshot.
Hard rules: never hand-edit the rendered SVG; always edit the diagram with `diagram_edit` and render again. Never recreate the diagram from scratch; always patch with stable ids. Never leave a warning you can fix; an unresolved warning risks shipping a picture that does not match the schema. If an edit fails with an error you can't resolve, report the `code`, `element` and `fix` to the person who asked and ask them to resolve it.
HTTP API recipe
For agents/devs not using MCP. Send
Authorization: Bearer $ZINDEX_API_KEY on every call
except POST /v1/diagrams/validate and
POST /v1/diagrams/preview, which need no key. In the
paths, ${SCENE_ID} is the diagram's ID, or the
key you gave it in diagram_create. Full
reference: REST API, OpenAPI spec.
- 01
POST/v1/diagramsOn the first run, parse every migration and save the result with
diagram_create: a scene with diagramFamily entityRelationship and an LR hierarchical layoutStrategy, akeysuch asblog-er, and abriefwhose first line says what the diagram shows. Zindex mints the ID; the key is how later runs find the diagram, and the brief's first line is what a search shows. On later runs, read it withdiagram_getinstead.Example request body
{ "key": "blog-er", "message": "Schema from the migrations so far", "scene": { "schemaVersion": "0.1", "diagramFamily": "entityRelationship", "scene": { "title": "Blog Entity Relationship", "brief": "The blog's tables and their keys, built from the database migrations.", "canvas": { "width": 1100, "height": 600 } }, "layoutStrategy": { "direction": "LR", "nodeSpacing": 60, "rankSpacing": 140 }, "elements": [ "..." ] } }Example response
{ "id": "dgm_5n5bArfPPqPW", "key": "blog-er", "revision": 1, "hash": "sha256:97b7591054f1cc6fb4f1f0c707545047eab7abc2786e2bb2bf88f6bfc377694f", "chain": "sha256:acfbcc2a75f7ca39af864bf6d829334ec9762b3b2fc07430367cca9f202a0721", "warnings": [], "created": true } - 02
GET/v1/diagrams/${SCENE_ID}?view=dspRead the diagram with
view: "dsp"to get the scene JSON, since the columns live in each entity'sextensions.columnsand the outline doesn't show them. For each entity, check whether it still exists in the parsed schema. For each column inside each entity, check whether it was added, removed, renamed, or had its type changed. Emit a list of intended ops (createNode / updateNode / deleteElement / createEdge / updateEdge) - do not yet apply them.Example response
{ "id": "dgm_5n5bArfPPqPW", "key": "blog-er", "revision": 1, "hash": "sha256:97b7591054f1cc6fb4f1f0c707545047eab7abc2786e2bb2bf88f6bfc377694f", "chain": "sha256:acfbcc2a75f7ca39af864bf6d829334ec9762b3b2fc07430367cca9f202a0721", "createdAt": "2026-10-31T11:35:04.430Z", "visibility": "private", "scene": { "schemaVersion": "0.1", "diagramFamily": "entityRelationship", "scene": { "id": "dgm_5n5bArfPPqPW", "title": "Blog Entity Relationship", "...": "..." }, "elements": [ { "id": "user", "kind": "node", "nodeType": "er.entity", "label": "Users", "extensions": { "columns": [ { "name": "id", "type": "int", "pk": true }, "..." ] }, "...": "..." }, "..." ], "...": "..." } } - 03
POST/v1/diagrams/${SCENE_ID}/revisionsSend the diff as one
diagram_editwithbaseRevisionset to the revision you read and amessagenaming the migration. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Always reuse stable ids (user,post, etc.) so renames produce a true updateNode rather than a delete+create. The element id is the schema's stable handle; do not regenerate it on every run.Example request body
{ "baseRevision": 1, "message": "add Tags table from migration 20260527000000_add_tags", "ops": [ { "op": "createNode", "id": "tag", "nodeType": "er.entity", "shape": "rect", "label": "Tags", "extensions": { "columns": [ { "name": "id", "type": "int", "pk": true }, { "name": "name", "type": "varchar" } ] } }, { "op": "createEdge", "id": "e-tagged", "edgeType": "er.relationship", "from": { "elementId": "post" }, "to": { "elementId": "tag", "cardinality": "many" }, "router": "orthogonal", "label": "tagged" } ] }Example response
{ "id": "dgm_5n5bArfPPqPW", "revision": 2, "hash": "sha256:b973f7dff1f51df7be73891eae3f2e9fe926045ae8f95aaec5debbda38d0b138", "chain": "sha256:48d79bd803d6f463bd39887c94d26316572e13f1c6e86fd0d8e0055baf2f86d7", "warnings": [], "changed": { "added": [ "tag", "e-tagged" ], "updated": [], "removed": [] } } - 04
GET/v1/diagrams/${SCENE_ID}/renderGet SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address,
zindex.ai/d/<id>@<revision>, and date, so the image is traceable to its revision without a metadata sidecar file.Example response
{ "id": "dgm_5n5bArfPPqPW", "title": "Blog Entity Relationship", "revision": 2, "latest": 2, "savedAt": "2026-10-31T11:35:04.463Z", "hash": "sha256:b973f7dff1f51df7be73891eae3f2e9fe926045ae8f95aaec5debbda38d0b138", "chain": "sha256:48d79bd803d6f463bd39887c94d26316572e13f1c6e86fd0d8e0055baf2f86d7", "engine": "8.10.4+build.2565", "svg": "https://api.zindex.ai/v1/images/dgm_5n5bArfPPqPW@2.svg?e=1794051304&s=...", "png": "https://api.zindex.ai/v1/images/dgm_5n5bArfPPqPW@2.png?e=1794051304&s=...", "expires": "2026-11-07T11:35:04.000Z", "width": 1100, "height": 365 } - 05
GET/v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}&to=${NEW_REVISION}Ask for what changed between the prior revision and the new one. The response lists the element IDs added, changed and removed, and the scene-level fields that changed, so the agent doesn't have to re-derive the change on its own.
Example response
{ "id": "dgm_5n5bArfPPqPW", "from": 1, "to": 2, "added": [ "tag", "e-tagged" ], "changed": [], "removed": [], "scene": [], "authors": [ { "by": null, "client": "curl/8.7.1" } ] }
Operations
Raw The typed operations that build revision 2's scene from empty in one edit, not through the edit the diagram above was saved by. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "blog-er",
"baseRevision": 1,
"message": "Initial blog ER schema: users, posts, comments, tags",
"ops": [
{
"op": "createNode",
"id": "user",
"nodeType": "er.entity",
"shape": "rect",
"label": "Users",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "username",
"type": "varchar"
},
{
"name": "email",
"type": "varchar"
},
{
"name": "created_at",
"type": "timestamp"
}
]
}
},
{
"op": "createNode",
"id": "post",
"nodeType": "er.entity",
"shape": "rect",
"label": "Posts",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "author_id",
"type": "int",
"fk": true
},
{
"name": "title",
"type": "varchar"
},
{
"name": "body",
"type": "text"
}
]
}
},
{
"op": "createNode",
"id": "comment",
"nodeType": "er.entity",
"shape": "rect",
"label": "Comments",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "post_id",
"type": "int",
"fk": true
},
{
"name": "user_id",
"type": "int",
"fk": true
},
{
"name": "body",
"type": "text"
}
]
}
},
{
"op": "createNode",
"id": "tag",
"nodeType": "er.entity",
"shape": "rect",
"label": "Tags",
"extensions": {
"columns": [
{
"name": "id",
"type": "int",
"pk": true
},
{
"name": "name",
"type": "varchar"
}
]
}
},
{
"op": "createEdge",
"id": "e-writes",
"edgeType": "er.relationship",
"from": {
"elementId": "post",
"column": "author_id"
},
"to": {
"elementId": "user"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e-comments",
"edgeType": "er.relationship",
"from": {
"elementId": "comment",
"column": "user_id"
},
"to": {
"elementId": "user"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e-has-comments",
"edgeType": "er.relationship",
"from": {
"elementId": "comment",
"column": "post_id"
},
"to": {
"elementId": "post"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e-tagged",
"edgeType": "er.relationship",
"from": {
"elementId": "post"
},
"to": {
"elementId": "tag",
"cardinality": "many"
},
"router": "orthogonal",
"label": "tagged"
}
]
} Validation
Valid
Captured response from POST /v1/diagrams/validate, the
check diagram_validate runs. It checks the scene and
draws it. Every code it can return is in the validation rules.
- 0 errors
- 0 warnings
The scene validates with no errors or warnings.
Each entry has a code, the element it
concerns when there is one, and a one-line fix.
diagram_create and diagram_edit save
nothing when there are errors and return
VALIDATION_FAILED; warnings don't block a save. Both
return the same warnings for the revision they save, so an agent
reads them from the write itself.
Revision diff
Raw
What changed between two revisions of the diagram, as
diagram_history returns it with compare.
Every revision is kept, so any two can be compared, by revision
number or by date.
Scenario
A new migration adds a Tags table and a relationship from Posts to Tags. The agent reads the migration and adds the entity, with its id and name columns, and the labeled relationship in one edit. Revision 2 differs from revision 1 by exactly those two elements, which is what reviewers need to look at.
- Revision 1 → 2
- +2 added
- -0 removed
- ~0 changed
+ Added
tage-tagged
Raw compare response
{
"id": "dgm_q6VpsT4xDsG2",
"from": 1,
"to": 2,
"added": [
"tag",
"e-tagged"
],
"changed": [],
"removed": [],
"scene": [],
"scenario": "A new migration adds a Tags table and a relationship from Posts to Tags. The agent reads the migration and adds the entity, with its id and name columns, and the labeled relationship in one edit. Revision 2 differs from revision 1 by exactly those two elements, which is what reviewers need to look at."
} Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
er-diagram-from-migrations.scene.jsonCanonical DSP scene Open -
er-diagram-from-migrations.ops.jsonTyped-operation envelope that builds the scene Open -
er-diagram-from-migrations.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
er-diagram-from-migrations.diff.jsonSamplediagram_historycompare response Open -
er-diagram-from-migrations.svgRendered diagram: revision 2 as Zindex saved it Open -
er-diagram-from-migrations.before.svgRevision diff's before picture: revision 1 as Zindex saved it Open -
er-diagram-from-migrations.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open