julianobarbosa/power-bi-deployment

Power BI Deployment Skill

Manage model lifecycle with TMDL export/import, transactions, and version control.

Prerequisites

pipx install pbi-cli-tool
pbi-cli skills install
pbi connect

Connecting to Targets

# Local Power BI Desktop (auto-detects port)
pbi connect

# Local with explicit port
pbi connect -d localhost:54321

# Named connections for switching
pbi connect -d localhost:54321 --name dev
pbi connections list
pbi connections last
pbi disconnect

TMDL Export and Import

TMDL (Tabular Model Definition Language) is the text-based format for version-controlling Power BI models.

# Export entire model to TMDL folder
pbi database export-tmdl ./model-tmdl/

# Import TMDL folder into connected model
pbi database import-tmdl ./model-tmdl/

TMSL Export

# Export as TMSL JSON (for SSAS/AAS compatibility)
pbi database export-tmsl

TMDL Diff (Compare Snapshots)

Compare two TMDL export folders to see what changed between snapshots. Useful for CI/CD pipelines ("what did this PR change in the model?").

# Compare two exports
pbi database diff-tmdl ./model-before/ ./model-after/

# JSON output for CI/CD scripting
pbi --json database diff-tmdl ./baseline/ ./current/

Returns a structured summary:

• tables: added, removed, and changed tables with per-table entity diffs (measures, columns, partitions, hierarchies added/removed/changed)
• relationships: added, removed, and changed relationships
• model: changed model-level properties (e.g. culture, default power bi dataset version)
• summary: total counts of all changes

LineageTag-only changes (GUID regeneration without real edits) are automatically filtered out to avoid false positives.

No connection to Power BI Desktop is needed -- works on exported folders.

Database Operations

# List databases on the connected server
pbi database list

Transaction Management

Use transactions for atomic multi-step changes:

# Begin a transaction
pbi transaction begin

# Make changes
pbi measure create "New KPI" -e "SUM(Sales[Amount])" -t Sales
pbi measure create "Another KPI" -e "COUNT(Sales[OrderID])" -t Sales

# Commit all changes atomically
pbi transaction commit

# Or rollback if something went wrong
pbi transaction rollback

Table Refresh

# Refresh individual tables
pbi table refresh Sales --type Full
pbi table refresh Sales --type Automatic
pbi table refresh Sales --type Calculate
pbi table refresh Sales --type DataOnly

Workflow: Version Control with Git

# 1. Export model to TMDL
pbi database export-tmdl ./model/

# 2. Commit to git
cd model/
git add .
git commit -m "feat: add new revenue measures"

# 3. Later, import back into Power BI Desktop
pbi connect
pbi database import-tmdl ./model/

Workflow: Inspect Model Before Deploy

# Get model metadata
pbi --json model get

# Check model statistics
pbi --json model stats

# List all objects
pbi --json table list
pbi --json measure list
pbi --json relationship list

Best Practices

• Always export TMDL before making changes (backup)
• Use transactions for multi-object changes
• Test changes in dev before deploying to production
• Use --json for scripted deployments
• Store TMDL in git for version history
• Use named connections (--name) to avoid accidental changes to wrong environment

---

Gotchas

• import-tmdl is not atomic across the whole folder: If one file fails to parse mid-import, partially-applied changes stick in the connected model. Always pbi transaction begin around import-tmdl, or export a backup first so rollback is just a re-import.
• diff-tmdl filters out lineageTag-only changes by design: Helpful for noise but it also masks legitimate re-tagging that downstream Power BI Service references depend on (deployment pipelines, perspectives, datamarts). Diff the raw folders with git diff when investigating broken references in Service.
• Named connections persist across pbi-cli sessions: --name prod survives even after you've closed Desktop. Running a destructive import-tmdl thinking you're on dev is the classic foot-gun. Always pbi connections last before mutating commands.
• table refresh --type Full rebuilds calculated columns and relationships: On large tables this triggers a long re-process and locks the model. Prefer --type DataOnly for production refreshes; reserve Full for schema changes.
• TMSL export is JSON; TMDL export is folders of text: The two formats are NOT interchangeable for git diffs — TMSL collapses all measures into one large JSON, killing clean diffs. Use TMDL for version control and reserve TMSL for SSAS/AAS compatibility.
• transaction rollback only reverts metadata changes, not data refreshes: If you ran table refresh inside the transaction, the refreshed data stays after rollback. Refreshes commit out-of-band.