Added Known Vendor Issues section into the DBAL manual, detailing PostgreSQL...

Added Known Vendor Issues section into the DBAL manual, detailing PostgreSQL DateTime microseconds problem and the solution implemented in DBAL-33

reference/en.txt

 + Introduction
 + Architecture
 + Configuration
-+ Events
 + Data Retrieval and Manipulation
 + Transactions
 + Platforms
 + Types
 + Schema Manager
 + Schema Representation
-+ Supporting Other Databases
++ Events
\ No newline at end of file
++ Supporting Other Databases
++ Known Vendor Issues
\ No newline at end of file

reference/en/data-retrieval-and-manipulation.txt

@@ -20,7 +20,7 @@ Prepare a given sql statement and return the `\Doctrine\DBAL\Driver\Statement` i
     )
     */
 
-++ executeUpdate($sql, array $params)
+++ executeUpdate($sql, array $params = array(), array $types = array())
 
 Executes a prepared statement with the given sql and parameters and returns the
 affected rows count:
@@ -29,7 +29,11 @@ affected rows count:
     $count = $conn->executeUpdate('UPDATE user SET username = ? WHERE id = ?', array('jwage', 1));
     echo $count; // 1
 
-++ executeQuery($sql, array $params)
+The `$types` variable contains the PDO or Doctrine Type constants to perform
+necessary type conversions between actual input parameters and expected database values.
+See the [Types](./types#type-conversion) section for more information.
+
+++ executeQuery($sql, array $params = array(), array $types = array())
 
 Creates a prepared statement for the given sql and passes the parameters to the
 execute method, then returning the statement:
@@ -45,6 +49,10 @@ execute method, then returning the statement:
     )
     */
 
+The `$types` variable contains the PDO or Doctrine Type constants to perform
+necessary type conversions between actual input parameters and expected database values.
+See the [Types](./types#type-conversion) section for more information.
+
 ++ fetchAll($sql, array $params)
 
 Execute the query and fetch all results into an array:

reference/en/known-vendor-issues.txt

+This section describes known compatability issues with all the supported database vendors:
+
+++ PostgreSQL
+
++++ DateTime, DateTimeTz and Time Types
+
+Postgres has a variable return format for the datatype TIMESTAMP(n) and TIME(n)
+if microseconds are allowed (n > 0). Whenever you save a value with microseconds = 0.
+PostgreSQL will return this value in the format:
+
+    2010-10-10 10:10:10 (Y-m-d H:i:s)
+
+However if you save a value with microseconds it will return the full representation:
+
+    2010-10-10 10:10:10.123456 (Y-m-d H:i:s.u)
+
+Using the DateTime, DateTimeTz or Time type with microseconds enabled columns
+can lead to errors because internally types expect the exact format 'Y-m-d H:i:s'
+in combination with `DateTime::createFromFormat()`. This method is twice a fast
+as passing the date to the constructor of `DateTime`.
+
+This is why Doctrine always wants to create the time related types without microseconds:
+
+* DateTime to `TIMESTAMP(0) WITHOUT TIME ZONE`
+* DateTimeTz to `TIMESTAMP(0) WITH TIME ZONE`
+* Time to `TIME(0) WITHOUT TIME ZONE`
+
+If you do not let Doctrine create the date column types and rather use types with microseconds
+you have replace the "DateTime", "DateTimeTz" and "Time" types with a more liberal DateTime parser
+that detects the format automatically:
+
+    [php]
+    use Doctrine\DBAL\Types\Type;
+
+    Type::overrideType('datetime', 'Doctrine\DBAL\Types\VarDateTime');
+    Type::overrideType('datetimetz', 'Doctrine\DBAL\Types\VarDateTime');
+    Type::overrideType('time', 'Doctrine\DBAL\Types\VarDateTime');
+
++++ Timezones and DateTimeTz
+
+Postgres 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).
+
+++ MySQL
+
++++ DateTimeTz
+
+MySQL does not support saving timezones or offsets. The DateTimeTz type therefore behave like the DateTime type.
+
+++ Sqlite
+
++++ DateTimeTz
+
+Sqlite does not support saving timezones or offsets. The DateTimeTz type therefore behave like the DateTime type.
+
+++ 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).
+
+++ Oracle
+
+Oracle 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).
+
+++ Microsoft SQL Server
+
+Nothing yet.
\ No newline at end of file

reference/en/types.txt

@@ -22,7 +22,12 @@ the supported database vendors:
 Types are flyweights. This means there is only ever one instance of a type and it is not allowed to contain any state.
 Creation of type instances is abstracted through a static get method `Doctrine\DBAL\Types\Type::getType()`.
 
-++ Schema Detection of Database Types
+> **NOTE**
+>
+> See the [Known Vendor Issue](./known-vendor-issues) section for details about the different
+> handling of microseconds and timezones across all the different vendors.
+
+++ Detection of Database Types
 
 When calling table inspection methods on your connections `SchemaManager` instance
 the retrieved database column types are translated into Doctrine mapping types.