Extend Seed with Embedded Schema Creation, Object Waiting, Repetition & MiniJinja Format

[mikkeldamsgaard]

Extend the existing seed subsystem so that schema/database creation and waiting for database objects (tables/views/schemas/databases) are defined within the seed configuration file itself using MiniJinja, can be repeated in sequence, and rendered into a structured plan for execution.

Summary

We want the seed functionality to support:

• Declarative schema/database creation embedded in the seed config
• Waiting for database objects before continuing
• Multiple ordered phases
• MiniJinja templating for expressivity

Embedded MiniJinja Seed Format

The seed config should be a MiniJinja template that renders into a plan with named phases. Each phase may include:

• schema or database to switch to
• createIfMissing boolean indicating whether to create the target if it does not exist
• A list of objects to wait for (table, view, schema, database)
• A timeout for waits
• Seed data definitions

The engine must first render the MiniJinja template, then execute the rendered plan.

Requirements

1. MiniJinja rendering

   • Support rendering of templates into a Go struct representing the plan.
   • Validate the rendered plan against JSON Schema or similar.
   • Use the same format engine as the render command uses.
   • Modify the reference syntax to be usable in this rendering universe.

2. Embedded create logic

   • When a phase specifies schema or database and createIfMissing: true, create the object in the target database if it doesn’t exist.
   • Supported databases: PostgreSQL, MySQL, SQLite.

3. Embedded wait logic

   • Before seeding data for a phase, wait for each object specified in waitFor to exist.
   • Supported waitable object types: schema, table, view, database (PostgreSQL only).
   • Respect a timeout per phase or per object.

4. Repetition support

   • Phases should be executed in defined order.
   • Each phase’s create + wait + seed logic must execute independently.

5. Error handling

   • Timeouts should produce structured errors.
   • Failures should not leave partial states without logs/diagnostics.
   • Clearly report errors if the object is not supported on the underlying engine choosen.

Deliverables

• MiniJinja template support in internal/seed that:
  • Renders and validates seed configs
  • Produces a structured seed plan
• Updated database logic to:
  • Create schemas/databases
  • Wait for objects
  • Execute seed data according to the plan
• Seed examples in examples/seed/ demonstrating phase sequences
• Tests covering:
  • Schema create logic
  • Wait conditions with timeouts
  • Multiple phase execution
  • Errors and edge cases
• Documentation in docs/seeding.md explaining:
  • MiniJinja seed format
  • Embedded create/wait syntax
  • Phase execution semantics
• Update CHANGELOG.md

Acceptance Criteria

• Seed templates using the new format render correctly
• Schema create and wait logic works across PostgreSQL, MySQL, and SQLite
• Timeouts are respected and failures produce clear output
• Documentation covers the embedded format and includes examples
• Tests demonstrate the expected behavior

Rationale

Embedding create and wait semantics directly into the seed configuration provides a more declarative and reproducible way to handle database initialization logic. Using MiniJinja allows flexible templating while keeping the template itself readable and maintainable.