propigated detach() and invalidate() methods to Connection.

diff --git a/CHANGES b/CHANGES
index 2e4862d1df58045c2dcd747f5f28d91a50246d7b..3526f7486447bcf4da5cb05e9eed8e74feced77c 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,8 @@
 - engines
-    - connections can be detached from their pool, closing on dereference
-      instead of returning to the pool for reuse
+    - added detach() to Connection, allows underlying DBAPI connection to be detached 
+      from its pool, closing on dereference/close() instead of being reused by the pool.
+    - added invalidate() to Connection, immediately invalidates the Connection and its
+      underlying DBAPI connection.
 - sql
     - _Label class overrides compare_self to return its ultimate object.
       meaning, if you say someexpr.label('foo') == 5, it produces

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index b3ba657a832be993bcc1f7191925594edb8abeb2..1dfe8293474eca429f8c2fb01d21705628e19eac 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -427,6 +427,30 @@ class Connection(Connectable):
         """contextual_connect() is implemented to return self so that an incoming Engine or Connection object can be treated similarly."""
         return self
 
+    def invalidate(self):
+        """invalidate the underying DBAPI connection and immediately close this Connection.
+        
+        The underlying DBAPI connection is literally closed (if possible), and is discarded.
+        Its source connection pool will typically create a new connection to replace it, once
+        requested.
+        """
+        
+        self.__connection.invalidate()
+        self.__connection = None
+
+    def detach(self):
+        """detach the underlying DBAPI connection from its connection pool.
+        
+        This Connection instance will remain useable.  When closed, the 
+        DBAPI connection will be literally closed and not returned to its pool.
+        The pool will typically create a new connection to replace it, once requested.
+        
+        This method can be used to insulate the rest of an application from a modified
+        state on a connection (such as a transaction isolation level or similar).
+        """
+        
+        self.__connection.detach()
+        
     def begin(self):
         if self.__transaction is None:
             self.__transaction = self._create_transaction(None)

diff --git a/lib/sqlalchemy/pool.py b/lib/sqlalchemy/pool.py
index 6ad560e5b30846739e9728f70991fc7acb5a916a..8915b8098d9b062d014bc85db76029e4751d5876 100644 (file)
--- a/lib/sqlalchemy/pool.py
+++ b/lib/sqlalchemy/pool.py
@@ -258,6 +258,11 @@ class _ConnectionFairy(object):
     is_valid = property(lambda self:self.connection is not None)
     
     def invalidate(self, e=None):
+        """Mark this connection as invalidated.
+        
+        The connection will be immediately closed.  The 
+        containing ConnectionRecord will create a new connection when next used.
+        """
         if self.connection is None:
             raise exceptions.InvalidRequestError("This connection is closed")
         if self._connection_record is not None:
@@ -284,6 +289,14 @@ class _ConnectionFairy(object):
         return self
 
     def detach(self):
+        """Separate this Connection from its Pool.
+        
+        This means that the connection will no longer be returned to the 
+        pool when closed, and will instead be literally closed.  The 
+        containing ConnectionRecord is separated from the DBAPI connection, and
+        will create a new connection when next used.
+        """
+        
         if self._connection_record is not None:
             self._connection_record.connection = None        
             self._pool.do_return_conn(self._connection_record)