fix(migrations): auto-create required extensions, prevent dirty state

[bclermont]

Problem

goclaw's initial migration (migrations/000001_init_schema.up.sql) executed:

CREATE EXTENSION IF NOT EXISTS "pgcrypto";
CREATE EXTENSION IF NOT EXISTS "vector";

Both extensions require superuser privileges. When goclaw connects with a least-privilege database role (the recommended security posture), the migration fails midway and marks the schema as dirty (schema_migrations.dirty = true). This blocks all subsequent boots with no automated recovery — the only workaround is manual intervention to clean the schema.

Root Cause

PostgreSQL does not allow non-superuser roles to create extensions (unless explicitly granted CREATE privilege). Once a migration fails, the dirty flag prevents the app from starting again until the flag is manually cleared.

Solution

Move extension creation out of the migration into a pre-flight check that auto-creates them. This prevents the dirty state entirely.

Changes

1. migrations/000001_init_schema.up.sql

   • Remove CREATE EXTENSION statements
   • Document pgcrypto/pgvector as prerequisites in header

2. internal/upgrade/checker.go - Add EnsureExtensions()

   • Checks if extensions exist before migrations run
   • Automatically creates them (works with privileged roles)
   • Returns clear, actionable error if creation fails (includes SQL for DBA)

3. cmd/migrate.go & cmd/upgrade.go

   • Call EnsureExtensions(db) before running migrations
   • Prevents dirty state by ensuring extensions upfront

Behavior

Scenario	Before	After
Role has privilege	Migration fails → dirty	Extensions auto-created → success
Role lacks privilege	Migration fails → dirty	Clear error with DBA SQL
Extensions missing	N/A	Attempt auto-create
Extensions exist	Works	Works (fast check, no-op)

Error Message Example

If auto-creation fails due to insufficient privilege:

extension "pgcrypto" is required but missing.
Attempted to create it, but got permission error: ...

Ask your database administrator to run:
  CREATE EXTENSION IF NOT EXISTS "pgcrypto";

The goclaw database role may need explicit CREATE privilege on pgcrypto and pgvector.

Migration Path

Existing deployments:

• If extensions already created: no change, works normally
• If dirty state: EnsureExtensions will try to fix on next upgrade

Fresh deployments:

• Extensions auto-created on first goclaw upgrade (if role has privilege)
• Otherwise: clear error with manual SQL for DBA

Test environments:

• Auto-created by test role (usually sufficient privilege)
• Resolves need for postgres-init.sh pre-creation workaround

Testing

• Migration succeeds when extensions auto-created
• Clear error when auto-creation fails (permission denied)
• Existing deployments with pre-created extensions unaffected
• Test role auto-creates extensions on fresh DB
• No dirty state in any scenario

[clark-cant]

Review: fix(migrations) auto-create required extensions

Summary: Moves CREATE EXTENSION out of migration 000001 into a pre-flight EnsureExtensions() check to prevent dirty schema state when running as non-superuser.

Risk level: Medium — touches migration path, upgrade path, and CLI entry points.

Mandatory gates:

• Duplicate/prior implementation: clear — no prior PR addresses this exact migration-dirty-state path
• Project standards: inferred from codebase patterns
• Strategic necessity: clear value — prevents unrecoverable dirty state for least-privilege deployments

Findings

Critical

• go CI unit tests FAILING — run #29438786446 job go fails at "Unit tests" step. Must be green before merge.

Important

• cmd/migrate.go: redundant DB connection — connectDB(dsn) already opens db above. This PR opens a second sql.Open("pgx", dsn) just for EnsureExtensions, then closes it. Reuse the existing db handle instead of creating a second connection that leaks if newMigrator fails between the close and the open.
• cmd/upgrade.go runUpgradeStatus: error swallowed — fmt.Print(err) writes to stdout (not stderr) and then return nil silently discards the error. The status subcommand will print an extension error as if everything is fine. Either return the error or print to stderr and set a non-zero exit indicator.

Suggestion

• cmd/upgrade.go runUpgrade: same fmt.Print(err) pattern — consider fmt.Fprintln(os.Stderr, err) for consistency.
• internal/upgrade/checker.go createExtension: extension names are hardcoded so no real injection risk, but consider using a constant slice instead of fmt.Sprintf for the SQL to make the intent clearer.

Verdict: Request changes

Fix the CI failure and the redundant connection / error-swallowing issues, then this is a solid improvement.

Posted by github-maintain cron at 2026-07-17T13:30:00Z