VLE cache: replace snapshot invalidation with per-graph

Replace AGE's snapshot-based VLE cache invalidation with per-graph
monotonic version counters in shared memory. The old code compared
PostgreSQL's global xmin/xmax/curcid, causing false cache invalidation
whenever ANY transaction ran on the server — even unrelated ones. This
forced a full hash table rebuild (~138s at SF3) on every VLE query in
any multi-connection environment.

The fix uses three invalidation paths with automatic detection:
- DSM (PG 17+): GetNamedDSMSegment — works without shared_preload_libraries
- SHMEM (PG <17): shmem_request/startup hooks — needs shared_preload_libraries;
  functions conditionally compiled via #if PG_VERSION_NUM < 170000
- SNAPSHOT: fallback to original behavior when shared memory unavailable

Version counter increment points:
- Cypher CREATE/DELETE/SET/MERGE via executor hooks
- SQL INSERT/UPDATE/DELETE via auto-installed per-table triggers
- TRUNCATE via ProcessUtility hook interception

New slot allocation in the version counter array uses pg_write_barrier()
before incrementing num_entries to ensure entry visibility on
weak memory-ordering architectures (e.g., ARM).

Additional optimizations:
- Thin entries: vertex/edge hash table entries store 6-byte TID instead of
  copied property Datum; properties fetched on demand via heap_fetch only
  during result construction. Reduces hash table memory by ~77%.
- Fast path in is_an_edge_match: skip property access for label-only VLE
  patterns (e.g., [:KNOWS*1..2]). When property constraints are present,
  edge properties are fetched once and cached locally to avoid duplicate
  heap access.
- Defensive elog(ERROR) on stale TID in lazy property fetch to catch
  invalidation logic bugs.
- Trigger install is conditional — checks if the trigger function exists
  in the catalog before attempting installation, ensuring backward
  compatibility with older extension SQL versions.

Test results (LDBC SNB benchmark, SF3 — 52.7M edges, 9.3M vertices):

  Production simulation (VLE with concurrent background transactions):
    Before: 177,188 ms avg per query (full rebuild every time)
    After:      15.7 ms avg per query (cache hit)
    Speedup: 11,299x

  Cold build time:
    Before: 186,275 ms
    After:  108,955 ms (41% faster — no datumCopy)

  LDBC IC1 warm (3-hop VLE, single session):
    Before: 219,385 ms
    After:  175,249 ms (20% faster — better cache utilization)

  Hash table memory (SF3):
    Before: ~9 GB
    After:  ~2.1 GB (77% reduction)

New regression tests in age_global_graph.sql verify:
- VLE cache invalidation after CREATE (path extends)
- VLE cache invalidation after DELETE (path shrinks)
- VLE cache invalidation after SET (property updated via lazy fetch)
- VLE edge property fetch via full path return (weight values in path)
- VLE edge property fetch via UNWIND + relationships() (individual weights)

Regression tests: 32/32 pass

Files changed (14):
  src/backend/age.c                        — shmem hook registration (PG <17)
  src/backend/catalog/ag_catalog.c         — TRUNCATE interception
  src/backend/commands/label_commands.c    — conditional trigger auto-install on label creation
  src/backend/executor/cypher_create.c     — increment_graph_version after CREATE
  src/backend/executor/cypher_delete.c     — increment_graph_version after DELETE
  src/backend/executor/cypher_merge.c      — increment_graph_version after MERGE
  src/backend/executor/cypher_set.c        — increment_graph_version after SET
  src/backend/utils/adt/age_global_graph.c — version counter, thin entries, trigger fn, lazy fetch
  src/backend/utils/adt/age_vle.c          — is_an_edge_match fast path, cached edge property fetch
  src/include/utils/age_global_graph.h     — conditional declarations
  sql/age_main.sql                         — trigger function registration for next-version SQL
  regress/sql/age_global_graph.sql         — VLE cache regression tests
  regress/expected/age_global_graph.out    — expected output for new tests
  age--1.7.0--y.y.y.sql                    — upgrade template: trigger function for existing installs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jrgemignani

age--1.7.0--y.y.y.sql

@@ -408,3 +408,13 @@ $function$;
 
 COMMENT ON FUNCTION ag_catalog.age_pg_upgrade_status() IS
 'Returns the current pg_upgrade readiness status of the AGE installation.';
