Contents

Heavy SQL Tests

Sticky note for contributors and agents: the maintained inventory and layer selection guide lives in SQL Tests.

Use these scripts when cargo pgrx test is not representative enough: client SQLSTATEs, ACL/RLS role boundaries, crash recovery, backup/restore, package validation, Docker, pg_upgrade, memory evidence, playground query stability, or mixed concurrency.

gql_isolation_matrix.sh is the two-session backend-local mapped-write visibility gate. It applies node and relationship CREATE, SET, REMOVE, relationship DELETE, DETACH DELETE, and MERGE under READ COMMITTED, REPEATABLE READ, and SERIALIZABLE. Source rows and graph results must agree inside the writer, inside the concurrent reader snapshot, and after commit. gql_merge_race.sh and gql_relationship_race.sh use lock-visible handshakes for deterministic same-key outcomes. gql_write_recheck_race.sh covers stale predicate and tenant outcomes with exact SQLSTATE and graph-delta assertions. With PERSIST_ON_BUILD=on, the isolation script retains its durable new-node identity and repeated-build profile. Durable incremental node deletion in a graph with standalone relationship mappings remains fail-closed with rebuild guidance, so that mode does not claim the full write-family matrix.

run_gql_write_matrix.sh runs the full and persisted isolation profiles plus the deterministic MERGE, relationship, and stale-write race gates against each requested supported PostgreSQL major. It creates one temporary PostgreSQL cluster per major and removes it on exit. Set PG_VERSIONS to a space-separated subset or provide PG_CONFIG_<major> for a nonstandard installation path.

Most scripts expect a disposable database and accept variables such as PG_VERSION_FEATURE=pg17, PG_CONFIG, and DBNAME. Crash scripts run through scripts/with_disposable_postgres.sh; PostgreSQL binary upgrades run through run_pg_upgrade_matrix.sh, whose lower-level validator requires a per-run safety sentinel.

run_postgres_process_sanitizer.sh creates its own disposable cluster and runs the postmaster plus child processes under Valgrind. It covers persisted mmap build/load/traversal/reload, corruption rejection, build-job execution, transaction callbacks, and guarded error unwinding. The gate fails if any process log reports an unsuppressed error. Use RUN_VALGRIND=1 with run_memory_sanitizers.sh, or set RUN_POSTGRES_SANITIZER=1 on run_pg_matrix_docker.sh for the containerized release environment. Direct execution installs pgGraph into the PostgreSQL installation selected by PG_CONFIG; prefer the containerized command when that installation must not be changed.

run_durable_projection_matrix.sh creates one disposable cluster per requested PostgreSQL major and runs the cross-backend durable lifecycle plus the complete publication/writer-lock regression. Set RUN_DURABLE_PROJECTION_MATRIX=1 on run_pg_matrix_docker.sh to run it in the maintained PostgreSQL 14-18 image. Each child profile is bounded by PROFILE_TIMEOUT_SECONDS (600 seconds by default), and cluster shutdown is verified before its temporary files are removed.

For build memory evidence, start with measure_build_rss.sh. For opt-in stress profiles that cover baseline build, small SPI/spool batches, repeated persisted rebuilds, and low-memory rebuilds, use build_memory_stress.sh or set RUN_BUILD_MEMORY_STRESS=1 on run_release_gate.sh. Use measure_runtime_resources.sh for repeated load plus representative query, hydration, sync-ingest, compaction, and analytics resource evidence. It samples backend RSS everywhere and PSS when Linux exposes smaps_rollup, verifies the stable PG007 breaker, and enforces positive MAX_RSS_MB/MAX_PSS_MB thresholds (1024 MiB by default). Missing PID, RSS, or Linux PSS samples fail the profile. Successful representative queries use an explicit QUERY_MEMORY_MB budget (256 MiB by default), while the separate work-limit case must still return PG007. The default evidence shape is 10,000 nodes, 9,999 edges, and two 500-row sync cycles; telemetry assertions verify the reported operation, peak phase, work, row, and disk counters. The full release gate runs this profile by default; set RUN_RUNTIME_RESOURCES=0 only when intentionally running a narrower gate.