dbdiagram-ai

Local-first DBML, dbdiagram.io sync, MCP, and exporter tooling for AI coding agents.

This package lets Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, GitHub Copilot, OpenCode, Qoder, Roo Code, Trae, Kiro, and similar agents create and manage dbdiagram.io database diagrams while keeping DBML as the source of truth.

Status

This is a v1 implementation scaffold with working local DBML workflows, MCP tools, optional cloud sync, and exporters. It intentionally does not embed an LLM provider. Rich natural-language schema design should be done by the calling AI agent using the generated instructions and MCP tools.

Install

After the package is published to npm, install it globally:

npm install -g @daveng/dbdiagram-ai

Then use the CLI and MCP server from anywhere:

dbdiagram-ai --help
dbdiagram-ai-mcp

On Windows PowerShell, if script execution policy blocks npm .ps1 shims, use the generated .cmd shims:

dbdiagram-ai.cmd --help
dbdiagram-ai-mcp.cmd

You can also run without global install:

npx @daveng/dbdiagram-ai --help

Install From Source

npm install
npm run build
npm test

Local binaries after build:

node dist/cli.js --help
node dist/mcp-server.js

Package bins:

dbdiagram-ai
dbdiagram-ai-mcp
dbdiagram-ai-install
dbdiagram-ai-init
dbdiagram-ai-create
dbdiagram-ai-update
dbdiagram-ai-validate
dbdiagram-ai-format
dbdiagram-ai-from-sql
dbdiagram-ai-pull
dbdiagram-ai-push
dbdiagram-ai-sync
dbdiagram-ai-diagrams-list
dbdiagram-ai-export-sql
dbdiagram-ai-export-prisma
dbdiagram-ai-export-flyway
dbdiagram-ai-export-liquibase

Publish To npm

The package is configured for public npm publishing as @daveng/dbdiagram-ai.

Before publishing:

npm whoami
npm run pack:dry-run

If npm whoami reports that you are not logged in:

npm adduser

Publish manually:

npm run publish:npm

Publishing runs npm run check first through prepublishOnly, so TypeScript build and tests must pass before npm accepts the package.

GitHub Actions publishing is configured in .github/workflows/npm-publish.yml. Add an npm automation token as the repository secret NPM_TOKEN, then publish a GitHub release or run the workflow manually.

Local DBML Workflow

Local mode is the default. It works without dbdiagram.io credentials and is version-control friendly.

dbdiagram-ai create --prompt "Create ecommerce database diagram" --out database.dbml
dbdiagram-ai update database.dbml --prompt "Add payment and shipment tables"
dbdiagram-ai validate database.dbml
dbdiagram-ai format database.dbml
dbdiagram-ai from-sql schema.sql --out database.dbml

Skill-like command aliases are also installed for agents that prefer one command per tool:

dbdiagram-ai-create --prompt "Create ecommerce database diagram" --out database.dbml
dbdiagram-ai-update database.dbml --prompt "Add payment and shipment tables"
dbdiagram-ai-validate database.dbml
dbdiagram-ai-format database.dbml
dbdiagram-ai-from-sql schema.sql --out database.dbml

Safety defaults:

• Existing .dbml files are read before update.
• In-place updates and formatting create backups.
• Writes refuse to overwrite existing output files unless --overwrite or --force is explicit.
• DBML validation runs before writing DBML output.

Agent Initialization

Install the bundled diagram-ai skill for one agent at a time. Run dbdiagram-ai install in an interactive terminal to open the guided installer TUI.

dbdiagram-ai install

For scripts and CI, pass flags to keep the install non-interactive:

dbdiagram-ai install --ai codex
dbdiagram-ai install --ai claude
dbdiagram-ai install --ai gemini
dbdiagram-ai install --ai cursor
dbdiagram-ai install --ai windsurf
dbdiagram-ai install --ai copilot
dbdiagram-ai install --ai opencode
dbdiagram-ai install --ai qoder
dbdiagram-ai install --ai roocode
dbdiagram-ai install --ai trae
dbdiagram-ai install --ai kiro

You can force the TUI explicitly:

dbdiagram-ai install --interactive

init is kept as a backwards-compatible alias:

dbdiagram-ai init --ai codex

Global and custom skill-directory installs:

dbdiagram-ai install --ai codex --global
dbdiagram-ai install --ai claude --global
dbdiagram-ai install --target ~/.codex/skills --force

Generated project paths:

| Agent | Files | | --- | --- | | Claude Code | .claude/skills/diagram-ai, CLAUDE.md, .mcp.json | | Codex CLI | .codex/skills/diagram-ai, .codex/commands/diagram-ai.md, .codex/mcp.json | | Gemini CLI | .gemini/skills/diagram-ai, GEMINI.md, .gemini/settings.json | | Cursor | .cursor/skills/diagram-ai, .cursor/rules/dbdiagram-ai.mdc, .cursor/mcp.json | | Windsurf | .windsurf/skills/diagram-ai, .windsurf/rules/dbdiagram-ai.md, .windsurf/mcp_config.example.json | | GitHub Copilot | .github/prompts/diagram-ai, .github/copilot-instructions.md, .github/mcp.json | | OpenCode | .opencode/skills/diagram-ai, .opencode/rules/dbdiagram-ai.md, opencode.json | | Qoder | .qoder/skills/diagram-ai, AGENTS.md, .mcp.json | | Roo Code | .roo/skills/diagram-ai, .roo/rules/dbdiagram-ai.md, .roo/mcp.json | | Trae | .trae/skills/diagram-ai, .rules, .trae/mcp.json | | Kiro | .kiro/steering/diagram-ai, .kiro/steering/dbdiagram-ai.md, .kiro/settings/mcp.json |

