Architect, Agent, Gatekeeper: Upgrading PHP 8.5 and PostgreSQL 18 with a Two-Tier AI Workflow

Major infrastructure upgrades often stall due to subtle friction: extension compilation breakages, Composer platform mismatches, storage directory shifts, and breaking CLI tool gates.

While autonomous agents running open loops are getting all the attention lately, I’ve found that a paired AI workflow offers far greater control and velocity. By using a conversational LLM (Gemini) as a strategic architect and "prompt compiler," I can reason through upstream changelogs and design precise, context-rich execution directives. The workspace agent in Antigravity IDE then takes those prompts and executes the heavy lifting—auditing ASTs, building containers, and orchestrating test stacks—almost always in a single shot.

Here is how this division of labor turned two major upgrades on an AI-integrated Drupal 11 stack—moving to PHP 8.5 and leaping from PostgreSQL 16 to 18—into rapid, rollback-safe operations completed in minutes.

1. The Division of Labor & The Engineer-in-the-Loop

The workflow succeeds by maintaining strict boundaries between strategic reasoning, deterministic execution, and human approval:

[ Engineer ] <---> [ Gemini (Strategic Architect) ]
     |                      |
     |                      v (High-intent prompts & logic)
     +------------> [ Antigravity IDE (Workspace Agent) ]
                            |
                            v (Executes commands, checks code, writes diffs)
                    [ Local Stacks / Git / Docker Swarm ]

• Gemini (Strategic Architect): Analyzes upstream release notes, models edge cases (SemVer traps, storage breaking changes), and drafts dense execution prompts targeting root causes rather than mechanical syntax.
• Antigravity IDE (Workspace Agent): Operates directly inside the repo to run static audits, spawn ephemeral test containers, refactor Dockerfiles and Compose manifests, and execute CLI assertions.
• The Engineer (System Gatekeeper): Retains final deployment authority—reviewing diffs, verifying canary environments, testing SSO redirects, and pulling the trigger on production cutovers.

2. Case Study: Auditing and Shipping PHP 8.5

The application runtime was pinned to php:8.4-fpm-bookworm. Drupal Core 11.4.8 inherited PHP 8.5 compatibility upstream, but moving runtimes still introduced hidden friction points:

• Pre-Flight Audit: Antigravity IDE inspected the ASTs and spawned throwaway containers to run composer check-platform-reqs and dry-run updates against 114 locked packages. It identified zero PECL blockers, relying exclusively on core extensions (gd, zip, pdo_pgsql, opcache).
• The Base Image Gotcha: Image compilation halted on RUN docker-php-ext-install ... opcache. Gemini diagnosed the log immediately: the official php:8.5-fpm-bookworm image now compiles Zend OPcache statically into the binary. Antigravity updated the Dockerfile on the fly to drop the redundant step.
• Dependency Governance: Because Renovate treats PHP 8.4 → 8.5 as a minor update, Gemini restructured renovate.json to route all runtime bumps to the Dependency Dashboard for mandatory human approval. Antigravity then aligned the platform schema in composer.json and refreshed the lockfile hash using --ignore-platform-reqs.

3. Case Study: Leaping from PostgreSQL 16 to 18

Skipping two major database versions in a stateful stack managing 1,536-dimensional vector embeddings (pgvector and HNSW indexing for RAG search) carries high rollback anxiety. We chose a logical dump/restore over a risky in-place binary upgrade, decoupling storage from schema migration.

• Storage Layout Breaking Change: PostgreSQL 18 changed the upstream image volume to VOLUME /var/lib/postgresql with versioned subdirectories. Antigravity initially attempted to force PGDATA via environment variables, but Gemini steered us to adopt the official upstream mount point (db_data_v18:/var/lib/postgresql), preventing orphaned volume leaks and data disappearance on recreation.
• The Extension Lifecycle Trap: Drupal's restore routine executes drush sql:drop, which wipes the public schema and custom types. Restoring the SQL dump immediately crashed because type vector was dropped. Gemini drafted the fix, and Antigravity patched restore.sh to inject CREATE EXTENSION IF NOT EXISTS vector; prior to data ingest.
• Client Tooling Parity: While PHP PDO connects across versions, pg_dump aborts on server-version mismatches. Antigravity updated the multi-stage Dockerfile to pull postgresql-client-18, ensuring automated backup routines (drush archive:dump) wouldn't break post-migration.
• Verification & Cutover: Antigravity deployed an ephemeral test stack (drupal-pg18-test), restored 44,500 statements, rebuilt the RAG search index, and verified healthchecks. With the original PG16 volume left completely untouched as an instant fallback, production cutover took under three minutes.

Operational Takeaway

What typically represents a multi-day slog—reading migration guides, debugging base image C-extensions, synchronizing dependency managers, and validating stateful database schemas—was executed cleanly in a single session. Treating an LLM chat as an architectural compiler provided the deep upfront diligence, while the IDE agent delivered rapid, deterministic execution—leaving the engineer firmly in control of production integrity.