Improve get_affected_rows() documentation

Mention that the exact result of this method can't be relied upon for
the partially successful statements when using ODBC: some drivers
(including the widely used MS SQL native client) simply don't return
this information at all, while others (MySQL) just return wrong number
of rows.

Also remove the apparently obsolete note about this method not supported
in the Oracle backend as it does seem to implement it.

docs/beyond.md

@@ -16,8 +16,12 @@ It can be useful to know how many rows were affected by the last SQL statement,
 
 ---
 ##### Portability note:
-This method is currently not supported by the Oracle backend. It is however
-supported when using Oracle database via ODBC backend.
+This method behaviour in case of partially executed update, i.e. when some
+records were updated or inserted while some other have failed to be updated or
+inserted, depends on the exact backend and, in the case of ODBC backend, on the
+exact ODBC driver used. It can return `-1`, meaning that the number of rows is
+unknown, the number of rows actually updated or the total number of affected
+rows.
 ---
 
 ### Working with sequences
@@ -71,4 +75,4 @@ The above example retrieves the `rowid` ("something" that identifies the row in
 
 In order for any of the above to compile, you have to explicitly `#include` the appropriate backend's header file.
 
-Please see the header file related to the given backend to learn what low-level handles and descriptors are available.
+Please see the header file related to the given backend to learn what low-level handles and descriptors are available.

tests/common-tests.h

@@ -3891,8 +3891,15 @@ TEST_CASE_METHOD(common_tests, "Get affected rows", "[core][affected-rows]")
     sql << "select count(val) from soci_test", into(val);
     if(val != 0)
     {
-        // test the preserved 'number of rows
-        // affected' after a potential failure.
+        // Notice that some ODBC drivers don't return the number of updated
+        // rows at all in the case of partially executed statement like this
+        // one, while MySQL ODBC driver wrongly returns 2 affected rows even
+        // though only one was actually inserted.
+        //
+        // So we can't check for "get_affected_rows() == val" here, it would
+        // fail in too many cases -- just check that the backend doesn't lie to
+        // us about no rows being affected at all (even if it just honestly
+        // admits that it has no idea by returning -1).
         CHECK(st6.get_affected_rows() != 0);
     }
 }