dbml-multi-db-schema

name	dbml-multi-db-schema
description	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.

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/.