Skip to content

dct migrate

Update board YAML to the latest released version. Use it after upgrading dbt Charts when a dashboard reports that it uses older YAML syntax. The command recognizes syntax from the YAML shape; authors never write a version field themselves. dct migrate writes one automatically -- an informational _schema_version: field, added as the file's first line with a comment marking it as auto-written -- so a later parse failure can report that a file targets a newer dbt Charts than the one reading it.

dct migrate [OPTIONS] [PATH]...

Arguments

Argument Description
PATH... Board YAML file or directory to migrate. Omit paths to scan the project root.

Options

Flag Description
--dry-run Report the files that would change without writing them.
--project-dir PATH Project root for resolving paths.

Preview and Apply a Migration

Start with a dry run, review the change in your working tree, then rerun without --dry-run to write it.

dct migrate --dry-run
dct migrate
git diff

For a targeted migration, pass a board file or a directory:

dct migrate charts/revenue.yml
dct migrate charts/

The command prints a summary of updated files, files that already use current syntax, and files that need manual repair. It exits with status 1 when any file cannot be migrated; files with independent, successful migrations are still written.

What Gets Rewritten

A file that already matches the latest released grammar is left unchanged, even if it was created with an older dbt Charts release. Otherwise dbt Charts looks for constructs that supported grammars have since retired, starting from the oldest one still kept, and applies every safe, structural migration between the grammar those constructs belong to and the latest released one -- never further: dct migrate never introduces syntax from an unreleased, in-development version, even when one is already in flight for the next release. A file carrying leftovers from two different grammars starts at the older of the two.

Keys dbt Charts has added since a grammar was frozen are usually left alone; they are simply newer than the retired construct sitting next to them. One exception is worth knowing: when such a key shares its name with a long-standing field elsewhere in the grammar, it can still stop a retired key beside it from being rewritten. The file is reported as using unsupported syntax rather than migrated; removing the newer key and re-running migrates it.

For example, the retired style.board: block is renamed to style.frame::

# Before
style:
  board:
    width: 1200

# After
style:
  frame:
    width: 1200

This recognition is not a claim about when you wrote the file. It only answers which grammar the retired constructs still in it came from.

When dct migrate cannot finish a file

A file that carries both the old and the new spelling of a key, or an unrelated error beside a retired key, is not rewritten. dct validate still names the successor of each retired key:

Unknown field 'zero' at charts.rev.bar.style.axis_y.grid.
`zero` was renamed to `threshold` in 0.7.0. Rename the key.

Manual Repair

dct migrate only performs declared, lossless structural changes. It stops for a file when a change would alter meaning, discard information, or conflict with an already-present destination key. The error names the conflicting path. For a file that migrates but still does not match the current grammar, the error names where validation stopped: a container rather than the exact key, since dct migrate has no parser pass behind it; run dct validate for the precise location. Make that repair yourself, then run dct validate to check the result.

dct migrate charts/revenue.yml
# Repair the path reported by the command.
dct validate charts/revenue.yml

The command does not make backups or offer rollback. Keep your dashboards in version control and use git diff to review the rewrite; use git revert if you need to undo a committed migration.