Expose MySQL connection state

site/doc/areas/mysql.txt

@@ -1,6 +1,7 @@
 MySQL Functions
 
 mysql_connect
+mysql_connected
 mysql_disconnect
 mysql_error
 mysql_escape

site/doc/pages/mysql_connect.txt

@@ -11,7 +11,7 @@ return value : pointer to the MySQL connection struct
 >mysql
 
 :content
-Establishes a connection to a MySQL server and returns a pointer to the connection struct.
+Establishes a connection to a MySQL server and returns a request-owned pointer to the connection struct. A failed connection also returns a wrapper so that `mysql_error()` can report the failure; use `mysql_connected()` before issuing optional work that requires a live server handle.
 
 This connection handle is then used with helpers such as `mysql_query()`, `mysql_error()`, and `mysql_disconnect()`.
 
@@ -19,5 +19,5 @@ MySQL handles are request-scoped framework resources. Repeated `mysql_connect()`
 
 :example
 MySQL* db = mysql_connect();
-print(db != 0 ? "connected to MySQL" : "no MySQL server reachable with these credentials", "\n");
+print(mysql_connected(db) ? "connected to MySQL" : "no MySQL server reachable with these credentials", "\n");
 if(db != 0) mysql_disconnect(db);

site/doc/pages/mysql_connected.txt

@@ -0,0 +1,20 @@
+:sig
+bool mysql_connected(MySQL* m)
+
+:params
+m : pointer returned by mysql_connect()
+return value : true only when the wrapper owns a live server connection
+
+:see
+>mysql
+
+:content
+Tests whether a MySQL wrapper has a usable server connection. `mysql_connect()` retains a failed wrapper so that callers can retrieve its diagnostic through `mysql_error()`; this helper distinguishes that state from a live handle without consuming the diagnostic.
+
+:example
+MySQL* db = mysql_connect();
+if(!mysql_connected(db))
+{
+    print("database unavailable: ", mysql_error(db), "\n");
+}
+if(db != 0) mysql_disconnect(db);

site/tests/services.uce

@@ -117,6 +117,11 @@ RENDER(Request& context)
 	);
 	MySQL unavailable_mysql;
 	unavailable_mysql.connect("127.0.0.1", "__uce_intentionally_missing__", "not-a-real-password");
+	mark(
+		"mysql_connected() distinguishes a failed connection wrapper",
+		!mysql_connected(&unavailable_mysql) ? "pass" : "fail",
+		mysql_connected(&unavailable_mysql) ? "unexpected live handle" : "no live handle"
+	);
 	unavailable_mysql.query("SELECT 1");
 	String unavailable_mysql_error = unavailable_mysql.error();
 	mark(