Remove migrate subcommand — migrations are out of scope

The migrate subcommand was a thin wrapper around external migration
tools. Use the exec subcommand instead for running external tools
with structured logging.

- Deleted src/cmd/migrate.rs and the unused run_command() helper
- Replaced postgres-migrate-seed example with postgres-seed
- Cleaned all references from docs, Helm chart, and CHANGELOG

Closes #11

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mikkeldamsgaard

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `dprint` formatter for Markdown, JSON, TOML, YAML, and Dockerfile with CI check (`dprint/check@v2.2`) and definition-of-done gate.
 - Structured database connection config as an alternative to URL (`host`, `port`, `user`, `password`, `name`, `options` fields). Passwords with URL-reserved characters (`@`, `%`, `:`, etc.) work without encoding. Connections are built using driver-native APIs (PostgreSQL key-value DSN, MySQL `OptsBuilder`), bypassing URL parsing entirely. The `url`/`url_env` fields remain supported for backward compatibility. See [#39](https://github.com/KitStream/initium/issues/39).
 
+### Removed
+
+- `migrate` subcommand: removed the thin command-execution wrapper. Use `exec` subcommand instead if you need to run an external migration tool with structured logging.
+
 ### Changed
 
 - Renamed `jyq.Dockerfile` to `Dockerfile.jyq` to follow the `Dockerfile.<variant>` convention.
@@ -78,8 +82,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `exec` subcommand: run arbitrary commands with structured logging, exit code forwarding, and optional `--workdir` for child process working directory
 - `fetch` subcommand and `internal/fetch` package: fetch secrets/config from HTTP(S) endpoints with auth header via env var, retry with backoff, TLS options, redirect control (same-site by default), and path traversal prevention
 - `render` subcommand and `internal/render` package: render templates into config files with `envsubst` (default) and Jinja2 template modes, path traversal prevention, and automatic intermediate directory creation
-- `seed` subcommand: run database seed commands with structured logging and exit code forwarding (no idempotency — distinct from `migrate`)
-- `migrate` subcommand: run database migration commands with structured logging, exit code forwarding, and optional idempotency via `--lock-file`
+- `seed` subcommand: run database seed commands with structured logging and exit code forwarding
 - Structured database seeding via `seed` subcommand with YAML/JSON spec files
 - Seed tracking table (`initium_seed` by default) for idempotent seed application
 - Support for PostgreSQL, MySQL, and SQLite database drivers
@@ -117,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Documentation for building custom images using Initium as a base
 - SECURITY.md with vulnerability reporting instructions
 - Apache 2.0 LICENSE
-- Examples for nginx-waitfor, postgres-migrate-seed, config-render, template-functions, and phased-seed use cases
+- Examples for nginx-waitfor, postgres-seed, config-render, template-functions, and phased-seed use cases
 - Unit tests for retry logic, logging, safety path validation, wait-for, sha256, base64, template integration, seed schema parsing, database operations, executor logic, references, idempotency, reset, edge cases, duration parsing, and env var support
 - Integration tests with docker-compose for end-to-end testing against real Postgres 16, MySQL 8.0, and nginx services
 - Helm chart unit tests using helm-unittest plugin covering deployment rendering, securityContext, and configuration

Cargo.toml

@@ -12,7 +12,7 @@ license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/KitStream/initium"
 rust-version = "1.88"
-description = "Swiss-army toolbox for Kubernetes initContainers — wait-for, migrate, seed, render, fetch in a single static Rust binary"
+description = "Swiss-army toolbox for Kubernetes initContainers — wait-for, seed, render, fetch in a single static Rust binary"
 
 [[bin]]
 name = "initium"

FAQ.md

@@ -7,7 +7,7 @@
 Initium is a single binary that replaces ad-hoc bash scripts in Kubernetes `initContainers`. Use it when your pod needs to do any of these before the main container starts:
 
 - Wait for a database or API to become reachable
-- Run database migrations or seed data
+- Seed data into a database
 - Render config files from templates
 - Fetch secrets or config from an HTTP endpoint
 - Run a setup script with structured logging
@@ -82,20 +82,6 @@ initContainers:
 
 Everything after `--` is the command Initium will execute. Initium does not interpret those arguments — it passes them directly via `execve`.
 
-### How do I run database migrations?
-
-Use the `migrate` subcommand. It works the same way as `seed` but is a separate subcommand so you can distinguish migration steps from seed steps in logs:
-
-```yaml
-initContainers:
-  - name: migrate
-    image: ghcr.io/kitstream/initium:latest
-    args: ["migrate", "--", "flyway", "migrate"]
-    env:
-      - name: FLYWAY_URL
-        value: "jdbc:postgresql://postgres:5432/mydb"
-```
-
 ### How do I render a config file from a template before my app starts?
 
 Use the `render` subcommand. Mount a ConfigMap containing your template and let Initium expand environment variables into the output:
@@ -209,11 +195,11 @@ docker run --rm --network mynet ghcr.io/kitstream/initium:latest \
 The `--` tells Initium where its own flags end and the wrapped command begins. Without it, Initium might try to interpret your tool's flags as its own:
 
 ```yaml
-# Correct — Initium sees "migrate" subcommand, then passes "flyway migrate" to execve
-args: ["migrate", "--", "flyway", "migrate"]
+# Correct — Initium sees "exec" subcommand, then passes "setup.sh" to execve
+args: ["exec", "--", "/bin/setup.sh"]
 
-# Wrong — Initium tries to parse "flyway" as a flag to the migrate subcommand
-args: ["migrate", "flyway", "migrate"]
+# Wrong — Initium tries to parse "/bin/setup.sh" as a flag to the exec subcommand
+args: ["exec", "/bin/setup.sh"]
 ```
 
 This is the same convention used by `kubectl`, `docker`, and many other CLI tools.
@@ -392,7 +378,7 @@ spec:
 
 The initContainer writes to `/work`, and the main container reads from it.
 
-### How do I chain multiple init steps (wait → migrate → seed)?
+### How do I chain multiple init steps (wait → seed)?
 
 Define multiple initContainers in order. Kubernetes runs them sequentially:
 
@@ -409,14 +395,9 @@ initContainers:
       capabilities:
         drop: [ALL]
 
-  - name: migrate
-    image: ghcr.io/kitstream/initium:latest
-    args: ["migrate", "--", "/app/migrate", "up"]
-    securityContext: *initium-security
-
   - name: seed
     image: ghcr.io/kitstream/initium:latest
-    args: ["seed", "--", "/app/seed", "--file", "/seeds/data.sql"]
+    args: ["seed", "--spec", "/seeds/seed.yaml"]
     securityContext: *initium-security
 ```
 

README.md

@@ -2,7 +2,7 @@
 
 **Swiss-army toolbox for Kubernetes initContainers.**
 
-Initium replaces fragile bash scripts in your initContainers with a single, security-hardened, multi-tool binary. Wait for dependencies, run migrations, render config files, fetch secrets, and more — all with structured logging, retries, and safe defaults.
+Initium replaces fragile bash scripts in your initContainers with a single, security-hardened, multi-tool binary. Wait for dependencies, seed databases, render config files, fetch secrets, and more — all with structured logging, retries, and safe defaults.
 
 [![CI](https://github.com/kitstream/initium/actions/workflows/ci.yml/badge.svg)](https://github.com/kitstream/initium/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
@@ -66,7 +66,6 @@ kubectl apply -f https://raw.githubusercontent.com/kitstream/initium/main/exampl
 | 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 |
@@ -192,20 +191,6 @@ initContainers:
 
 See [docs/seeding.md](docs/seeding.md) for the full schema, features, and examples.
 
-### How do I run database migrations?
-
-Use the `migrate` subcommand — it wraps your migration tool with structured logging:
-
-```yaml
-initContainers:
-  - name: migrate
-    image: ghcr.io/kitstream/initium:latest
-    args: ["migrate", "--", "flyway", "migrate"]
-    env:
-      - name: FLYWAY_URL
-        value: "jdbc:postgresql://postgres:5432/mydb"
-```
-
 ### How do I render config templates?
 
 Use the `render` subcommand with environment variable substitution:
@@ -301,7 +286,7 @@ args:
 ## Examples
 
 - [**nginx-waitfor**](examples/nginx-waitfor/): Nginx deployment waiting for a backend service
-- [**postgres-migrate-seed**](examples/postgres-migrate-seed/): Wait → Migrate → Seed workflow
+- [**postgres-seed**](examples/postgres-seed/): Wait → Seed workflow with PostgreSQL
 - [**config-render**](examples/config-render/): Render config from templates before app starts
 
 ## How to Run Locally
@@ -351,7 +336,7 @@ Initium was built to address limitations in existing init container tools:
 | [k8s-wait-for](https://github.com/groundnuty/k8s-wait-for) | Bash     | Needs shell | No         | No               | Requires shell + kubectl |
 | [wait4x](https://github.com/atkrad/wait4x)                 | Go       | ~12 MB      | No         | No               | Minimal OS               |
 
-If you only need TCP/HTTP readiness checks, any of these tools work. Initium is designed for teams that also need migrations, seeding, config rendering, and secret fetching in a single security-hardened binary.
+If you only need TCP/HTTP readiness checks, any of these tools work. Initium is designed for teams that also need seeding, config rendering, and secret fetching in a single security-hardened binary.
 
 ## Documentation
 

charts/initium/Chart.yaml

@@ -14,5 +14,4 @@ keywords:
   - initcontainer
   - init
   - wait
-  - migration
   - kubernetes

charts/initium/tests/deployment_test.yaml

@@ -100,16 +100,6 @@ tests:
           args:
             - --target
             - tcp://postgres:5432
-        - name: run-migration
-          command:
-            - migrate
-          args:
-            - --
-            - flyway
-            - migrate
-          env:
-            - name: FLYWAY_URL
-              value: "jdbc:postgresql://postgres:5432/mydb"
         - name: seed-data
           command:
             - seed
@@ -122,15 +112,9 @@ tests:
           value: wait-for-db
       - equal:
           path: spec.template.spec.initContainers[1].name
-          value: run-migration
-      - equal:
-          path: spec.template.spec.initContainers[1].env[0].name
-          value: FLYWAY_URL
-      - equal:
-          path: spec.template.spec.initContainers[2].name
           value: seed-data
       - equal:
-          path: spec.template.spec.initContainers[2].args
+          path: spec.template.spec.initContainers[1].args
           value:
             - --spec
             - /seeds/seed.yaml

charts/initium/values.yaml

@@ -35,7 +35,7 @@ sampleDeployment:
 # Define initContainers that Initium should run.
 # Each entry becomes an initContainer in the sample deployment.
 #
-# Example: wait for Postgres, render config, then run migration
+# Example: wait for Postgres, then render config
 initContainers:
 # - name: wait-for-postgres
 #   command: ["wait-for"]
@@ -62,16 +62,6 @@ initContainers:
 #     - name: DB_PORT
 #       value: "5432"
 
-# - name: run-migration
-#   command: ["migrate"]
-#   args:
-#     - --
-#     - /usr/bin/flyway
-#     - migrate
-#   env:
-#     - name: FLYWAY_URL
-#       value: jdbc:postgresql://postgres:5432/mydb
-
 # Additional volumes to mount into initContainers
 extraVolumes: []
 # - name: templates

docs/design.md

@@ -11,8 +11,8 @@ Initium is a single Rust binary with multiple subcommands, each addressing a com
 ├─────────────────────────────────────────┤
 │               src/cmd/                  │
 │   ┌──────────┬──────────┬────────────┐  │
-│   │ wait-for │ migrate  │  render    │  │
-│   │ seed     │  fetch   │   exec     │  │
+│   │ wait-for │  render  │   fetch    │  │
+│   │ seed     │   exec   │            │  │
 │   └──────────┴──────────┴────────────┘  │
 ├─────────────────────────────────────────┤
 │          Shared Libraries               │
@@ -31,7 +31,6 @@ src/
   cmd/                Subcommand implementations (one file per command)
     mod.rs            Shared command execution helpers
     wait_for.rs       Wait for endpoints
-    migrate.rs        Database migrations
     seed.rs           Database seeding
     render.rs         Template rendering
     fetch.rs          HTTP fetch

docs/usage.md

@@ -67,52 +67,6 @@ initium wait-for \
 
 Targets are checked sequentially. All must become reachable before the command succeeds.
 
-### migrate
-
-Run a database migration command with structured logging, exit code forwarding,
-and optional idempotency via a lock file.
-
-The command is executed directly via `execve` (no shell). Use `--` to separate
-initium flags from the migration command and its arguments.
-
-```bash
-# Run a flyway migration
-initium migrate -- flyway migrate
-
-# Run with JSON logs
-initium migrate --json -- /app/migrate -path /migrations up
-
-# Idempotent: skip if already migrated
-initium migrate --lock-file .migrated --workdir /work -- /app/migrate up
-```
-
-**Flags:**
-
-| Flag          | Default  | Env Var             | Description                                                 |
-| ------------- | -------- | ------------------- | ----------------------------------------------------------- |
-| `--workdir`   | `/work`  | `INITIUM_WORKDIR`   | Working directory for file operations                       |
-| `--lock-file` | _(none)_ | `INITIUM_LOCK_FILE` | Skip migration if this file exists in workdir (idempotency) |
-| `--json`      | `false`  | `INITIUM_JSON`      | Enable JSON log output                                      |
-
-**Behavior:**
-
-- stdout and stderr from the migration command are captured and logged with timestamps
-- The child process exit code is forwarded: a non-zero exit code causes `migrate` to fail
-- When `--lock-file` is set:
-  - If the lock file exists in `--workdir`, the migration is skipped (exit 0)
-  - On successful completion, the lock file is created so subsequent runs become no-ops
-  - If the migration fails, no lock file is created
-- Lock file paths are validated against `--workdir` to prevent path traversal
-- No shell is used: the command is executed directly via `execve`
-
-**Exit codes:**
-
-| Code | Meaning                                        |
-| ---- | ---------------------------------------------- |
-| `0`  | Migration succeeded (or skipped via lock file) |
-| `1`  | Migration command failed, or invalid arguments |
-| _N_  | Forwarded from the migration command           |
-
 ### seed
 
 Apply structured database seeds from a YAML or JSON spec file.

…es/postgres-migrate-seed/deployment.yaml examples/postgres-seed/deployment.yamlexamples/postgres-migrate-seed/deployment.yaml renamed to examples/postgres-seed/deployment.yaml examples/postgres-migrate-seed/deployment.yaml renamed to examples/postgres-seed/deployment.yaml

@@ -1,27 +1,26 @@
-# Postgres migrate + seed example
+# Postgres wait + seed example
 #
 # This example shows a deployment that:
 # 1. Waits for Postgres to be reachable
-# 2. Runs database migrations
-# 3. Seeds initial data
+# 2. Seeds initial data
 #
 # Usage:
-#   kubectl apply -f examples/postgres-migrate-seed/deployment.yaml
+#   kubectl apply -f examples/postgres-seed/deployment.yaml
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: app-with-migration
+  name: app-with-seed
   labels:
-    app: app-with-migration
+    app: app-with-seed
 spec:
   replicas: 1
   selector:
     matchLabels:
-      app: app-with-migration
+      app: app-with-seed
   template:
     metadata:
       labels:
-        app: app-with-migration
+        app: app-with-seed
     spec:
       initContainers:
         - name: wait-for-postgres
@@ -41,41 +40,12 @@ spec:
               drop:
                 - ALL
 
-        - name: run-migration
-          image: ghcr.io/kitstream/initium:latest
-          args:
-            - migrate
-            - --
-            - /app/migrate
-            - -path
-            - /migrations
-            - up
-          env:
-            - name: DATABASE_URL
-              valueFrom:
-                secretKeyRef:
-                  name: postgres-credentials
-                  key: url
-          securityContext:
-            runAsNonRoot: true
-            runAsUser: 65534
-            readOnlyRootFilesystem: true
-            allowPrivilegeEscalation: false
-            capabilities:
-              drop:
-                - ALL
-          volumeMounts:
-            - name: workdir
-              mountPath: /work
-
         - name: seed-data
           image: ghcr.io/kitstream/initium:latest
           args:
             - seed
-            - --
-            - /app/seed
-            - --file
-            - /seeds/initial.sql
+            - --spec
+            - /seeds/seed.yaml
           env:
             - name: DATABASE_URL
               valueFrom:
@@ -93,6 +63,9 @@ spec:
           volumeMounts:
             - name: workdir
               mountPath: /work
+            - name: seed-specs
+              mountPath: /seeds
+              readOnly: true
 
       containers:
         - name: app
@@ -107,3 +80,6 @@ spec:
       volumes:
         - name: workdir
           emptyDir: {}
+        - name: seed-specs
+          configMap:
+            name: seed-specs