{"_id":"@daveng/dbdiagram-ai","name":"@daveng/dbdiagram-ai","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@daveng/dbdiagram-ai","version":"0.1.0","description":"Local-first DBML, dbdiagram.io sync, MCP, and exporter tooling for AI coding agents.","type":"module","license":"MIT","author":"","repository":{"type":"git","url":"git+https://github.com/duynd0909/db-diagram-io-plugin.git"},"bugs":{"url":"https://github.com/duynd0909/db-diagram-io-plugin/issues"},"homepage":"https://github.com/duynd0909/db-diagram-io-plugin#readme","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"dbdiagram-ai":"dist/cli.js","dbdiagram-ai-mcp":"dist/mcp-server.js","dbdiagram-ai-install":"dist/bin/install.js","dbdiagram-ai-init":"dist/bin/init.js","dbdiagram-ai-create":"dist/bin/create.js","dbdiagram-ai-update":"dist/bin/update.js","dbdiagram-ai-validate":"dist/bin/validate.js","dbdiagram-ai-format":"dist/bin/format.js","dbdiagram-ai-from-sql":"dist/bin/from-sql.js","dbdiagram-ai-pull":"dist/bin/pull.js","dbdiagram-ai-push":"dist/bin/push.js","dbdiagram-ai-sync":"dist/bin/sync.js","dbdiagram-ai-diagrams-list":"dist/bin/diagrams-list.js","dbdiagram-ai-export-sql":"dist/bin/export-sql.js","dbdiagram-ai-export-prisma":"dist/bin/export-prisma.js","dbdiagram-ai-export-flyway":"dist/bin/export-flyway.js","dbdiagram-ai-export-liquibase":"dist/bin/export-liquibase.js"},"keywords":["dbdiagram","dbml","mcp","ai-agent","database","schema","prisma","flyway","liquibase"],"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","check":"npm run build && npm test","pack:dry-run":"npm run check && npm pack --dry-run","publish:npm":"npm publish --access public","prepublishOnly":"npm run check"},"dependencies":{"@inkjs/ui":"^2.0.0","@modelcontextprotocol/sdk":"^1.20.2","commander":"^14.0.2","ink":"^7.0.3","react":"^19.2.6","zod":"^4.1.12"},"devDependencies":{"@types/node":"^24.10.1","@types/react":"^19.2.14","typescript":"^5.9.3","vitest":"^4.0.8"},"engines":{"node":">=20"},"_id":"@daveng/dbdiagram-ai@0.1.0","gitHead":"8862f779b82a59e8146cf74a2d5b0e85725ad417","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-JuyIkKlAhDLh4F56UELDdVMyzIvYxqr70+a3NpZcerjtpipd20Ri8/+5uT42b66FFLGZYEpWHMG91tKGCb8PFw==","shasum":"a929867f44638a8faaaf6ec6456f1f553b974ab5","tarball":"https://registry.npmjs.org/@daveng/dbdiagram-ai/-/dbdiagram-ai-0.1.0.tgz","fileCount":149,"unpackedSize":375600,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@daveng%2fdbdiagram-ai@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC+/UpMI5di5+sYeA1T6luSBzFG8cMCk7pTs3pAP3iEtwIgP9iHCN0aBdX72pMjvJsie7gIUkjm3qc/Qc3lUkaXSvo="}]},"_npmUser":{"name":"davengn","email":"duynd0909@gmail.com"},"directories":{},"maintainers":[{"name":"davengn","email":"duynd0909@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dbdiagram-ai_0.1.0_1778836407076_0.0496398335117314"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T09:13:26.961Z","0.1.0":"2026-05-15T09:13:27.216Z","modified":"2026-05-15T09:13:27.634Z"},"maintainers":[{"name":"davengn","email":"duynd0909@gmail.com"}],"description":"Local-first DBML, dbdiagram.io sync, MCP, and exporter tooling for AI coding agents.","homepage":"https://github.com/duynd0909/db-diagram-io-plugin#readme","keywords":["dbdiagram","dbml","mcp","ai-agent","database","schema","prisma","flyway","liquibase"],"repository":{"type":"git","url":"git+https://github.com/duynd0909/db-diagram-io-plugin.git"},"bugs":{"url":"https://github.com/duynd0909/db-diagram-io-plugin/issues"},"license":"MIT","readme":"# dbdiagram-ai\n\nLocal-first DBML, dbdiagram.io sync, MCP, and exporter tooling for AI coding agents.\n\nThis 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.\n\n## Status\n\nThis 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.\n\n## Install\n\nAfter the package is published to npm, install it globally:\n\n```bash\nnpm install -g @daveng/dbdiagram-ai\n```\n\nThen use the CLI and MCP server from anywhere:\n\n```bash\ndbdiagram-ai --help\ndbdiagram-ai-mcp\n```\n\nOn Windows PowerShell, if script execution policy blocks npm `.ps1` shims, use the generated `.cmd` shims:\n\n```powershell\ndbdiagram-ai.cmd --help\ndbdiagram-ai-mcp.cmd\n```\n\nYou can also run without global install:\n\n```bash\nnpx @daveng/dbdiagram-ai --help\n```\n\n## Install From Source\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nLocal binaries after build:\n\n```bash\nnode dist/cli.js --help\nnode dist/mcp-server.js\n```\n\nPackage bins:\n\n```txt\ndbdiagram-ai\ndbdiagram-ai-mcp\ndbdiagram-ai-install\ndbdiagram-ai-init\ndbdiagram-ai-create\ndbdiagram-ai-update\ndbdiagram-ai-validate\ndbdiagram-ai-format\ndbdiagram-ai-from-sql\ndbdiagram-ai-pull\ndbdiagram-ai-push\ndbdiagram-ai-sync\ndbdiagram-ai-diagrams-list\ndbdiagram-ai-export-sql\ndbdiagram-ai-export-prisma\ndbdiagram-ai-export-flyway\ndbdiagram-ai-export-liquibase\n```\n\n## Publish To npm\n\nThe package is configured for public npm publishing as `@daveng/dbdiagram-ai`.\n\nBefore publishing:\n\n```bash\nnpm whoami\nnpm run pack:dry-run\n```\n\nIf `npm whoami` reports that you are not logged in:\n\n```bash\nnpm adduser\n```\n\nPublish manually:\n\n```bash\nnpm run publish:npm\n```\n\nPublishing runs `npm run check` first through `prepublishOnly`, so TypeScript build and tests must pass before npm accepts the package.\n\nGitHub 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.\n\n## Local DBML Workflow\n\nLocal mode is the default. It works without dbdiagram.io credentials and is version-control friendly.\n\n```bash\ndbdiagram-ai create --prompt \"Create ecommerce database diagram\" --out database.dbml\ndbdiagram-ai update database.dbml --prompt \"Add payment and shipment tables\"\ndbdiagram-ai validate database.dbml\ndbdiagram-ai format database.dbml\ndbdiagram-ai from-sql schema.sql --out database.dbml\n```\n\nSkill-like command aliases are also installed for agents that prefer one command per tool:\n\n```bash\ndbdiagram-ai-create --prompt \"Create ecommerce database diagram\" --out database.dbml\ndbdiagram-ai-update database.dbml --prompt \"Add payment and shipment tables\"\ndbdiagram-ai-validate database.dbml\ndbdiagram-ai-format database.dbml\ndbdiagram-ai-from-sql schema.sql --out database.dbml\n```\n\nSafety defaults:\n\n- Existing `.dbml` files are read before update.\n- In-place updates and formatting create backups.\n- Writes refuse to overwrite existing output files unless `--overwrite` or `--force` is explicit.\n- DBML validation runs before writing DBML output.\n\n## Agent Initialization\n\nInstall 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.\n\n```bash\ndbdiagram-ai install\n```\n\nFor scripts and CI, pass flags to keep the install non-interactive:\n\n```bash\ndbdiagram-ai install --ai codex\ndbdiagram-ai install --ai claude\ndbdiagram-ai install --ai gemini\ndbdiagram-ai install --ai cursor\ndbdiagram-ai install --ai windsurf\ndbdiagram-ai install --ai copilot\ndbdiagram-ai install --ai opencode\ndbdiagram-ai install --ai qoder\ndbdiagram-ai install --ai roocode\ndbdiagram-ai install --ai trae\ndbdiagram-ai install --ai kiro\n```\n\nYou can force the TUI explicitly:\n\n```bash\ndbdiagram-ai install --interactive\n```\n\n`init` is kept as a backwards-compatible alias:\n\n```bash\ndbdiagram-ai init --ai codex\n```\n\nGlobal and custom skill-directory installs:\n\n```bash\ndbdiagram-ai install --ai codex --global\ndbdiagram-ai install --ai claude --global\ndbdiagram-ai install --target ~/.codex/skills --force\n```\n\nGenerated project paths:\n\n| Agent | Files |\n| --- | --- |\n| Claude Code | `.claude/skills/diagram-ai`, `CLAUDE.md`, `.mcp.json` |\n| Codex CLI | `.codex/skills/diagram-ai`, `.codex/commands/diagram-ai.md`, `.codex/mcp.json` |\n| Gemini CLI | `.gemini/skills/diagram-ai`, `GEMINI.md`, `.gemini/settings.json` |\n| Cursor | `.cursor/skills/diagram-ai`, `.cursor/rules/dbdiagram-ai.mdc`, `.cursor/mcp.json` |\n| Windsurf | `.windsurf/skills/diagram-ai`, `.windsurf/rules/dbdiagram-ai.md`, `.windsurf/mcp_config.example.json` |\n| GitHub Copilot | `.github/prompts/diagram-ai`, `.github/copilot-instructions.md`, `.github/mcp.json` |\n| OpenCode | `.opencode/skills/diagram-ai`, `.opencode/rules/dbdiagram-ai.md`, `opencode.json` |\n| Qoder | `.qoder/skills/diagram-ai`, `AGENTS.md`, `.mcp.json` |\n| Roo Code | `.roo/skills/diagram-ai`, `.roo/rules/dbdiagram-ai.md`, `.roo/mcp.json` |\n| Trae | `.trae/skills/diagram-ai`, `.rules`, `.trae/mcp.json` |\n| Kiro | `.kiro/steering/diagram-ai`, `.kiro/steering/dbdiagram-ai.md`, `.kiro/settings/mcp.json` |\n\nThe 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.\n\nSee [docs/agent-install.md](docs/agent-install.md) for the installer layout and path rules.\n\n### Codex Slash Command\n\nFor 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.\n\nAfter restarting the Codex CLI session, use:\n\n```txt\n/diagram-ai create ecommerce database diagram\n/diagram-ai update database.dbml add payments and shipments\n/diagram-ai export prisma database.dbml\n```\n\nIf 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`.\n\n## MCP Usage\n\nStart the MCP server:\n\n```bash\ndbdiagram-ai-mcp\n```\n\nOr:\n\n```bash\ndbdiagram-ai mcp\n```\n\nPrimary tools:\n\n```txt\ncreate_dbdiagram\nupdate_dbdiagram\ncreate_dbml_file\nupdate_dbml_file\nread_dbml_file\nwrite_dbml_file\nvalidate_dbml\nformat_dbml\nconvert_sql_to_dbml\nconvert_dbml_to_sql\npull_from_dbdiagram\npush_to_dbdiagram\nexport_dbml_to_sql\nexport_dbml_to_prisma\nexport_dbml_to_flyway\nexport_dbml_to_liquibase\ngenerate_migration_structure\n```\n\nMCP cloud tools require `DBDIAGRAM_API_TOKEN`. Local tools do not.\n\n## dbdiagram.io Cloud Sync\n\nCloud sync is disabled unless configured.\n\n```bash\nexport DBDIAGRAM_API_TOKEN=\"...\"\nexport DBDIAGRAM_DIAGRAM_ID=\"...\"\n```\n\nPowerShell:\n\n```powershell\n$env:DBDIAGRAM_API_TOKEN=\"...\"\n$env:DBDIAGRAM_DIAGRAM_ID=\"...\"\n```\n\nCommands:\n\n```bash\ndbdiagram-ai diagrams list\ndbdiagram-ai pull --diagram-id <id> --out database.dbml\ndbdiagram-ai push database.dbml --diagram-id <id>\ndbdiagram-ai sync database.dbml --diagram-id <id>\n```\n\nEquivalent skill-like aliases:\n\n```bash\ndbdiagram-ai-diagrams-list\ndbdiagram-ai-pull --diagram-id <id> --out database.dbml\ndbdiagram-ai-push database.dbml --diagram-id <id>\ndbdiagram-ai-sync database.dbml --diagram-id <id>\n```\n\nPush behavior:\n\n- Reads the remote diagram first.\n- Validates local DBML before update.\n- Sends only `name`, `content`, and optional `detailLevel`.\n- Does not send layout fields, so dbdiagram.io can preserve positions, sticky notes, and reference paths.\n- Never prints the API token.\n\n## Exporters\n\nDBML remains canonical. Exporters parse DBML into a normalized `SchemaModel`, then generate derived artifacts.\n\n```bash\ndbdiagram-ai export sql database.dbml --out schema.sql --dialect postgres\ndbdiagram-ai export prisma database.dbml --out prisma/schema.prisma\ndbdiagram-ai export flyway database.dbml --out db/migration --version 1 --name init_schema --dialect postgres\ndbdiagram-ai export liquibase database.dbml --out db/changelog/db.changelog-master.yaml --format yaml\n```\n\nEquivalent skill-like aliases:\n\n```bash\ndbdiagram-ai-export-sql database.dbml --out schema.sql --dialect postgres\ndbdiagram-ai-export-prisma database.dbml --out prisma/schema.prisma\ndbdiagram-ai-export-flyway database.dbml --out db/migration --version 1 --name init_schema --dialect postgres\ndbdiagram-ai-export-liquibase database.dbml --out db/changelog/db.changelog-master.yaml --format yaml\n```\n\nExport targets:\n\n| Target | Output | Notes |\n| --- | --- | --- |\n| Raw SQL | `schema.sql` | Supports `postgres`, `mysql`, `sqlite`, `sqlserver`, and `generic` modes |\n| Prisma | `prisma/schema.prisma` | Emits generator, datasource, models, enums, maps, and relations |\n| Flyway | `db/migration/V1__init_schema.sql` | Reuses SQL exporter and refuses overwrite unless `--force` |\n| Liquibase | `db/changelog/db.changelog-master.yaml` | YAML supported first; XML/JSON/SQL are reserved for future work |\n\n## DBML Guidance For Agents\n\n- Use `Project` at the top of new files.\n- Include tables, primary keys, foreign keys, indexes, enums, and notes when useful.\n- Prefer short-form relationships: `Ref: orders.user_id > users.id`.\n- Use `TableGroup` for medium or large schemas.\n- Use `DiagramView` for focused views in large schemas.\n- Use `TablePartial` only when repeated fields appear across many tables.\n- Preserve existing DBML content unless the user asks for removal.\n\n## Development\n\n```bash\nnpm run build\nnpm test\nnpm run check\n```\n\nTest coverage includes:\n\n- DBML parser, formatter, validator, starter generation, and SQL conversion\n- Local no-overwrite and backup behavior\n- SQL, Flyway, Liquibase YAML, and Prisma exporters\n- Agent initialization isolation\n- dbdiagram.io API token header and token redaction\n\n## License\n\nMIT. See [LICENSE.md](LICENSE.md).\n\n## References\n\n- dbdiagram.io Public API docs: https://docs.dbdiagram.io/api/v1/#tag/diagrams\n- DBML syntax docs: https://dbml.dbdiagram.io/docs/\n- 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\n- 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\n- Cursor rules and MCP docs: https://docs.cursor.com/en/context and https://docs.cursor.com/advanced/model-context-protocol\n- 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\n- Kiro steering and MCP docs: https://kiro.dev/docs/steering/ and https://kiro.dev/docs/mcp/configuration/\n- Qoder CLI docs: https://docs.qoder.com/cli/using-cli\n","readmeFilename":"README.md","_rev":"1-179a82bbc197f0b8fa5a9150efdafb3c"}