+
+--
+-- VLE cache invalidation trigger function
+-- Installed on graph label tables to catch SQL-level mutations
+-- and increment the per-graph version counter for VLE cache invalidation.
+--
+CREATE FUNCTION ag_catalog.age_invalidate_graph_cache()
+    RETURNS trigger
+    LANGUAGE c
+AS 'MODULE_PATHNAME';

regress/expected/age_global_graph.out

@@ -413,6 +413,180 @@ NOTICE:  graph "ag_graph_3" has been dropped
 
 (1 row)
 
+-----------------------------------------------------------------------------------------------------------------------------
+--
+-- VLE cache invalidation tests
+--
+-- These tests verify that the graph version counter properly invalidates
+-- the VLE hash table cache when the graph is mutated, and that thin
+-- entry lazy property fetch returns correct data.
+--
+-- Setup: create a graph with a chain a->b->c->d
+SELECT * FROM create_graph('vle_cache_test');
+NOTICE:  graph "vle_cache_test" has been created
+ create_graph 
+--------------
+ 
+(1 row)
+
+SELECT * FROM cypher('vle_cache_test', $$
+  CREATE (a:Node {name: 'a'})-[:Edge]->(b:Node {name: 'b'})-[:Edge]->(c:Node {name: 'c'})-[:Edge]->(d:Node {name: 'd'})
+$$) AS (v agtype);
+ v 
+---
+(0 rows)
+
+-- VLE query: find all paths from a's neighbors (should find b, b->c, b->c->d)
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..3]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+ name 
+------
+ "b"
+ "c"
+ "d"
+(3 rows)
+
+-- Now add a new node e connected to d. This should invalidate the cache.
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (d:Node {name: 'd'})
+  CREATE (d)-[:Edge]->(:Node {name: 'e'})
+$$) AS (v agtype);
+ v 
+---
+(0 rows)
+
+-- VLE query again: should now also find e via a->b->c->d->e (4 hops won't reach,
+-- but d->e is 1 hop from d, and a->b->c->d->e would be 4 hops from a).
+-- Increase range to *1..4 to include e
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+ name 
+------
+ "b"
+ "c"
+ "d"
+ "e"
+(4 rows)
+
+-- Test cache invalidation on DELETE: remove node c and its edges
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (c:Node {name: 'c'})
+  DETACH DELETE c
+$$) AS (v agtype);
+ v 
+---
+(0 rows)
+
+-- VLE query: should only find b now (c is gone, so b->c path is broken)
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+ name 
+------
+ "b"
+(1 row)
+
+-- Test cache invalidation on SET: change b's name property
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (b:Node {name: 'b'})
+  SET b.name = 'b_modified'
+  RETURN b.name
+$$) AS (name agtype);
+     name     
+--------------
+ "b_modified"
+(1 row)
+
+-- VLE query: verify the updated property is returned via lazy fetch
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+     name     
+--------------
+ "b_modified"
+(1 row)
+
+-- Test VLE with edge properties (exercises thin entry edge property fetch)
+SELECT * FROM drop_graph('vle_cache_test', true);
+NOTICE:  drop cascades to 4 other objects
+DETAIL:  drop cascades to table vle_cache_test._ag_label_vertex
+drop cascades to table vle_cache_test._ag_label_edge
+drop cascades to table vle_cache_test."Node"
+drop cascades to table vle_cache_test."Edge"
+NOTICE:  graph "vle_cache_test" has been dropped
+ drop_graph 
+------------
+ 
+(1 row)
+
+SELECT * FROM create_graph('vle_cache_test2');
+NOTICE:  graph "vle_cache_test2" has been created
+ create_graph 
+--------------
+ 
+(1 row)
+
+SELECT * FROM cypher('vle_cache_test2', $$
+  CREATE (a:N {name: 'a'})-[:E {weight: 1}]->(b:N {name: 'b'})-[:E {weight: 2}]->(c:N {name: 'c'})
+$$) AS (v agtype);
+ v 
+---
+(0 rows)
+
+-- VLE path output to verify edge properties are fetched correctly via
+-- thin entry lazy fetch. Returning the full path forces build_path()
+-- to call get_edge_entry_properties() for each edge in the result.
+-- The output must contain the correct weight values (1 and 2).
+SELECT * FROM cypher('vle_cache_test2', $$
+  MATCH p=(a:N {name: 'a'})-[:E *1..2]->(n:N)
+  RETURN p
+  ORDER BY n.name
+$$) AS (p agtype);
+                                                                                                                                                                                                                                                        p                                                                                                                                                                                                                                                         
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ [{"id": 844424930131969, "label": "N", "properties": {"name": "a"}}::vertex, {"id": 1125899906842626, "label": "E", "end_id": 844424930131970, "start_id": 844424930131969, "properties": {"weight": 1}}::edge, {"id": 844424930131970, "label": "N", "properties": {"name": "b"}}::vertex]::path
+ [{"id": 844424930131969, "label": "N", "properties": {"name": "a"}}::vertex, {"id": 1125899906842626, "label": "E", "end_id": 844424930131970, "start_id": 844424930131969, "properties": {"weight": 1}}::edge, {"id": 844424930131970, "label": "N", "properties": {"name": "b"}}::vertex, {"id": 1125899906842625, "label": "E", "end_id": 844424930131971, "start_id": 844424930131970, "properties": {"weight": 2}}::edge, {"id": 844424930131971, "label": "N", "properties": {"name": "c"}}::vertex]::path
+(2 rows)
+
+-- VLE edge properties via UNWIND + relationships() to individually verify
+-- each edge's properties are correctly fetched from the heap via TID.
+SELECT * FROM cypher('vle_cache_test2', $$
+  MATCH p=(a:N {name: 'a'})-[:E *1..2]->(n:N)
+  WITH p, n
+  UNWIND relationships(p) AS e
+  RETURN n.name, e.weight
+  ORDER BY n.name, e.weight
+$$) AS (name agtype, weight agtype);
+ name | weight 
+------+--------
+ "b"  | 1
+ "c"  | 1
+ "c"  | 2
+(3 rows)
+
+-- Cleanup
+SELECT * FROM drop_graph('vle_cache_test2', true);
+NOTICE:  drop cascades to 4 other objects
+DETAIL:  drop cascades to table vle_cache_test2._ag_label_vertex
+drop cascades to table vle_cache_test2._ag_label_edge
+drop cascades to table vle_cache_test2."N"
+drop cascades to table vle_cache_test2."E"
+NOTICE:  graph "vle_cache_test2" has been dropped
+ drop_graph 
+------------
+ 
+(1 row)
+
 -----------------------------------------------------------------------------------------------------------------------------
 --
 -- End of tests

