al2dbml 0.8.0

Convert compiled Microsoft Dynamics 365 Business Central AL packages (.app) into DBML schemas.

AL-to-DBML

al2dbml is a small Python CLI that converts a compiled Microsoft Dynamics 365 Business Central AL package (.app) into a DBML schema you can paste straight into dbdiagram.io or dbdocs.io. The pipeline reads SymbolReference.json from the .app archive (tolerating AL's 40-byte header), normalises tables, extensions, enums, and TableRelations, and emits one valid DBML document with Table, Ref, Enum, and TableGroup sections.

Release history and per-version notes live in CHANGELOG.md.

Install

Python 3.10+ is required. The runtime depends only on click and pydbml.

Recommended: uv tool install

uv installs CLI tools into isolated environments and puts the entry point on your PATH, so al2dbml is available globally without touching your system Python.

uv tool install al2dbml

If you don't already have uv:

# Fedora / RHEL / CentOS
sudo dnf install uv

# macOS (Homebrew)
brew install uv

# Anywhere (standalone installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

Upgrade later with uv tool upgrade al2dbml, uninstall with uv tool uninstall al2dbml.

Alternative: pipx

pipx install al2dbml

Alternative: plain pip

Works inside an activated virtualenv. On modern distros that mark system Python as externally-managed (PEP 668), prefer uv tool or pipx instead.

pip install al2dbml

Verify

al2dbml --version
al2dbml --help

Quickstart

al2dbml MyApp.app -o schema.dbml

Drop schema.dbml into https://dbdiagram.io. Without -o, the DBML is streamed to stdout so you can pipe it elsewhere.

al2dbml MyApp.app | less

Grouping

By default tables are bucketed into TableGroups by the last segment of their AL namespace (so Microsoft.Finance.GeneralLedger -> group GeneralLedger). Tables that have no namespace tag fall back to the first whitespace-separated word in their name (so Sales Header + Sales Line -> group Sales). Buckets smaller than two tables are dropped so single-table groups don't clutter the diagram.

Override the source with --group-by:

al2dbml MyApp.app --group-by namespace   # default
al2dbml MyApp.app --group-by word        # legacy first-word grouping
al2dbml MyApp.app --group-by none        # no auto groups (only explicit --group rules apply)

# Auto grouping (default)
al2dbml MyApp.app -o schema.dbml

# Explicit rules; the value is NAME=PATTERN[,PATTERN...] and -g is repeatable
al2dbml MyApp.app -g "Documents=Sales*,Purch*" -g "Master=Customer,Vendor,Item"

# Disable grouping entirely
al2dbml MyApp.app --no-groups

# Keep singleton groups too
al2dbml MyApp.app --min-group-size 1

--no-auto-groups switches off the first-word fallback so only your explicit -g rules apply.

Rich field descriptions (aldoc overlay)

By default, column notes are built from the AL Caption property in SymbolReference.json — which is usually just the field name itself. Real BC field documentation (the "Specifies the customer number..." sentences you see on Microsoft Learn) lives in the AL ToolTip property and /// <summary> XML doc comments, neither of which the compiled .app package preserves.

To get those rich descriptions into your diagram, run aldoc (Microsoft's official AL documentation generator, bundled with the AL Language VS Code extension) once to produce a YAML reference tree, then point al2dbml at it with -d/--docs:

# Step 1: generate docs from your .app (slow, but only once per release)
aldoc generate MyApp.app -o ./myapp-docs/

# Step 2: render the DBML with descriptions overlaid (fast)
al2dbml MyApp.app --docs ./myapp-docs/ -o schema.dbml

The result:

• Each table block gets a Note { ... } body sourced from the AL /// <summary> of the table — e.g. "Stores document-level information for sales quotes, orders, invoices, credit memos, blanket orders, and return orders."
• Each column note leads with the AL ToolTip text — e.g. "Specifies the customer number to whom the goods or services are sold."
• Existing condition / **References** sections still follow, separated by <br><br>

Coverage is uneven: active-document tables (Sales Header, Customer, Item, etc.) are richly documented in real BC; history and buffer tables often have nothing. Where aldoc has no entry, the original Caption-based note (or no note) is used.

TableExtensions

Extensions are merged into their target tables by default. Use --no-merge-extensions to emit them as separate <Target> (Extension) tables instead.

Public Python API

from al2dbml import Diagram, generate, GroupingConfig

# One-shot helper
dbml = generate("MyApp.app", output_path="schema.dbml")

# Or step-by-step for custom grouping
diagram = Diagram.from_app(
    "MyApp.app",
    grouping=GroupingConfig(rules={"Documents": ["Sales*", "Purch*"]}),
)
print(diagram.dbml())

Limitations

• FlowFields are treated as regular fields — the underlying CalcFormula is not interpreted.
• Obsolete fields are emitted alongside active ones; no filtering by ObsoleteState.
• Multi-field primary keys are represented as multiple [pk] flags rather than a composite index, matching DBML's single-PK convention.
• Multi-column secondary keys are not yet emitted as DBML indexes; only single-column secondary keys are surfaced (as [unique] on the column).
• Cross-package references (table relations that point to a table outside the current .app) are preserved as notes on the source column, since the target table is not present in the diagram.
• IF (...) ... ELSE IF (...) ... ELSE ... conditional TableRelation expressions are parsed into one DBML Ref per resolved branch, with each branch's condition recorded in the source column's note. Branches whose target table is missing from the current .app degrade to notes only.
• Render time scales quadratically with the table count inside the underlying pydbml library. Small/medium packages (up to a few hundred tables) finish in under a second. Microsoft's full Base Application (~1,500 tables) currently takes several minutes to render, even though parsing itself is fast. A custom DBML emitter is on the roadmap to remove this cliff.

Development

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -q
.venv/bin/ruff check .