feat: hint at extension dependency when plan fails with missing object errors (#436)

[tianzhou]

Summary

Follow-up to #436 (and the discussion in #121 / #437): pgschema intentionally does not manage extension lifecycle, but the error users hit when their schema depends on an extension is opaque:

failed to apply schema SQL to temporary schema pgschema_tmp_...: ERROR: data type uuid has no default operator class for access method "gist" (SQLSTATE 42704)

This PR detects the common SQLSTATEs for this failure mode during desired-state apply — 42704 undefined_object (missing type / operator class) and 42883 undefined_function (missing function / operator) — and appends a hint pointing at the supported solution:

• Embedded plan path: suggests using an external plan database with the extension installed (--plan-host), since the embedded postgres binaries cannot provide extensions at all
• External plan path: suggests installing the extension in the plan database (CREATE EXTENSION)

Both hints link to https://www.pgschema.com/cli/plan-db. Errors with other SQLSTATEs (and non-PostgreSQL errors) pass through unchanged.

Example output for the repro in #436 (EXCLUDE USING gist on uuid, requires btree_gist):

failed to apply schema SQL to temporary schema pgschema_tmp_...: ERROR: data type uuid has no default operator class for access method "gist" (SQLSTATE 42704)
Hint: this schema may depend on a PostgreSQL extension, which the embedded plan database cannot provide. Use an external plan database with the extension installed (--plan-host), see https://www.pgschema.com/cli/plan-db

Changes

• internal/postgres/desired_state.go: new hintExtensionDependency helper
• internal/postgres/embedded.go, internal/postgres/external.go: wire the hint into the desired-state apply error path with provider-specific wording
• internal/postgres/desired_state_test.go: unit tests covering both SQLSTATEs, composition with the existing error-location snippet, and pass-through behavior

Testing

• go test ./internal/postgres passes
• Verified end-to-end against a real embedded PostgreSQL 17 using the exact schema from Include Required Extensions in Dump Output #436 — the hint appears as shown above

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds extension-dependency hints when desired-state planning fails on missing PostgreSQL objects. The main changes are:

• New helper for detecting PostgreSQL missing-object and missing-function SQLSTATEs.
• Embedded plan database errors now suggest using an external plan database with extensions installed.
• External plan database errors now suggest installing the needed extension in the plan database.
• Unit tests cover hinted SQLSTATEs, wrapped apply errors, and pass-through behavior.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

_{Reviews (1): Last reviewed commit: "feat: hint at extension dependency when ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR improves the usability of plan failures caused by missing PostgreSQL extension-provided objects by detecting common “missing object” SQLSTATEs during desired-state apply and appending a provider-specific hint explaining how to resolve the issue (embedded vs external plan DB).

Changes:

• Added hintExtensionDependency to append an actionable hint for SQLSTATE 42704 (undefined_object) and 42883 (undefined_function) errors.
• Wired the hint into the desired-state apply error path for both embedded and external plan database providers with tailored guidance.
• Added unit tests covering the hinting behavior, including interaction with existing enhanceApplyError wrapping and pass-through for other error types.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
internal/postgres/desired_state.go	Adds helper to detect missing-object SQLSTATEs and append an extension-dependency hint while preserving error unwrapping.
internal/postgres/embedded.go	Appends an embedded-specific hint explaining embedded plan DBs can’t provide extensions and suggesting --plan-host.
internal/postgres/external.go	Appends an external-specific hint advising to install the missing extension in the plan database (CREATE EXTENSION).
internal/postgres/desired_state_test.go	Adds tests for hinting behavior, wrapping compatibility, and pass-through cases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.