Resolved #56444: updated transaction/locking doc

Changes

@@ -3,8 +3,8 @@ Changes for Perl extension DBD-SQLite
 1.38_01 to be released
     *** CHANGES THAT MAY POSSIBLY BREAK YOUR OLD APPLICATIONS ***
     - Set sqlite_use_immediate_transaction to true by default
-      (See RT #56444). This usually shouldn't matter, but if you
+      to avoid deadlocks (see RT #56444). If you really need
-      really need the deferred transaction (which had long been the
+      the deferred transaction (which had long been the
       default), explicitly set sqlite_use_immediate_transaction
       to false. (ISHIGAKI)
 

lib/DBD/SQLite.pm

@@ -1031,36 +1031,24 @@ statement, and ends by a C<COMMIT> or a <ROLLBACK>.
 
 =head2 Transaction and Database Locking
 
-Transaction by C<AutoCommit> or C<begin_work> is nice and handy, but
+The default transaction behavior of SQLite is C<deferred>, that
-sometimes you may get an annoying "database is locked" error.
+means, locks are not acquired until the first read or write
-This typically happens when someone begins a transaction, and tries
+operation, and thus it is possible that another thread or process
-to write to a database while other person is reading from the
+could create a separate transaction and write to the database after
-database (in another transaction). You might be surprised but SQLite
+the C<BEGIN> on the current thread has executed, and eventually
-doesn't lock a database when you just begin a normal (deferred)
+cause a "deadlock". To avoid this, DBD::SQLite internally issues
-transaction to maximize concurrency. It reserves a lock when you
+a C<BEGIN IMMEDIATE> when you begin a transaction by
-issue a statement to write, but until you actually try to write
+C<begin_work> or under the C<AutoCommit> mode (since 1.38_01).
-with a C<commit> statement, it allows other people to read from
-the database. However, reading from the database also requires
-C<shared lock>, and that prevents to give you the C<exclusive lock>
-you reserved, thus you get the "database is locked" error, and
-other people will get the same error if they try to write afterwards,
-as you still have a C<pending> lock. C<busy_timeout> doesn't help
-in this case.
 
-To avoid this, set a transaction type explicitly. You can issue a
+If you really need to turn off this feature for some reasons,
-C<begin immediate transaction> (or C<begin exclusive transaction>)
+set C<sqlite_use_immediate_transaction> database handle attribute
-for each transaction, or set C<sqlite_use_immediate_transaction>
+to false, and the default C<deferred> transaction will be used.
-database handle attribute to true (since 1.30_02) to always use
-an immediate transaction (even when you simply use C<begin_work>
-or turn off the C<AutoCommit>.).
 
   my $dbh = DBI->connect("dbi:SQLite::memory:", "", "", {
-    sqlite_use_immediate_transaction => 1,
+    sqlite_use_immediate_transaction => 0,
   });
 
-Note that this works only when all of the connections use the same
+See L<http://sqlite.org/lockingv3.html> for locking details.
-(non-deferred) transaction. See L<http://sqlite.org/lockingv3.html>
-for locking details.
 
 =head2 C<< $sth->finish >> and Transaction Rollback
 
@@ -1197,6 +1185,10 @@ If you set this to true, DBD::SQLite tries to issue a C<begin
 immediate transaction> (instead of C<begin transaction>) when
 necessary. See above for details.
 
+As of version 1.38_01, this attribute is set to true by default.
+If you really need to use C<deferred> transactions for some reasons,
+set this to false explicitly.
+
 =item sqlite_see_if_its_a_number
 
 If you set this to true, DBD::SQLite tries to see if the bind values