Skip to content

Platform options

platform_options in project.yaml configures render-time defaults for the active target_platform. They are not crawled from the database and not tracked in state — they shape the SQL dtm emits, nothing else.

Options are grouped by object type (tables, future views, …). Today only tables is exposed, and only for target_platform: azure_databricks. A snowflake block will be added when a Snowflake renderer lands; the YAML key stays the same and the schema is selected by target_platform.

tables.properties (azure_databricks)

A key-value map emitted as TBLPROPERTIES (...) on every CREATE TABLE statement.

target_platform: azure_databricks

platform_options:
  tables:
    properties:
      delta.columnMapping.mode: name

A CREATE TABLE then renders as:

CREATE TABLE IF NOT EXISTS sales.raw.orders (
    id bigint NOT NULL
)
TBLPROPERTIES ('delta.columnMapping.mode' = 'name');

When to use it

For Delta properties that:

  1. Must be set at creation time — most notably delta.columnMapping.mode = name, which is a precondition for DROP COLUMN and column renames on Databricks. Setting it post-hoc requires a reader/writer version upgrade and is not equivalent to setting it at create time.
  2. Are solution-wide invariants — every table in the solution should have the same value. Per-table overrides aren't supported; if you need that, use a user-defined migration.

Values are emitted as strings (Databricks accepts string-typed property values for all built-in Delta properties).

What it does not do

  • No retroactive application. Changing tables.properties in project.yaml does not alter existing tables. The new value only takes effect for tables created on subsequent deployments. There is no automatic ALTER TABLE … SET TBLPROPERTIES emitted.
  • Not part of diffing. dtm does not read TBLPROPERTIES from the database, does not store them in state, and does not detect drift. If someone unsets a property by hand, dtm will not put it back.
  • Not applied on ALTER TABLE. Properties are appended only to CREATE TABLE output. Other generated statements (add column, drop column, alter column, etc.) are unchanged.

Applying properties to existing tables

If you flip delta.columnMapping.mode on after tables already exist, you have two options today:

  1. Author a pre-deployment migration that runs ALTER TABLE … SET TBLPROPERTIES (...) for each affected table. This is the recommended route for a one-off rollout.
  2. Recreate the tables. Drop and recreate — only viable for empty or rebuildable tables.

Extending to other object types

tables is the first object-type group. When dtm grows to manage views (and similar objects) a sibling block will be added — e.g.:

platform_options:
  tables:
    properties: {...}
  views:
    # view-specific options here

Existing tables blocks are unaffected; users who don't need view options simply omit the new section.

Extending to other platforms

When a non-Databricks platform is added, the schema of platform_options is selected by target_platform. Setting target_platform: snowflake will accept a Snowflake-specific options block (potentially different keys, possibly cross-cutting options at the top level) and reject Databricks-specific keys as unknown. Setting both platforms' keys in the same project is not supported — a project has exactly one target platform.