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

2 files changed, 37 insertions, 0 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index b3ba657a8..1dfe82934 100644
--- 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 6ad560e5b..8915b8098 100644
--- 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)