test(io): add pool flush metric coverage

Added IO tests for pgrst_db_pool_flushes_total to validate:
- single flush increment on schema cache reload
- no extra flushes during schema cache retry loops
- metric exposure in /metrics output

Also hardened wait_until_status_code by initializing response before retrying, preventing UnboundLocalError when all attempts raise connection exceptions.

Author: mkleczek

test/io/postgrest.py

@@ -187,6 +187,7 @@ def wait_until_exit(postgrest):
 def wait_until_status_code(url, max_seconds, status_code):
     "Wait for the given HTTP endpoint to return a status code"
     session = requests_unixsocket.Session()
+    response = None
 
     for _ in range(max_seconds * 10):
         try:

test/io/test_io.py

@@ -18,6 +18,7 @@
     sleep_until_postgrest_full_reload,
     sleep_until_postgrest_scache_reload,
     wait_until_exit,
+    wait_until_status_code,
 )
 
 
@@ -105,6 +106,88 @@ def sleep():
         t.join()
 
 
+def test_pool_flushes_metric(defaultenv):
+    "Should increase pool flushes metric when the pool is flushed"
+
+    with run(env=defaultenv, port=freeport()) as postgrest:
+        response = postgrest.admin.get("/metrics")
+        assert response.status_code == 200
+        before = float(
+            re.search(r"pgrst_db_pool_flushes_total ([0-9.e+-]+)", response.text).group(
+                1
+            )
+        )
+
+        postgrest.process.send_signal(signal.SIGUSR1)
+        sleep_until_postgrest_scache_reload()
+
+        response = postgrest.admin.get("/metrics")
+        assert response.status_code == 200
+        after = float(
+            re.search(r"pgrst_db_pool_flushes_total ([0-9.e+-]+)", response.text).group(
+                1
+            )
+        )
+        assert after == before + 1
+
+
+def test_pool_flushes_metric_with_schema_cache_retries(defaultenv, metapostgrest):
+    "Should flush the pool exactly once even when schema cache reload retries"
+
+    role = "timeout_authenticator"
+    app_name = "pool-flush-retry"
+    env = {
+        **defaultenv,
+        "PGUSER": role,
+        "PGAPPNAME": app_name,
+        "PGRST_INTERNAL_SCHEMA_CACHE_QUERY_SLEEP": "50",
+    }
+
+    with run(env=env, port=freeport()) as postgrest:
+        response = postgrest.admin.get("/metrics")
+        assert response.status_code == 200
+        before = float(
+            re.search(r"pgrst_db_pool_flushes_total ([0-9.e+-]+)", response.text).group(
+                1
+            )
+        )
+
+        try:
+            # Force schema cache reload failures to trigger retries.
+            set_statement_timeout(metapostgrest, role, 20)
+            postgrest.process.send_signal(signal.SIGUSR1)
+
+            postgrest.wait_until_scache_starts_loading(max_seconds=2)
+
+            # Give retry loop time to run and verify it doesn't flush the pool.
+            time.sleep(1)
+
+            response = postgrest.admin.get("/metrics")
+            assert response.status_code == 200
+            during_retries = float(
+                re.search(
+                    r"pgrst_db_pool_flushes_total ([0-9.e+-]+)", response.text
+                ).group(1)
+            )
+            assert during_retries == before
+
+            reset_statement_timeout(metapostgrest, role)
+            # Ensure next retry establishes fresh sessions with the reset timeout.
+            metapostgrest.session.get(f"/rpc/terminate_pgrst?appname={app_name}")
+            wait_until_status_code(postgrest.admin.baseurl + "/ready", 12, 200)
+        finally:
+            reset_statement_timeout(metapostgrest, role)
+
+        response = postgrest.admin.get("/metrics")
+        assert response.status_code == 200
+        after = float(
+            re.search(r"pgrst_db_pool_flushes_total ([0-9.e+-]+)", response.text).group(
+                1
+            )
+        )
+        assert after == before + 1
+
+
 def test_random_port_bound(defaultenv):
     "PostgREST should bind to a random port when PGRST_SERVER_PORT is 0."
 
@@ -1458,6 +1541,7 @@ def test_admin_metrics(defaultenv):
         assert "pgrst_db_pool_waiting" in response.text
         assert "pgrst_db_pool_available" in response.text
         assert "pgrst_db_pool_timeouts_total" in response.text
+        assert "pgrst_db_pool_flushes_total" in response.text
 
 
 def test_schema_cache_startup_load_with_in_db_config(defaultenv, metapostgrest):