The initializer never creates a root openai.yaml and never creates Codex/OpenAI metadata for non-Codex agents. Codex receives agents/openai.yaml inside its own skill folder only.

See docs/agent-install.md for the installer layout and path rules.

Codex Slash Command

For Codex CLI, dbdiagram-ai install --ai codex installs the skill at .codex/skills/diagram-ai, so the skill name is /diagram-ai. It also writes .codex/commands/diagram-ai.md for Codex CLI sessions that load project command files.

After restarting the Codex CLI session, use:

/diagram-ai create ecommerce database diagram
/diagram-ai update database.dbml add payments and shipments
/diagram-ai export prisma database.dbml

If the slash command is not listed by your AI CLI, use the installed shell aliases such as dbdiagram-ai-create, dbdiagram-ai-update, and dbdiagram-ai-export-prisma.

MCP Usage

Start the MCP server:

dbdiagram-ai-mcp

Or:

dbdiagram-ai mcp

Primary tools:

create_dbdiagram
update_dbdiagram
create_dbml_file
update_dbml_file
read_dbml_file
write_dbml_file
validate_dbml
format_dbml
convert_sql_to_dbml
convert_dbml_to_sql
pull_from_dbdiagram
push_to_dbdiagram
export_dbml_to_sql
export_dbml_to_prisma
export_dbml_to_flyway
export_dbml_to_liquibase
generate_migration_structure

MCP cloud tools require DBDIAGRAM_API_TOKEN. Local tools do not.

dbdiagram.io Cloud Sync

Cloud sync is disabled unless configured.

export DBDIAGRAM_API_TOKEN="..."
export DBDIAGRAM_DIAGRAM_ID="..."

PowerShell:

$env:DBDIAGRAM_API_TOKEN="..."
$env:DBDIAGRAM_DIAGRAM_ID="..."

Commands:

dbdiagram-ai diagrams list
dbdiagram-ai pull --diagram-id <id> --out database.dbml
dbdiagram-ai push database.dbml --diagram-id <id>
dbdiagram-ai sync database.dbml --diagram-id <id>

Equivalent skill-like aliases:

dbdiagram-ai-diagrams-list
dbdiagram-ai-pull --diagram-id <id> --out database.dbml
dbdiagram-ai-push database.dbml --diagram-id <id>
dbdiagram-ai-sync database.dbml --diagram-id <id>

Push behavior:

• Reads the remote diagram first.
• Validates local DBML before update.
• Sends only name, content, and optional detailLevel.
• Does not send layout fields, so dbdiagram.io can preserve positions, sticky notes, and reference paths.
• Never prints the API token.

Exporters

DBML remains canonical. Exporters parse DBML into a normalized SchemaModel, then generate derived artifacts.

dbdiagram-ai export sql database.dbml --out schema.sql --dialect postgres
dbdiagram-ai export prisma database.dbml --out prisma/schema.prisma
dbdiagram-ai export flyway database.dbml --out db/migration --version 1 --name init_schema --dialect postgres
dbdiagram-ai export liquibase database.dbml --out db/changelog/db.changelog-master.yaml --format yaml

Equivalent skill-like aliases:

dbdiagram-ai-export-sql database.dbml --out schema.sql --dialect postgres
dbdiagram-ai-export-prisma database.dbml --out prisma/schema.prisma
dbdiagram-ai-export-flyway database.dbml --out db/migration --version 1 --name init_schema --dialect postgres
dbdiagram-ai-export-liquibase database.dbml --out db/changelog/db.changelog-master.yaml --format yaml

Export targets:

| Target | Output | Notes | | --- | --- | --- | | Raw SQL | schema.sql | Supports postgres, mysql, sqlite, sqlserver, and generic modes | | Prisma | prisma/schema.prisma | Emits generator, datasource, models, enums, maps, and relations | | Flyway | db/migration/V1__init_schema.sql | Reuses SQL exporter and refuses overwrite unless --force | | Liquibase | db/changelog/db.changelog-master.yaml | YAML supported first; XML/JSON/SQL are reserved for future work |

DBML Guidance For Agents

• Use Project at the top of new files.
• Include tables, primary keys, foreign keys, indexes, enums, and notes when useful.
• Prefer short-form relationships: Ref: orders.user_id > users.id.
• Use TableGroup for medium or large schemas.
• Use DiagramView for focused views in large schemas.
• Use TablePartial only when repeated fields appear across many tables.
• Preserve existing DBML content unless the user asks for removal.

Development

npm run build
npm test
npm run check

Test coverage includes:

• DBML parser, formatter, validator, starter generation, and SQL conversion
• Local no-overwrite and backup behavior
• SQL, Flyway, Liquibase YAML, and Prisma exporters
• Agent initialization isolation
• dbdiagram.io API token header and token redaction

License

MIT. See LICENSE.md.

References

• dbdiagram.io Public API docs: https://docs.dbdiagram.io/api/v1/#tag/diagrams
• DBML syntax docs: https://dbml.dbdiagram.io/docs/
• Claude Code memory and MCP docs: https://docs.anthropic.com/en/docs/claude-code/memory and https://docs.anthropic.com/en/docs/claude-code/mcp
• Gemini CLI context and MCP docs: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md and https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
• Cursor rules and MCP docs: https://docs.cursor.com/en/context and https://docs.cursor.com/advanced/model-context-protocol
• GitHub Copilot instructions and MCP docs: https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-repository-custom-instructions-for-github-copilot and https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp
• Kiro steering and MCP docs: https://kiro.dev/docs/steering/ and https://kiro.dev/docs/mcp/configuration/
• Qoder CLI docs: https://docs.qoder.com/cli/using-cli