regress/sql/age_global_graph.sql

@@ -146,6 +146,103 @@ RESET client_min_messages;
 SELECT * FROM drop_graph('ag_graph_1', true);
 SELECT * FROM drop_graph('ag_graph_2', true);
 SELECT * FROM drop_graph('ag_graph_3', true);
+
+-----------------------------------------------------------------------------------------------------------------------------
+--
+-- VLE cache invalidation tests
+--
+-- These tests verify that the graph version counter properly invalidates
+-- the VLE hash table cache when the graph is mutated, and that thin
+-- entry lazy property fetch returns correct data.
+--
+
+-- Setup: create a graph with a chain a->b->c->d
+SELECT * FROM create_graph('vle_cache_test');
+
+SELECT * FROM cypher('vle_cache_test', $$
+  CREATE (a:Node {name: 'a'})-[:Edge]->(b:Node {name: 'b'})-[:Edge]->(c:Node {name: 'c'})-[:Edge]->(d:Node {name: 'd'})
+$$) AS (v agtype);
+
+-- VLE query: find all paths from a's neighbors (should find b, b->c, b->c->d)
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..3]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+
+-- Now add a new node e connected to d. This should invalidate the cache.
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (d:Node {name: 'd'})
+  CREATE (d)-[:Edge]->(:Node {name: 'e'})
+$$) AS (v agtype);
+
+-- VLE query again: should now also find e via a->b->c->d->e (4 hops won't reach,
+-- but d->e is 1 hop from d, and a->b->c->d->e would be 4 hops from a).
+-- Increase range to *1..4 to include e
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+
+-- Test cache invalidation on DELETE: remove node c and its edges
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (c:Node {name: 'c'})
+  DETACH DELETE c
+$$) AS (v agtype);
+
+-- VLE query: should only find b now (c is gone, so b->c path is broken)
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+
+-- Test cache invalidation on SET: change b's name property
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (b:Node {name: 'b'})
+  SET b.name = 'b_modified'
+  RETURN b.name
+$$) AS (name agtype);
+
+-- VLE query: verify the updated property is returned via lazy fetch
+SELECT * FROM cypher('vle_cache_test', $$
+  MATCH (a:Node {name: 'a'})-[:Edge*1..4]->(n:Node)
+  RETURN n.name
+  ORDER BY n.name
+$$) AS (name agtype);
+
+-- Test VLE with edge properties (exercises thin entry edge property fetch)
+SELECT * FROM drop_graph('vle_cache_test', true);
+SELECT * FROM create_graph('vle_cache_test2');
+
+SELECT * FROM cypher('vle_cache_test2', $$
+  CREATE (a:N {name: 'a'})-[:E {weight: 1}]->(b:N {name: 'b'})-[:E {weight: 2}]->(c:N {name: 'c'})
+$$) AS (v agtype);
+
+-- VLE path output to verify edge properties are fetched correctly via
+-- thin entry lazy fetch. Returning the full path forces build_path()
+-- to call get_edge_entry_properties() for each edge in the result.
+-- The output must contain the correct weight values (1 and 2).
+SELECT * FROM cypher('vle_cache_test2', $$
+  MATCH p=(a:N {name: 'a'})-[:E *1..2]->(n:N)
+  RETURN p
+  ORDER BY n.name
+$$) AS (p agtype);
+
+-- VLE edge properties via UNWIND + relationships() to individually verify
+-- each edge's properties are correctly fetched from the heap via TID.
+SELECT * FROM cypher('vle_cache_test2', $$
+  MATCH p=(a:N {name: 'a'})-[:E *1..2]->(n:N)
+  WITH p, n
+  UNWIND relationships(p) AS e
+  RETURN n.name, e.weight
+  ORDER BY n.name, e.weight
+$$) AS (name agtype, weight agtype);
+
+-- Cleanup
+SELECT * FROM drop_graph('vle_cache_test2', true);
+
 -----------------------------------------------------------------------------------------------------------------------------
 --
 -- End of tests

