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 before deciding file placement.
4. Read 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:

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:

.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 Decide where a DBML change belongs and when to create a tenant-specific variant.
• 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/.