feat: cache programmatic translations with rollback control - BED-9469

[zinic]

Description

Extends translation reuse to PostgreSQL programmatic queries and adds an immediate process-wide rollback control.

The profiled regression is dominated by FetchStartNodes and related programmatic queries, which bypassed the
raw-Cypher cache path. This layer reaches that hot path while preserving a fleet-wide, zero-critical-section rollback
switch if the optimized path needs to be disabled.

• Routes programmatic query-builder compilation through the shared cache.
• Uses literal-stripped query shapes so repeated ID-bound traversals can share a translation.
• Adds pg.SetOptimizedTranslation for atomically enabling or disabling both optimization and caching.
• Fixes relationship-property updates to bind against relationships rather than nodes.
• Adds PostgreSQL integration coverage for raw and programmatic caching, rollback behavior, and cached update bindings.
• Documents cache behavior, safety constraints, metrics, and rollback usage.

Resolves: BED-9469

Type of Change

• Chore (a change that does not modify the application functionality)
• Bug fix (a change that fixes an issue)
• New feature / enhancement (a change that adds new functionality)
• Refactor (no behaviour change)
• Test coverage
• Build / CI / tooling
• Documentation

Testing

• Unit tests added / updated
• Integration tests added / updated
• Full test suite run (make test_all with CONNECTION_STRING set)

Screenshots (if appropriate):

Driver Impact

• PostgreSQL driver (drivers/pg)
• Neo4j driver (drivers/neo4j)

Checklist

• Code is formatted
• All existing tests pass
• go.mod / go.sum are up to date if dependencies changed

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

Summary by CodeRabbit

• New Features

  • Added bounded PostgreSQL query-compilation caching with a default capacity of 256 entries.
  • Added configuration options for cache behavior through driver settings.
  • Added a process-wide switch to enable or disable optimized translation.
  • Cached queries now safely reuse compiled translations while rebinding current parameter values.

• Bug Fixes

  • Improved PostgreSQL handling for regular Cypher queries and prepared parameters.
  • Corrected relationship property updates and deletions.
  • Improved SQL comment formatting and protection of literal values.

• Documentation

  • Expanded Quick Start and PostgreSQL translation documentation with configuration, cache behavior, statistics, and rollback guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ab4efb95-6481-4cec-847a-abae7ddd0016

📥 Commits

Reviewing files that changed from the base of the PR and between 07b9c5e and 221a3e0.

📒 Files selected for processing (10)

• README.md
• docs/postgresql_translation.md
• drivers/pg/compiler.go
• drivers/pg/compiler_test.go
• drivers/pg/optimized_translation.go
• drivers/pg/optimized_translation_test.go
• drivers/pg/query.go
• drivers/pg/relationship.go
• drivers/pg/transaction.go
• integration/pgsql_translation_cache_test.go

Included review availability: 1 review is currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

Walkthrough

The PostgreSQL driver now prepares regular Cypher queries, caches optimized translation shapes, supports atomic optimization control, and rebinds request values on cache hits. Query wiring, relationship updates, documentation, unit tests, and PostgreSQL integration tests were updated.

Changes

PostgreSQL translation cache

Layer / File(s)	Summary
Prepared compilation and translation control drivers/pg/compiler.go, drivers/pg/optimized_translation.go	Regular queries use stable parameter names, copied ASTs, normalized SQL comments, and optimized or unoptimized translation paths. The process-wide optimization setting supports atomic reads and writes.
Query execution wiring and update targets drivers/pg/query.go, drivers/pg/transaction.go, drivers/pg/relationship.go	Live queries compile regular queries through the schema manager. Node and relationship accessors use the reduced constructor. Relationship updates target relationships for property changes and deletions.
Compiler, toggle, and integration validation drivers/pg/compiler_test.go, drivers/pg/optimized_translation_test.go, integration/pgsql_translation_cache_test.go	Tests cover cache keys, value rebinding, parameter types, bypass accounting, toggle concurrency, raw Cypher queries, node updates, and relationship updates.
Cache configuration and operational documentation README.md, docs/postgresql_translation.md	Documentation describes cache capacity, configuration, cache identity, statistics, invalidation, bypass behavior, concurrency, and shutdown handling.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 221a3

The PR is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant liveQuery
  participant schemaManager
  participant translationCache
  participant PostgreSQL
  Application->>liveQuery: execute regular Cypher query
  liveQuery->>schemaManager: prepare and compile query
  schemaManager->>translationCache: lookup translation shape
  translationCache-->>schemaManager: return cached or newly built shape
  schemaManager->>PostgreSQL: execute SQL with rebound values
  PostgreSQL-->>Application: return query result

Loading

Poem

A rabbit sorts the query keys,
And caches shapes with careful ease.
Values hop in, then rows return,
While toggle lights can fade or burn.
PostgreSQL thumps a steady beat.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.34% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 8 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: caching programmatic translations with rollback control. It is concise and related to the pull request objectives.
Description check	✅ Passed	The description follows the required template, explains the change and motivation, identifies BED-9469, documents the affected PostgreSQL driver, and lists testing and checklist items. The integration…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description follows the required template, explains the change and motivation, identifies BED-9469, documents the affected PostgreSQL driver, and lists testing and checklist items. The integration-test checkbox is not selected even though integration tests were added, but the description is otherwise complete.

Full details: Docstring Coverage

Explanation

Docstring coverage is 10.34% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 8 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/pg-translation-cache-programmatic

---

_{Comment @coderabbitai help to get the list of available commands.}

[urangel]

🙈

[zinic]

I know but at least I didn't bleed the atomic as a global exported variable :)