# Dbml Multi DB Schema

> Create and maintain DBML files for systems that split data across a PrimaryDB and one or more ClientDB instances. Use when adding or updating DBML for multi-database schemas, tenant-specific client databases, cross-database analysis views, logical relationships based on business keys such as ProjectNo, or recommended dbml folder structures.

- Skill: `atman-33/dbml-multi-db-schema` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add atman-33/dbml-multi-db-schema`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atman-33/dbml-multi-db-schema/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: atman-33 (https://skillmd.com/u/atman-33)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atman-33/dbml-multi-db-schema

---


# Dbml Multi Db Schema

## Overview

Use this skill to keep DBML manageable when one system has a central database and many client-specific databases. Separate physical schemas from cross-database logical relationships, and avoid duplicating one DBML file per client unless the schema actually diverges.

## Workflow

1. Identify the requested change.
	 Create a new structure? Update an existing DBML file? Add a cross-database relationship? Add a client-specific variant?
2. Classify the target.
	 Physical PrimaryDB change -> update `primary.dbml`.
	 Shared ClientDB change -> update `client.template.dbml`.
	 Cross-database analysis or lineage change -> update `integration.cross-db.dbml`.
	 Tenant-only divergence -> add or update a file under `client-variants/`.
3. Read [references/management-patterns.md](references/management-patterns.md) before deciding file placement.
4. Read [references/dbml-modeling-rules.md](references/dbml-modeling-rules.md) before adding tables, keys, or logical refs.
5. If the project has no DBML structure yet, scaffold it with `scripts/scaffold_multi_db_dbml.py`.
6. Apply the smallest change that preserves the structure split between physical schemas and logical integration views.
7. Validate naming consistency for shared business keys such as `project_no`, then review the result in the DBML visualizer.

## Default Layout

Prefer this layout unless the repository already uses a stronger convention:

```text
dbml/
	primary.dbml
	client.template.dbml
	integration.cross-db.dbml
	client-variants/
		client-a.dbml
		client-b.dbml
```

Keep `client.template.dbml` as the shared shape for all `ClientDB_n` instances. Create per-client files only for meaningful schema drift.

For this skill's generated starter files, use the dedicated output folder under the skill itself:

```text
.github/skills/dbml-multi-db-schema/generated-dbml/
```

The scaffold script writes there by default unless `--output-dir` is provided explicitly.

## Modeling Rules

- Model physical foreign keys only inside the same physical database.
- Model cross-database business-key links with `Ref:` plus a note that the link is logical, not enforced by the database.
- Keep shared keys named and typed consistently across files. If `ProjectNo` exists in multiple databases, use one canonical DBML field name such as `project_no` everywhere unless the project already has a fixed naming convention.
- Use narrow integration files. Include only the tables and columns needed to explain cross-database analysis paths.
- Do not duplicate every `ClientDB_1`, `ClientDB_2`, `ClientDB_3` schema if they are materially identical.

## Common Requests

Example requests that should trigger this skill:

- "Add a new shared column to PrimaryDB and ClientDB DBML files."
- "Create a cross-db ERD that links client records to primary projects by ProjectNo."
- "Add a tenant-specific DBML variant for one client with extra billing tables."
- "Restructure our DBML files so the central schema and client template are separate."

## Resources

- `scripts/scaffold_multi_db_dbml.py`
	Create starter DBML files for `primary.dbml`, `client.template.dbml`, and `integration.cross-db.dbml`. Save them to `generated-dbml/` under this skill by default.
- [references/management-patterns.md](references/management-patterns.md)
	Decide where a DBML change belongs and when to create a tenant-specific variant.
- [references/dbml-modeling-rules.md](references/dbml-modeling-rules.md)
	Apply consistent rules for business keys, logical refs, schemas, and notes.

## Output Expectations

When editing or creating DBML with this skill:

- Keep file contents in English.
- Preserve existing repository naming if already established.
- Explain whether each relationship is physical or logical.
- Prefer a few coherent files over one giant monolith.
- Mention any ambiguity that affects whether a change belongs in `client.template.dbml` or `client-variants/`.