Skip to content

Developer type-system guide

This guide explains how to extend dpone type inference and physical DDL planning without creating god modules.

Layers

flowchart TD
    Profiler["type_system.profiler"]
    Inference["type_system.inference"]
    Contracts["readiness.schema_contracts"]
    Resolver["readiness.target_type_resolvers"]
    Physical["readiness.physical_design"]
    CLI["commands.schema_plan_cmd"]

    Profiler --> Inference
    Contracts --> Inference
    Inference --> Resolver
    Resolver --> Physical
    Physical --> CLI

Rules

  • Keep source profiling independent from database clients.
  • Keep logical contracts portable.
  • Put target-specific decisions in target type resolvers.
  • Put DDL statement rendering in physical design planners.
  • Route unsafe existing-table DDL through online schema governance.
  • Add tests before adding new target behavior.

Adding a target type resolver

  1. Add logical-to-target mapping in dpone.readiness.target_type_resolvers.
  2. Add DDL rendering in dpone.readiness.physical_design.
  3. Add manifest schema fields only if users need new public config.
  4. Add unit tests for type rendering and DDL rendering.
  5. Add docs in Physical design and target connector docs.

Test checklist

  • canonical logical type parsing;
  • source metadata normalization;
  • sampled inference confidence;
  • explicit contract precedence;
  • target-specific override precedence;
  • unsafe narrowing blocked by governance;
  • docs YAML examples parse;
  • CLI text/json/md output.