Adopt golang-migrate for standardized schema migrations

[haasonsaas]

Context

Each Go service invents its own migration approach:

• objectives: bespoke EnsureSchema() — runs all SQL via CREATE TABLE IF NOT EXISTS at startup. No history table, no rollback, no versioning.
• asb: custom migrate.Runner reading .sql files from disk
• entities/connectors/skills: re-run CREATE TABLE IF NOT EXISTS on every startup
• Python services use Alembic via fermata/migrations

No service uses goose, golang-migrate, or Atlas. Migrations run inline at startup, making zero-downtime schema changes risky (DDL locks during traffic).

Requirements

• Add golang-migrate (or goose) as a shared dependency in service-runtime
• Add migrate.Run(db, migrationsDir) helper that services call at startup
• Support up, down, version commands via CLI flag or env var
• Add a pre-deploy migration Job template for Helm charts (like the Python migration-job.yaml ArgoCD PreSync hook)
• Migrate at least one service (e.g., objectives or audit) as a reference implementation
• Document migration best practices: online DDL, CREATE INDEX CONCURRENTLY, advisory locks

Impact

Enables safe schema evolution across 15+ Go services. Currently any ALTER TABLE that needs a migration path beyond IF NOT EXISTS is impossible without custom code per service.

[haasonsaas]

Taking this now. I’m working it as the first shared migration-runtime slice: standard golang-migrate support in service-runtime with startup/CLI entry points and docs, then I’ll assess how much reference adoption fits cleanly in the same PR.

[haasonsaas]

Draft PR is up for the shared runtime slice: #124

This branch adds the migrate package, Postgres bootstrap helpers, docs, and a reusable Helm migration job template. I also fixed a pre-existing local natsbus test race so the repo’s go test ./... -race matrix is green again.

Local validation:

• go test ./migrate ./postgres -count=1
• go test ./... -count=1
• go test ./... -race -count=1
• golangci-lint run ./...

I have not done the reference consumer adoption yet; meter still looks like the cleanest next follow-on for that part of the issue.

[haasonsaas]

Reference implementation is up in evalops/meter#74.

That PR switches meter to postgres.OpenAndMigrateIOFS, embeds versioned SQL migrations, and documents the METER_MIGRATE_* controls. It depends on this shared runtime slice landing first, so I left it as a draft stack-on-top PR for now.

Local validation on the meter side was:

• go test ./... -count=1
• GOTOOLCHAIN=go1.26.0 go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest run ./...