Deliver a tested Protect/EQL v2 to Stack/EQL v3 Postgres procedure #1603

Parent

#1540

What to build

A Protect user with existing EQL (Encrypt Query Language) v2 Postgres columns can follow the v2-to-v3 guide through preparation, conversion, verification and application cutover. Deliver the executable before/after example, live tests and guide procedure together, using the existing compatibility suite boundary. Follow the priority amendment in ADR PR #1575. This slice does not depend on the agent harness.

Acceptance criteria

• The starting database contains real Protect.js 10.2.1 writes to EQL v2 columns; legacy reads and queries pass before migration. Already-v3 columns populated by cross-store copying are not used as the starting proof.
• Text equality, integer-valued number equality and storage-only text have explicit legacy declarations, supported ranges, target domains and query mappings, each proven end to end.
• The documented procedure installs v3 alongside the legacy setup, preserves source columns, populates separate target columns, creates required indexes and switches the application under a write-maintenance window.
• Tests establish exactly which ciphertext/search-term bytes survive conversion. Any required re-encryption is stated per mapping and tested; a cast or changed version field is never assumed sufficient.
• Row counts, decrypted values, legacy-equivalent query results, fresh writes and required index definitions/use are verified against a disposable real Postgres database with real encryption.
• Unsupported capabilities and customer dependencies are detected before mutation; tests show refusal preserves source data. The guide inventories boolean, downcase, bigint, JSON, dates, fractional numbers, grouped fields, lock contexts, range/order and text-search limitations.
• The example demonstrates rollback before writes resume and documents that target-only writes require reconciliation before rollback. Source columns are not automatically destroyed at cutover.
• The guide contains preparation, commands, expected results, cutover, rollback and exclusions, with accurate live-test citations and passing credentialed CI. The citation gate covers both store procedures.
• Shared preparation and navigation agree with Complete the tested Protect-to-Stack v3 DynamoDB guide #1604 when both land. No v4 codec, package or SDK is required.

Blocked by

None — can start using PR #1519's compatibility helpers and guide as the base. PR #1519 must be integrated before this work merges. #1604 is a coordination dependency for final guide consistency, not a blocker to starting this slice.

Delivery status — 2026-11-11

The executable PostgreSQL procedure and tests landed in merged #1519. The nine-test guide suite passed against PostgreSQL 18 in current downstream CI (Test JS run 42943850538). Acceptance reconciliation is complete. Docs-site publication remains tracked in #1540/#1604; harness #1605 is a separate deliverable.

Acceptance verification — 2026-11-11

All repository-deliverable criteria were checked against merged #1519, unchanged in main at 574bdab635fe5056336ceed0249d0b91f0252ccb. Test JS run 42943850538 passed 40 compatibility tests, 22 crossover/upgrade/example tests and nine PostgreSQL 18 tests. The lightweight citation gate was rerun and passed all 57 tests.

The PostgreSQL example/tests cover actual Protect-written v2 data, supported mappings, preserved sources, fresh writes, planner index use, refusal before mutation and rollback limits. Repository delivery is complete. This closure does not claim docs-site publication or real-agent guide-usability evidence; those remain tracked in #1540 and #1604.