FAQ update about transaction interleaving

Our FAQ entry on XA support is quite vague; most users don't know what
transaction interleaving is or why they should care.

Here's an updated version based on a response I gave earlier to a post
asking about it:

-----------------
1.1. Does the driver have XA support?

Yes, starting with the 8.1dev-403 driver. However, the transaction
interleaving is not supported.

1.2. What is "transaction interleaving"?

Transaction interleaving means that one database connection can be used
for multiple transactions at the same time, switching between the
transactions.

Transaction interleaving is mostly useless, but it's a required part of
the JTA specification. Some application servers use it to allow a bit
more concurrency without allocating a bigger jdbc connection pool.

Few JDBC drivers support transaction interleaving properly. Some fake it
by issuing early prepare commands, risking transaction integrity, some
give strange error messages, some fail in other, subtle ways. The
PostgreSQL JDBC driver does it's best to detect interleaving and throws
a proper error message when it can't do what's requested.

Because of the lack of driver support, all of the popular application
servers use provide options to work around it, or don't use it at all.
Therefore, lack of transaction interleaving shouldn't affect your
application or data integrity.

See the JTA specification, section 3.4.4, or search the pgsql-jdbc
mailing list archives for more information.

1.3. How to configure application server XXX to work with the PostgreSQL
JDBC driver

[We need some examples...]

Please read the documentation of your application server for details.
You might need to set a flag to disable transaction interleaving. In
JBoss, for example, set the "track-connection-by-tx" parameter.

--
  Heikki Linnakangas
  EnterpriseDB   http://www.enterprisedb.com