QPSQL: Add support for forward-only queries

With this change, it is possible to significantly reduce memory
consumption of applications that fetch large result sets from databases.
The implementation is based on the new functionality called "single-row
mode" that was introduced in PostgreSQL version 9.2:

https://www.postgresql.org/docs/9.2/static/libpq-async.html

It also uses asynchronous commands PQsendQuery(), PQgetResult():

https://www.postgresql.org/docs/9.2/static/libpq-single-row-mode.html

[ChangeLog][QtSql][QPSQL] Added support for forward-only queries (requires
libpq version 9.2 or later)

[Important Behavior Changes] The QPSQL driver now supports forward-only
queries. To use this feature, you must build QPSQL plugin with PostreSQL
client library version 9.2 or later. See the Qt SQL documentation for
more information about QPSQL limitations of forward-only queries
(sql-driver.html).

[Important Behavior Changes] If you build the QPSQL plugin with PostgreSQL
version 9.2 or later, then you must distribute your application with
libpq version 9.2 or later. Otherwise, the QPSQL plugin will fail to load.

Task-number: QTBUG-63714
Change-Id: I15db8c8fd664f2a1f719329f5d113511fa69010c
Reviewed-by: Andy Shaw <andy.shaw@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

2 files changed, 44 insertions, 0 deletions

diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.cpp b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp
index 7983386642..e7dfbd90d5 100644
--- a/src/sql/doc/snippets/code/doc_src_sql-driver.cpp
+++ b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp
@@ -95,3 +95,35 @@ QSqlDatabase: available drivers: QMYSQL
 //! [34]
 column.contains(QRegularExpression("pattern"));
 //! [34]
+
+
+//! [36]
+QSqlQuery query(db);
+query.setForwardOnly(true);
+query.exec("SELECT * FROM table");
+while (query.next()) {
+    // Handle changes in every iteration of the loop
+    QVariant v = query.result()->handle();
+    if (qstrcmp(v.typeName(), "PGresult*") == 0) {
+        PGresult *handle = *static_cast<PGresult **>(v.data());
+        if (handle != 0) {
+            // Do something...
+        }
+    }
+}
+//! [36]
+
+
+//! [37]
+int value;
+QSqlQuery query1(db);
+query1.setForwardOnly(true);
+query1.exec("select * FROM table1");
+while (query1.next()) {
+    value = query1.value(0).toInt();
+    if (value == 1) {
+        QSqlQuery query2(db);
+        query2.exec("update table2 set col=2");  // WRONG: This will discard all results of
+    }                                            // query1, and cause the loop to quit
+}
+//! [37]
diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
index 04ea30915d..d127bdf8a5 100644
--- a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
+++ b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
@@ -225,3 +225,15 @@ cd $QTDIR/qtbase/src/plugins/sqldrivers
 qmake -- OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib "OCI_LIBS=-Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10"
 make sub-oci
 //! [33]
+
+
+//! [35]
+QSqlDatabase: QPSQL driver not loaded
+QSqlDatabase: available drivers: QSQLITE QMYSQL QMYSQL3 QODBC QODBC3 QPSQL QPSQL7
+Could not create database object
+//! [35]
+
+
+//! [38]
+QPSQLDriver::getResult: Query results lost - probably discarded on executing another SQL query.
+//! [38]