Versioning & Publish¶

Publishing is the final step in the DBPort workflow. It writes data from DuckDB to the Iceberg warehouse with full metadata, codelist, and version tracking.

Basic publish¶

dbp model publish --version 2026-03-09

port.publish(
    version="2026-03-09",
    params={"wstatus": "EMP", "nace_r2": "TOTAL"},
)

Publish modes¶

# Validate schemas without writing
dbp model publish --version 2026-03-09 --dry-run

# Overwrite a previously published version
dbp model publish --version 2026-03-09 --refresh

# Validate schemas without writing
port.publish(version="2026-03-09", mode="dry")

# Overwrite a previously published version
port.publish(version="2026-03-09", mode="refresh")

Full lifecycle in one command¶

The CLI provides dbp model run to execute the hook and publish in a single step:

dbp model run --version 2026-03-09 --timing

This syncs state, executes the configured hook, and publishes — equivalent to calling port.run(version="2026-03-09") in Python. See Hooks & Execution for details.

Pre-publish checks¶

Idempotency and checkpoints¶

Every publish writes checkpoint properties to the Iceberg table:

• dbport.upload.v2.<version>.completed — marks the version as done
• dbport.upload.v2.<version>.rows_appended — tracks row count

If a publish is interrupted, the next run detects the incomplete checkpoint and resumes from where it left off. Re-running a completed version is a no-op.

What happens on success¶

1. Data is written to the Iceberg table at <agency>.<dataset_id>
2. Codelists are auto-generated (or fetched from attached tables)
3. metadata.json is materialized and embedded in Iceberg table properties
4. A VersionRecord is appended to dbport.lock
5. created_at is set on first publish only; last_updated_at is updated every time

Write strategy¶

The DuckDB iceberg extension is the primary write path.