feat: extend seed with phases, object waiting, schema creation, and MiniJinja templating (#15) (#16)

* feat: extend seed with phases, object waiting, schema creation, and MiniJinja templating. Add seed schema version 2 with phase-based execution supporting ordered phases with create/wait/seed lifecycle, MiniJinja template rendering, embedded database/schema creation via create_if_missing, wait-for logic polling for tables/views/schemas/databases with timeouts, cross-phase @ref: references, and driver-aware error reporting. New Database trait methods: create_database, create_schema, object_exists, driver_name for SQLite, PostgreSQL, MySQL. 32 new tests, all 98 pass. Closes #15

Author: mikkeldamsgaard

CHANGELOG.md

@@ -7,10 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+- Seed schema version 1 (flat `seed_sets` without phases): all seed specs now use phase-based structure
+- `version` field from seed spec schema: no longer required or accepted
+
+### Added
+- Seed schema with phase-based execution: ordered phases with create → wait → seed lifecycle
+- MiniJinja template rendering for seed spec files: dynamic values, conditionals, loops via `{{ env.VAR }}`
+- Embedded database/schema creation via `create_if_missing` in seed phases (PostgreSQL, MySQL)
+- Embedded wait-for logic: poll for tables, views, schemas, or databases with configurable per-phase and per-object timeouts
+- Database trait methods: `create_database`, `create_schema`, `object_exists`, `driver_name` for SQLite, PostgreSQL, MySQL
+- Cross-phase `@ref:` references: references defined in earlier phases resolve in later phases
+- Documentation: schema reference, driver support tables, MiniJinja templating guide, failure modes in `docs/seeding.md`
+- Example: `examples/seed/phased-seed.yaml` — multi-phase PostgreSQL seeding with wait-for, create-if-missing, and MiniJinja
+
 ### Changed
 - Seed executor tests now verify data actually arrived in the database after execution, using file-based SQLite and post-execution queries to assert row counts, column values, cross-table references, env substitution, ordering, and edge cases
 
 ### Fixed
+- Aligned all markdown table columns across documentation files (`FAQ.md`, `README.md`, `docs/security.md`, `docs/seeding.md`, `docs/usage.md`)
 - Fixed clippy `collapsible_if` lint in seed executor's unique key check
 - Removed dead code: unused `src/cmd/seed.rs` module (replaced by `src/seed/`)
 - Suppressed unused field warning on `AutoIdConfig.id_type` (reserved for future use)

FAQ.md

@@ -147,14 +147,14 @@ This is useful when you're shipping logs to a centralized system like Loki, Data
 
 All retry parameters are flags on the `wait-for` subcommand:
 
-| Flag | Default | What it does |
-|------|---------|-------------|
-| `--max-attempts` | `60` | Total number of attempts before giving up |
-| `--initial-delay` | `1s` | Delay after the first failure |
-| `--max-delay` | `30s` | Upper bound on delay between retries |
-| `--backoff-factor` | `2.0` | Multiplier applied to the delay after each attempt |
-| `--jitter` | `0.1` | Random fraction (0.0–1.0) added to each delay to prevent thundering herd |
-| `--timeout` | `5m` | Hard deadline across all targets |
+| Flag               | Default   | What it does                                                             |
+| ------------------ | --------- | ------------------------------------------------------------------------ |
+| `--max-attempts`   | `60`      | Total number of attempts before giving up                                |
+| `--initial-delay`  | `1s`      | Delay after the first failure                                            |
+| `--max-delay`      | `30s`     | Upper bound on delay between retries                                     |
+| `--backoff-factor` | `2.0`     | Multiplier applied to the delay after each attempt                       |
+| `--jitter`         | `0.1`     | Random fraction (0.0–1.0) added to each delay to prevent thundering herd |
+| `--timeout`        | `5m`      | Hard deadline across all targets                                         |
 
 Example — fast retries with low jitter:
 
@@ -449,12 +449,12 @@ kubectl logs <pod-name> -c <initcontainer-name>
 
 Common causes:
 
-| Symptom | Likely cause | Fix |
-|---------|-------------|-----|
+| Symptom                                   | Likely cause                                 | Fix                                                                          |
+| ----------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
 | `target not reachable` after all attempts | Target service isn't running or DNS is wrong | Check the service/endpoint exists and is in the same namespace (or use FQDN) |
-| `unsupported target scheme` | Missing `tcp://` or `http://` prefix | Add the scheme: `tcp://postgres:5432` not just `postgres:5432` |
-| `path traversal detected` | Output path tries to escape workdir | Use a relative path for `--output` |
-| `context cancelled` | Overall `--timeout` was too short | Increase `--timeout` or check why the target takes so long |
+| `unsupported target scheme`               | Missing `tcp://` or `http://` prefix         | Add the scheme: `tcp://postgres:5432` not just `postgres:5432`               |
+| `path traversal detected`                 | Output path tries to escape workdir          | Use a relative path for `--output`                                           |
+| `context cancelled`                       | Overall `--timeout` was too short            | Increase `--timeout` or check why the target takes so long                   |
 
 ### Does Initium support ARM-based nodes (e.g., AWS Graviton)?
 

README.md

@@ -38,26 +38,26 @@ kubectl apply -f https://raw.githubusercontent.com/kitstream/initium/main/exampl
 
 ## Why Initium?
 
-| | Bash scripts | Initium |
-|---|---|---|
-| **Retries with backoff** | DIY, error-prone | Built-in, configurable |
-| **Structured logging** | `echo` statements | JSON or text with timestamps |
-| **Security** | Runs as root, full shell | Non-root, no shell, read-only FS |
-| **Secret handling** | Easily leaked in logs | Automatic redaction |
-| **Multiple tools** | Install curl, netcat, psql… | Single 2MB image |
-| **Reproducibility** | Shell differences across distros | Single Rust binary, `FROM scratch` |
-| **Vulnerability surface** | Full OS + shell utils | Zero OS packages |
+|                           | Bash scripts                     | Initium                            |
+| ------------------------- | -------------------------------- | ---------------------------------- |
+| **Retries with backoff**  | DIY, error-prone                 | Built-in, configurable             |
+| **Structured logging**    | `echo` statements                | JSON or text with timestamps       |
+| **Security**              | Runs as root, full shell         | Non-root, no shell, read-only FS   |
+| **Secret handling**       | Easily leaked in logs            | Automatic redaction                |
+| **Multiple tools**        | Install curl, netcat, psql…      | Single 2MB image                   |
+| **Reproducibility**       | Shell differences across distros | Single Rust binary, `FROM scratch` |
+| **Vulnerability surface** | Full OS + shell utils            | Zero OS packages                   |
 
 ## Subcommands
 
-| Command | Description | Status |
-|---------|-------------|--------|
-| `wait-for` | Wait for TCP/HTTP/HTTPS endpoints | ✅ Available |
-| `migrate` | Run database migrations | ✅ Available |
-| `seed` | Structured database seeding from YAML/JSON | ✅ Available |
-| `render` | Render config templates | ✅ Available |
-| `fetch` | Fetch secrets/config from HTTP | ✅ Available |
-| `exec` | Run commands with structured logging | ✅ Available |
+| Command    | Description                                                          | Status      |
+| ---------- | -------------------------------------------------------------------- | ----------- |
+| `wait-for` | Wait for TCP/HTTP/HTTPS endpoints                                    | ✅ Available |
+| `migrate`  | Run database migrations                                              | ✅ Available |
+| `seed`     | Structured database seeding from YAML/JSON with MiniJinja templating | ✅ Available |
+| `render`   | Render config templates                                              | ✅ Available |
+| `fetch`    | Fetch secrets/config from HTTP                                       | ✅ Available |
+| `exec`     | Run commands with structured logging                                 | ✅ Available |
 
 ### wait-for
 

docs/security.md

@@ -15,16 +15,16 @@ Initium runs as an initContainer in Kubernetes pods. Its threat model considers:
 
 ### Attack Vectors Addressed
 
-| Vector | Mitigation |
-|--------|-----------|
-| **Path traversal** | All file writes constrained to `--workdir`; absolute paths rejected; `..` sequences resolved and validated |
-| **Secret leakage via logs** | Automatic redaction of keys matching `token`, `password`, `secret`, `auth`, `api_key`, `authorization` |
-| **Privilege escalation** | Container runs as UID 65534 (nobody); `allowPrivilegeEscalation: false`; all capabilities dropped |
-| **Filesystem tampering** | `readOnlyRootFilesystem: true`; writes only to mounted emptyDir volumes |
-| **Unintended network access** | All target URLs must be explicitly provided via flags; no default outbound connections |
-| **TLS downgrade** | TLS verification enabled by default; `--insecure-tls` requires explicit opt-in |
-| **Shell injection** | Commands executed via `execve` (no shell); `--` separator for command arguments |
-| **Supply chain** | Minimal `scratch` base image; SBOM and provenance attestation in CI; pinned dependencies |
+| Vector                        | Mitigation                                                                                                 |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Path traversal**            | All file writes constrained to `--workdir`; absolute paths rejected; `..` sequences resolved and validated |
+| **Secret leakage via logs**   | Automatic redaction of keys matching `token`, `password`, `secret`, `auth`, `api_key`, `authorization`     |
+| **Privilege escalation**      | Container runs as UID 65534 (nobody); `allowPrivilegeEscalation: false`; all capabilities dropped          |
+| **Filesystem tampering**      | `readOnlyRootFilesystem: true`; writes only to mounted emptyDir volumes                                    |
+| **Unintended network access** | All target URLs must be explicitly provided via flags; no default outbound connections                     |
+| **TLS downgrade**             | TLS verification enabled by default; `--insecure-tls` requires explicit opt-in                             |
+| **Shell injection**           | Commands executed via `execve` (no shell); `--` separator for command arguments                            |
+| **Supply chain**              | Minimal `scratch` base image; SBOM and provenance attestation in CI; pinned dependencies                   |
 
 ## Safe Defaults