From db646d8aefdd18ef61a566b224313175848276a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20Ha=C5=82as?= <piotr.h@decodo.com>
Date: Mon, 30 Mar 2026 10:58:52 +0200
Subject: [PATCH] Add Database monitoring methods (getMainThreadBusyness,
 getClientStatus)

Adds getMainThreadBusyness() for network thread utilization monitoring
and getClientStatus() for JSON-formatted client diagnostics info.
Useful for observability and health checks.

Closes #7
---
 src/Database.php                             | 18 ++++++++
 src/NativeClient.php                         |  2 +
 tests/Integration/DatabaseMonitoringTest.php | 45 ++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 tests/Integration/DatabaseMonitoringTest.php

diff --git a/src/Database.php b/src/Database.php
index ddd4da5..4265c64 100644
--- a/src/Database.php
+++ b/src/Database.php
@@ -261,6 +261,24 @@ public function getRangeSplitPoints(string $begin, string $end, int $chunkSize):
         );
     }
 
+    public function getMainThreadBusyness(): float
+    {
+        /** @var float $busyness */
+        $busyness = $this->client->fdb->fdb_database_get_main_thread_busyness($this->dpointer);
+
+        return $busyness;
+    }
+
+    public function getClientStatus(): string
+    {
+        $future = new Future\FutureKey(
+            $this->client->fdb->fdb_database_get_client_status($this->dpointer),
+            $this->client,
+        );
+
+        return $future->await();
+    }
+
     public function options(): DatabaseOptions
     {
         return new DatabaseOptions($this);
diff --git a/src/NativeClient.php b/src/NativeClient.php
index f336006..260bda0 100644
--- a/src/NativeClient.php
+++ b/src/NativeClient.php
@@ -61,6 +61,8 @@ final class NativeClient
             const char* connection_string, FDBDatabase** out_database
         );
         void fdb_database_destroy(FDBDatabase* d);
+        double fdb_database_get_main_thread_busyness(FDBDatabase* d);
+        FDBFuture* fdb_database_get_client_status(FDBDatabase* d);
         fdb_error_t fdb_database_set_option(FDBDatabase* d, int option, const void* value, int value_length);
         fdb_error_t fdb_database_create_transaction(FDBDatabase* d, FDBTransaction** out_transaction);
         fdb_error_t fdb_database_open_tenant(
diff --git a/tests/Integration/DatabaseMonitoringTest.php b/tests/Integration/DatabaseMonitoringTest.php
new file mode 100644
index 0000000..c50be73
--- /dev/null
+++ b/tests/Integration/DatabaseMonitoringTest.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CrazyGoat\FoundationDB\Tests\Integration;
+
+use CrazyGoat\FoundationDB\Database;
+use CrazyGoat\FoundationDB\FoundationDB;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class DatabaseMonitoringTest extends TestCase
+{
+    private static bool $initialized = false;
+
+    private static Database $db;
+
+    protected function setUp(): void
+    {
+        if (!self::$initialized) {
+            FoundationDB::reset();
+            FoundationDB::apiVersion(730);
+            self::$db = FoundationDB::open();
+            self::$initialized = true;
+        }
+    }
+
+    #[Test]
+    public function getMainThreadBusynessReturnsNonNegativeValue(): void
+    {
+        $busyness = self::$db->getMainThreadBusyness();
+
+        self::assertGreaterThanOrEqual(0.0, $busyness);
+    }
+
+    #[Test]
+    public function getClientStatusReturnsValidJson(): void
+    {
+        $status = self::$db->getClientStatus();
+
+        self::assertNotEmpty($status);
+        $decoded = json_decode($status, true);
+        self::assertIsArray($decoded);
+    }
+}