Concepts¶

Understand the design decisions behind DBPort before diving into the API.

DBPort handles the edges of periodic dataset recomputation: loading versioned inputs, enforcing output schemas, tracking publish history, and managing metadata. The model logic in between is yours.

Core ideas¶

• Inputs & Loading — how warehouse tables are loaded into DuckDB with snapshot caching and filter pushdown
• Outputs & Schemas — how output contracts are declared, enforced, and validated against the warehouse
• Metadata & Codelists — automatic lifecycle fields, codelist generation, and column-level overrides
• Lock File — the committable TOML file that tracks schema, ingest state, and version history
• Hooks & Execution — how run hooks are resolved, dispatched, and trusted
• Versioning & Publish — idempotent publication, checkpoints, publish modes, and schema drift protection

Start with Inputs & Loading if you want to understand data flow, or Lock File if you want to understand project state.

The mental model¶

graph LR
    A["Warehouse"] -->|"dbp model load"| B["DuckDB"]
    B -->|"dbp model exec"| B
    B -->|"dbp model publish"| C["Warehouse"]
    style A fill:#f5f5f5,stroke:#1F4E79
    style B fill:#f5f5f5,stroke:#E07A5F
    style C fill:#f5f5f5,stroke:#1F4E79

You bring the model. DBPort manages the dataset lifecycle.

See also: API Reference for exact signatures · Examples for applied usage