Ticket #9409: database_is_locked_docs.diff

docs/ref/databases.txt

@@ -278 +278 @@
 attempts to import ``pysqlite2`` before that ``sqlite3`` and so it can take 
 advantage of the new ``pysqlite2``/SQLite versions.
 
+``OperationalError: database is locked`` errors
+-----------------------------------------------
+
+``OperationalError: database is locked`` errors indicate that your application
+is experiencing more concurrency than ``pysqlite`` can handle in default
+configuration. Note that a SQLite database is essentially accessed in serial
+manner in threaded environment, so the error means that one thread has an
+exclusive lock on the SQLite database connection and another thread was trying
+to use the same connection, but timed out waiting on the lock. ``pysqlite`` has
+a default timeout value that determines how long the second thread is allowed to
+wait on the lock before it times out and raises the ``OperationalError: database
+is locked`` error.
+
+To avoid the error, you can either
+
+ * use another database backend or
+
+ * reduce concurrency by ensuring that your database transactions are
+   short-lived or
+
+ * increase the default timeout value by setting the ``timeout`` option::
+
+          DATABASE_OPTIONS = {
+              # ...
+             "timeout": 20,
+              # ...
+          }
+
 .. _oracle-notes:
 
 Oracle notes