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>

3 files changed, 24 insertions, 2 deletions

diff --git a/src/sql/kernel/qsqlfield.cpp b/src/sql/kernel/qsqlfield.cpp
index a258d44df7..782ab0d71c 100644
--- a/src/sql/kernel/qsqlfield.cpp
+++ b/src/sql/kernel/qsqlfield.cpp
@@ -588,7 +588,6 @@ void QSqlField::setAutoValue(bool autoVal)
 
     \sa tableName()
 */
-
 void QSqlField::setTableName(const QString &table)
 {
     detach();
@@ -598,9 +597,12 @@ void QSqlField::setTableName(const QString &table)
 /*!
     Returns the tableName of the field.
 
+    \note When using the QPSQL driver, due to limitations in the libpq library,
+    the \c tableName() field is not populated in a QSqlField resulting
+    from a QSqlRecord obtained by QSqlQuery::record() of a forward-only query.
+
     \sa setTableName()
 */
-
 QString QSqlField::tableName() const
 {
     return d->table;
diff --git a/src/sql/kernel/qsqlquery.cpp b/src/sql/kernel/qsqlquery.cpp
index b89d20976f..628bfa1880 100644
--- a/src/sql/kernel/qsqlquery.cpp
+++ b/src/sql/kernel/qsqlquery.cpp
@@ -878,6 +878,14 @@ bool QSqlQuery::isForwardOnly() const
   \note Calling setForwardOnly after execution of the query will result
   in unexpected results at best, and crashes at worst.
 
+  \note To make sure the forward-only query completed successfully,
+  the application should check lastError() for an error not only after
+  executing the query, but also after navigating the query results.
+
+  \warning PostgreSQL: While navigating the query results in forward-only
+  mode, do not execute any other SQL command on the same database
+  connection. This will cause the query results to be lost.
+
   \sa isForwardOnly(), next(), seek(), QSqlResult::setForwardOnly()
 */
 void QSqlQuery::setForwardOnly(bool forward)
diff --git a/src/sql/kernel/qsqlresult.cpp b/src/sql/kernel/qsqlresult.cpp
index f79c1c71cd..cdb1379502 100644
--- a/src/sql/kernel/qsqlresult.cpp
+++ b/src/sql/kernel/qsqlresult.cpp
@@ -565,6 +565,14 @@ bool QSqlResult::isForwardOnly() const
     \note Calling setForwardOnly after execution of the query will result
     in unexpected results at best, and crashes at worst.
 
+    \note To make sure the forward-only query completed successfully,
+    the application should check lastError() for an error not only after
+    executing the query, but also after navigating the query results.
+
+    \warning PostgreSQL: While navigating the query results in forward-only
+    mode, do not execute any other SQL command on the same database
+    connection. This will cause the query results to be lost.
+
     \sa isForwardOnly(), fetchNext(), QSqlQuery::setForwardOnly()
 */
 void QSqlResult::setForwardOnly(bool forward)
@@ -1002,6 +1010,10 @@ bool QSqlResult::nextResult()
 
     \warning The handle can be NULL if the result was not executed yet.
 
+    \warning PostgreSQL: in forward-only mode, the handle of QSqlResult can change
+    after calling fetch(), fetchFirst(), fetchLast(), fetchNext(), fetchPrevious(),
+    nextResult().
+
     The handle returned here is database-dependent, you should query the type
     name of the variant before accessing it.