sql/age_main.sql

@@ -381,3 +381,14 @@ CREATE FUNCTION ag_catalog._extract_label_id(graphid)
     STABLE
 PARALLEL SAFE
 AS 'MODULE_PATHNAME';
+
+--
+-- VLE cache invalidation trigger function.
+-- Installed on graph label tables to catch SQL-level mutations
+-- (INSERT/UPDATE/DELETE/TRUNCATE) and increment the graph's
+-- version counter so VLE caches are properly invalidated.
+--
+CREATE FUNCTION ag_catalog.age_invalidate_graph_cache()
+    RETURNS trigger
+    LANGUAGE c
+AS 'MODULE_PATHNAME';

src/backend/age.c

@@ -22,6 +22,29 @@
 #include "optimizer/cypher_paths.h"
 #include "parser/cypher_analyze.h"
 #include "utils/ag_guc.h"
+#include "utils/age_global_graph.h"
+
+#if PG_VERSION_NUM < 170000
+#include "miscadmin.h"
+
+/* saved hook pointers for PG < 17 shmem path */
+static shmem_request_hook_type prev_shmem_request_hook = NULL;
+static shmem_startup_hook_type prev_shmem_startup_hook = NULL;
+
+static void age_shmem_request_hook(void)
+{
+    if (prev_shmem_request_hook)
+        prev_shmem_request_hook();
+    age_graph_version_shmem_request();
+}
+
+static void age_shmem_startup_hook(void)
+{
+    if (prev_shmem_startup_hook)
+        prev_shmem_startup_hook();
+    age_graph_version_shmem_startup();
+}
+#endif /* PG_VERSION_NUM < 170000 */
 
 PG_MODULE_MAGIC;
 
@@ -35,6 +58,15 @@ void _PG_init(void)
     process_utility_hook_init();
     post_parse_analyze_init();
     define_config_params();
+
+#if PG_VERSION_NUM < 170000
+    /* Register shared memory hooks for graph version tracking.
+     * On PG 17+, DSM is used instead (no hooks needed). */
+    prev_shmem_request_hook = shmem_request_hook;
+    shmem_request_hook = age_shmem_request_hook;
+    prev_shmem_startup_hook = shmem_startup_hook;
+    shmem_startup_hook = age_shmem_startup_hook;
+#endif
 }
 
 void _PG_fini(void);