From 0f80bb1811badb281d2df1ffdd491015d6b3a36a Mon Sep 17 00:00:00 2001
From: Christian Ehrlicher <ch.ehrlicher@gmx.de>
Date: Tue, 5 Nov 2024 19:14:33 +0100
Subject: [PATCH] SQL/Doc: add notes about QDateTime handling

Add a note on how timestamps are handled for the different database
drivers.

Task-number: QTBUG-130118
Change-Id: I1bad480fa18b5b719870635db1444c8db8c7d966
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
(cherry picked from commit d63f14473345cdb83c2da00a19892f57e661a5d0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 src/sql/doc/src/sql-driver.qdoc | 43 +++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/src/sql/doc/src/sql-driver.qdoc b/src/sql/doc/src/sql-driver.qdoc
index 712b775fe9d..c25f31b0579 100644
--- a/src/sql/doc/src/sql-driver.qdoc
+++ b/src/sql/doc/src/sql-driver.qdoc
@@ -122,6 +122,13 @@
     library binary parity and exact matching with MySQL APIs and commands.
     Therefore the plugin for MySQL and MariaDB are combined into one Qt plugin.
 
+    \section3 Timestamp Support
+    Since Qt 6.8, QDateTime values are converted to UTC before insertion and
+    back from UTC during retrieval. To make this work, the driver sets
+    the connection time zone to UTC during open() (SET time_zone = '+00:00').
+    Since MySQL does not store any timezone information, this information is
+    lost and all retrieved QDateTime values are UTC.
+
     \section3 QMYSQL Stored Procedure Support
 
     MySQL has stored procedure support at the SQL level, but no
@@ -444,6 +451,12 @@
     Some drivers do not support scrollable cursors. In that case, only
     queries in \l QSqlQuery::setForwardOnly() mode can be used successfully.
 
+    \section3 Timestamp Support
+    ODBC is using TIMESTAMP_STRUCT which has no information about any
+    timezone or similar. Due to this, the QDateTime is used without honoring
+    the timezone at all.
+    \note: This might change in the future.
+
     \section3 ODBC Stored Procedure Support
 
     With Microsoft SQL Server the result set returned by a stored
@@ -542,6 +555,14 @@
 
     For more information about PostgreSQL visit \l http://www.postgresql.org.
 
+    \section3 Timestamp Support
+    Since Qt 6.8, QDateTime values are converted to UTC before insertion
+    and back from UTC during retrieval. To make this work, the driver sets
+    the connection time zone to UTC during open() (SET TIME ZONE 'UTC').
+    Although PostgreSQL has the `timestamptz` column type, the timezone
+    used during insertion is not preserved and therefore all retrieved
+    QDateTime values are UTC.
+
     \section3 QPSQL Unicode Support
 
     The QPSQL driver automatically detects whether the PostgreSQL
@@ -716,6 +737,12 @@
 
     You can find information about SQLite on \l{http://www.sqlite.org}.
 
+    \section3 Timestamp Support
+    SQLite does not have a special timestamp column type. A QDateTime is
+    stored as string, formatted in Qt::ISODateWithMs and therefore the
+    QDateTime timezone information is preserved during insertion and
+    select.
+
     \section3 Connection options
     The Qt SQLite plugin honors the following connection options:
     \table
@@ -836,6 +863,12 @@
     National Character Varying (NVARCHAR), or National Character Large Object (NCLOB) must be used.
     For more information about Mimer SQL and unicode, see \l{https://developer.mimer.com/features/multilingual-support}
 
+    \section3 Timestamp Support
+    MimerSQL does not know anything about timezones and QDateTime
+    is used without honoring the timezone at all.
+
+    \note: This might change in the future.
+
     \section3 QMIMER Stored Procedure Support
 
     Mimer SQL have stored procedures according to the SQL standard (PSM) and
@@ -877,6 +910,16 @@
     database file, no matter whether it is stored locally or on another
     server.
 
+    \section3 Timestamp Support
+    Interbase stores timestamps in UTC without any timezone information.
+    Due to this, the QDateTime is used without honoring the timezone at all.
+
+    Since Firebird 4.0, the database supports timestamps with timezones. The
+    timezone information is stored separately to the timestamp so it can
+    be properly retrieved later on. See the Firebird
+    \l {https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref40/fblangref40-datatypes-datetime.html}
+    {documentation} for more information about timestamp handling.
+
     \section3 Connection options
     The Qt Borland InterBase plugin honors the following connection options:
     \table