Your Database Diagram Is Outdated. Put a Live One in Your GitHub README.
Let's be honest. How often do you update your database diagram after changing your database?
You add a table, introduce a relationship, rename a column or refactor an existing module. Your application evolves, your database changes, and your documentation slowly falls behind.
The problem isn't creating database diagrams. There are plenty of tools for that.
The problem is keeping them updated.
A common solution is to export a diagram as an image and commit it to your repository. It works, but the moment your schema changes, the image becomes outdated.
And someone eventually has to remember to replace it.
There is a better approach: put your database diagram directly in your GitHub README and let it update automatically.
Why database documentation gets outdated
Most development teams understand the importance of database documentation.
A diagram helps developers:
- Understand how tables relate to each other.
- Explore an unfamiliar codebase.
- Identify dependencies before changing existing structures.
- Onboard new developers.
- Discuss database architecture with the rest of the team.
But maintaining that documentation introduces another task into an already busy development workflow.
Consider a typical Laravel application.
You start with users, roles and permissions. Later, you introduce subscriptions, invoices, payments and notifications.
Your migrations are updated, your application works, and everything gets committed.
But the database diagram?
It still shows the original structure.
Eventually, developers stop trusting it.
Put your database diagram directly in GitHub
With SchemaSketch, you can now embed a live database diagram directly into a GitHub README.
The process is straightforward.
Step 1: Create your database diagram
Go to SchemaSketch and create a diagram using DBML.
DBML is a simple language for describing database structures.
For example:
Table users { id integer [primary key] name varchar email varchar created_at timestamp } Table projects { id integer [primary key] user_id integer name varchar created_at timestamp } Table tasks { id integer [primary key] project_id integer title varchar status varchar } Ref: projects.user_id > users.id Ref: tasks.project_id > projects.id SchemaSketch renders the database structure visually, allowing you to explore tables and their relationships.
You can also export your schema into SQL, Laravel migrations and models, Mermaid or PlantUML.
Step 2: Share your diagram
Once your diagram is ready, open the Share dialog.
Make the diagram publicly accessible and select Copy Markdown.
SchemaSketch generates the Markdown required to embed your diagram.
Step 3: Add it to your README
Open your GitHub repository and edit its README.md file.
Paste the Markdown you copied from SchemaSketch wherever you want the diagram to appear.
Commit your changes.
That's it.
Your database diagram is now part of your repository documentation.
Step 4: Let it update automatically
This is the interesting part.
The embedded diagram is served as an SVG image.
It automatically supports GitHub's light and dark themes, so readers can view it comfortably regardless of their interface settings.
More importantly, when you update your diagram in SchemaSketch, the embedded image updates automatically, usually within approximately five minutes.
You don't need to export another image.
You don't need to replace anything in GitHub.
You don't need another commit just to update the documentation image.
If you make the diagram private or revoke its sharing link, the embedded image is no longer accessible.
What does this look like?
Imagine opening a repository and finding this:
Project Database Architecture
Your actual database diagram, showing users, projects, tasks and all their relationships.
A new developer can understand the database structure without having to open another application or search for an old diagram.
And when the database design changes, the README follows.
No separate image files to maintain.
No manual exports.
No outdated screenshots.
More than just database diagrams
The live README integration is one of several improvements we've recently introduced to SchemaSketch.
There are a few other things worth mentioning.
An open-source DBML renderer
We've released the drawing engine as schemasketch-render, an npm package.
It is MIT licensed, has no dependencies and supports Node.js 18 and above.
You can use it to render DBML into SVG independently.
For example, this makes it possible to generate database diagram images as part of your own development or CI workflows.
Repository and package:
More AI coding agent integrations
SchemaSketch also supports more AI coding environments through its agent plugin.
The plugin provides integrations for:
- Codex
- Cursor
- Devin
- Windsurf
- Gemini CLI
- Antigravity
GitHub Copilot CLI and Kiro can use the same plugin's skill, with an additional MCP server configuration.
Claude Code and Claude Desktop already support a one-command setup.
Through the SchemaSketch MCP server, AI agents can work with database diagrams rather than relying entirely on assumptions when generating application code.
More information: https://schemasketch.dev/mcp#clients
Better support for real-world DBML
We've also improved compatibility with DBML structures commonly found in existing projects.
This includes:
- PostgreSQL-style schemas, such as
billing.invoices. - Relationships across schemas.
- Named foreign key constraints.
- Composite foreign keys.
- Composite primary keys.
- UNIQUE constraints.
- CREATE INDEX statements in SQL exports.
The goal is to make working with existing database designs easier, not just diagrams created from scratch.
Documentation should evolve with your application
A database diagram shouldn't be something you create once, export and eventually forget.
It should be part of your development workflow.
Whether you're maintaining a Laravel application, working with PostgreSQL or building software with AI coding agents, having an accessible and current representation of your database makes a difference.
That's what we're trying to make easier with SchemaSketch.
Try it for free:
Your database changes. Your documentation should keep up.