Add a note about the support and the behavior of the "datetimetz" type

docs/en/reference/known-vendor-issues.rst

@@ -70,8 +70,20 @@ MySQL
 DateTimeTz
 ~~~~~~~~~~
 
-MySQL does not support saving timezones or offsets. The DateTimeTz
-type therefore behaves like the DateTime type.
+Prior to version 8.0.19, MySQL does not support saving timezones or offsets. The DateTimeTz type therefore
+behaves like the DateTime type on previous versions.
+Starting from version `8.0.19 and later <https://dev.mysql.com/doc/refman/8.0/en/date-and-time-literals.html#date-and-time-string-numeric-literals>`_,
+timezone offsets are supported. MySQL converts the time zone offset to UTC for storage, and back from UTC to the current
+(SYSTEM, SESSION, etc) time zone for retrieval.
+
+MariaDB
+-------
+
+DateTimeTz
+~~~~~~~~~~
+
+MariaDB does not support saving timezone offsets. The DateTimeTz type therefore behaves like the DateTime
+type.
 
 Sqlite
 ------
@@ -86,7 +98,7 @@ breaks the SERIALIZABLE transaction isolation property that SQLite supposedly
 has.
 
 DateTime
-~~~~~~~~~~
+~~~~~~~~
 
 Unlike most database management systems, Sqlite does not convert supplied
 datetime strings to an internal storage format before storage. Instead, Sqlite
@@ -104,8 +116,8 @@ when trying to convert database values to ``\DateTime`` objects using
 DateTimeTz
 ~~~~~~~~~~
 
-Sqlite does not support saving timezones or offsets. The DateTimeTz
-type therefore behaves like the DateTime type.
+Sqlite support saving timezone offsets, but this feature is not yet implemented in DBAL.
+The DateTimeTz type therefore behaves like the DateTime type.
 
 Reverse engineering primary key order
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -121,10 +133,8 @@ IBM DB2
 DateTimeTz
 ~~~~~~~~~~
 
-DB2 does not save the actual Timezone Name but UTC-Offsets. The
-difference is subtle but can be potentially very nasty. Derick
-Rethans explains it very well
-`in a blog post of his <http://derickrethans.nl/storing-date-time-in-database.html>`_.
+DB2 does not support saving timezone offsets. The DateTimeTz type therefore behaves like the DateTime
+type.
 
 Oracle
 ------

docs/en/reference/types.rst

@@ -301,6 +301,15 @@ information, you should consider using this type.
 Values retrieved from the database are always converted to PHP's ``\DateTime`` object
 or ``null`` if no data is present.
 
+.. note::
+
+    This type is not supported by all the vendor platforms or by all of their versions. Depending on
+    these variants, the databases that support this type may return the persisted date and time in a
+    different timezone than the one used during the ``INSERT`` or the ``UPDATE`` operation. This means
+    that if you persist a value like `1986-22-03 19:45:30-03:00`, you could have `1986-22-03 22:45:30-00:00`
+    as the result of a ``SELECT`` operation for that record. In these cases, the timezone offset present
+    in the result is usually UTC or the one configured as default in the database server.
+
 datetimetz_immutable
 ^^^^^^^^^^^^^^^^^^^^
 

src/Types/DateTimeTzType.php

@@ -7,18 +7,19 @@
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 
 /**
- * DateTime type saving additional timezone information.
+ * DateTime type accepting additional information about timezone offsets.
  *
  * Caution: Databases are not necessarily experts at storing timezone related
- * data of dates. First, of all the supported vendors only PostgreSQL and Oracle
- * support storing Timezone data. But those two don't save the actual timezone
- * attached to a DateTime instance (for example "Europe/Berlin" or "America/Montreal")
- * but the current offset of them related to UTC. That means depending on daylight saving times
- * or not you may get different offsets.
+ * data of dates. First, of not all the supported vendors support storing Timezone data, and some of
+ * them only use the offset to calculate the timestamp in its default timezone (usually UTC) and persist
+ * the value without the offset information. They even don't save the actual timezone names attached
+ * to a DateTime instance (for example "Europe/Berlin" or "America/Montreal") but the current offset
+ * of them related to UTC. That means, depending on daylight saving times or not, you may get different
+ * offsets.
  *
- * This datatype makes only sense to use, if your application works with an offset, not
- * with an actual timezone that uses transitions. Otherwise your DateTime instance
- * attached with a timezone such as Europe/Berlin gets saved into the database with
+ * This datatype makes only sense to use, if your application only needs to accept the timezone offset,
+ * not the actual timezone that uses transitions. Otherwise your DateTime instance
+ * attached with a timezone such as "Europe/Berlin" gets saved into the database with
  * the offset and re-created from persistence with only the offset, not the original timezone
  * attached.
  */