Revert to use default poolclass under Firebird

This partially reverts [3562] and instead documents the problem suggesting
a possible workaround. For the tests, the occurence of the problem is
largely reduced by using a TCP connection (that is, 'localhost:/some/file.fdb'
instead of '/some/file.fdb')

2 files changed, 31 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index a19d5302c..ee5831d58 100644
--- a/CHANGES
+++ b/CHANGES
@@ -206,7 +206,17 @@ CHANGES
 
    - MSSQL/PyODBC no longer has a global "set nocount on".
 
-   - Firebird backend does properly reflect domains (partially fixing [ticket:410]).
+   - Firebird backend
+
+     - does properly reflect domains (partially fixing [ticket:410]) and
+       PassiveDefaults
+
+     - reverted to use default poolclass (was set to SingletonThreadPool in
+       0.4.0 [3562] for test purposes)
+
+     - map func.length() to 'char_length' (easily overridable with the UDF
+       'strlen' on old versions of Firebird)
+
 
 0.4.1
 -----
diff --git a/lib/sqlalchemy/databases/firebird.py b/lib/sqlalchemy/databases/firebird.py
index 8b7a41aac..a86dfb23f 100644
--- a/lib/sqlalchemy/databases/firebird.py
+++ b/lib/sqlalchemy/databases/firebird.py
@@ -59,6 +59,25 @@ on the ``FBDialect`` class to do whatever is needed::
       # instead of ``char_length``
       FBCompiler.LENGTH_FUNCTION_NAME = 'strlen'
 
+Pooling connections
+-------------------
+
+The default strategy used by SQLAlchemy to pool the database connections
+in particular cases may raise an ``OperationalError`` with a message
+`"object XYZ is in use"`. This happens on Firebird when there are two
+connections to the database, one is using, or has used, a particular table
+and the other tries to drop or alter the same table. To garantee DDL
+operations success Firebird recommend doing them as the single connected user.
+
+In case your SA application effectively needs to do DDL operations while other
+connections are active, the following setting may alleviate the problem::
+
+  from sqlalchemy import pool
+  from sqlalchemy.databases.firebird import dialect
+
+  # Force SA to use a single connection per thread
+  dialect.poolclass = pool.SingletonThreadPool
+
 
 .. [#] Well, that is not the whole story, as the client may still ask
        a different (lower) dialect...
@@ -71,7 +90,7 @@ on the ``FBDialect`` class to do whatever is needed::
 import datetime
 import warnings
 
-from sqlalchemy import exceptions, pool, schema, types as sqltypes, sql, util
+from sqlalchemy import exceptions, schema, types as sqltypes, sql, util
 from sqlalchemy.engine import base, default
 
 
@@ -655,7 +674,6 @@ class FBIdentifierPreparer(sql.compiler.IdentifierPreparer):
 
 
 dialect = FBDialect
-dialect.poolclass = pool.SingletonThreadPool
 dialect.statement_compiler = FBCompiler
 dialect.schemagenerator = FBSchemaGenerator
 dialect.schemadropper = FBSchemaDropper