🐘 feat: Guard pgvector Startup DDL

[danny-avila]

Summary

I carried forward the opt-in pgvector startup DDL guards from #310 and completed the schema and column-type safety fixes identified during review. This superseding PR is necessary because GitHub does not permit maintainer edits to the organization-owned source fork.

• Guard legacy index creation, JSON-to-JSONB migration, and GIN index creation behind independent environment flags that default to disabled.
• Apply the normalized POSTGRES_SCHEMA search path to asyncpg startup connections so DDL targets the configured pgvector schema.
• Inspect the current-schema cmetadata column type before creating the GIN index.
• Create the GIN index only for JSONB columns and emit actionable warnings for legacy JSON, missing columns, and unsupported types.
• Document the startup flags and the dependency between JSONB migration and GIN index creation.
• Add unit coverage for flag behavior, schema-aware pool creation, and column-type guards.
• Add a PostgreSQL integration test covering custom-schema targeting, guarded migration, and GIN index creation.
• Preserve Peter Rothlaender's original feat: guard pgvector startup DDL #310 commits and add the independently reviewed fix as a separate commit.

Supersedes #310 because its organization-owned fork does not allow maintainer edits.

Change Type

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)

Testing

• Ran pytest --maxfail=1 --disable-warnings: 200 tests passed and 6 were skipped.
• Ran pytest -m integration --maxfail=3 --disable-warnings: 22 PostgreSQL integration tests passed.
• Ran Black 24.4.0 against the changed Python files.
• Compiled the changed modules with py_compile.

Test Configuration:

• Python 3.12
• Docker-backed PostgreSQL with pgvector

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in complex areas of my code
• I have made pertinent documentation changes
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective
• Local unit tests pass with my changes

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: d0ae8e6f64

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".