TN001 - (PostgreSQL *)clone:(int *)errorCode - what's for ?

In circumstances where locking a table or a row in one table while fetching data into one or more other tables, it is important to avoid unwanted cancellation of the initial transaction in case something goes wrong in one of the secondary query. This kind of situation is often related to update of records by user interaction.
Example :

begin a transaction
select for update a record to be updated by the user
present the data to the user and wait for its decision (Runloop)

during the interaction, the user triggers widgets leading to other data fetchning.

Example with customer data editing: you present customer data and the user edit the address, he enters a erroneous zip code and you present a list of valid zip codes. Doing this means executing another select on your zip code table. This may lead to executing SQL code conflicting with the fact that we are inside a transaction. This situation is solved by executing the secondary queries from another PostgreSQL connection object.
The easiest way to get another connection object to the same database is to clone the first one.

This is the purpose of

(PostgreSQL *)clone:(int *)errorCode;

What does this method is really give you a NEW connection to the back-end. This new connection is independent of the first one but with exactly the same characteristics (login, database, options).

Another circumstance where cloning a connection object may be required is when processing result from a SELECT query needs to UPDATE another table. You could use -(PgSQLResult *)getResultSet; but this routine copy the data from the back-end into the client memory. If the result is huge, this may lead to performance hit. If you clone the connection object and execute the UPDATE thru this new connection, There is no need to fetch the whole result of the first query and you may process each row at the time in a

while ([selectConn nextRow]) {

Note that each PosgreSQL connection object created should be released by calling [PostgreSQL releasePostgreSQLConnection:myConn] so that it's returned to the internal connection pool.