Commits

Mike Bayer committed 1e80d19

more on non-threadsafeness

Comments (0)

Files changed (1)

doc/build/content/dbengine.txt

 
 In this section we describe the SQL execution interface available from an `Engine` instance.  Note that when using the Object Relational Mapper (ORM) as well as when dealing with with "bound" metadata objects, SQLAlchemy deals with the Engine and Connections for you and you generally don't need to know much about it; in those cases, you can skip this section and go to [metadata](rel:metadata).  "Bound" metadata is described in [metadata_tables_binding](rel:metadata_tables_binding).
 
-The Engine provides a `connect()` method which returns a `Connection` object.  This object provides methods by which literal SQL text as well as SQL clause constructs can be compiled and executed.  
+The Engine provides a `connect()` method which returns a `Connection` object.  `Connection` is a *proxy* object which maintains a reference to a DBAPI connection instance.  This object provides methods by which literal SQL text as well as SQL clause constructs can be compiled and executed.  
 
     {python}
     engine = create_engine('sqlite:///:memory:')
 
 The `close` method on `Connection` does not actually remove the underlying connection to the database, but rather indicates that the underlying resources can be returned to the connection pool.  When using the `connect()` method, the DBAPI connection referenced by the `Connection` object is not referenced anywhere else. 
 
-
 In both execution styles above, the `Connection` object will also automatically return its resources to the connection pool when the object is garbage collected, i.e. its `__del__()` method is called.  When using the standard C implementation of Python, this method is usually called immediately as soon as the object is dereferenced.  With other Python implementations such as Jython, this is not so guaranteed.  
     
 The execute method on `Engine` and `Connection` can also receive SQL clause constructs as well, which are described in [sql](rel:sql):
 
 #### Implicit Execution Strategies {@name=strategies}
 
-The internal behavior of engine during implicit execution can be affected by the `strategy` keyword argument to `create_engine()`.  Generally this setting can be left at its default value of `plain`.  However, for the advanced user the `threadlocal` option can provide the service of managing connections against the current thread in which they were pulled from the connection pool, where the same connection as well as a single transaction can then be shared by many operations without explicitly passing a `Connection` or `Transaction` object around.  It also may reduce the number of connections checked out from the connection pool at a given time.
+The internal behavior of engine during implicit execution can be affected by the `strategy` keyword argument to `create_engine()`.  Generally this setting can be left at its default value of `plain`.  However, for the advanced user, the `threadlocal` option can provide the service of managing connections against the current thread in which they were pulled from the connection pool, where the same underlying DBAPI connection as well as a single database-level transaction can then be shared by many operations without explicitly passing a `Connection` or `Transaction` object around.  It also may reduce the number of connections checked out from the connection pool at a given time.
+
+Note that this setting does **not** affect the fact that **Connection and Transaction objects are not threadsafe.**.  The "threadlocal" strategy affects the selection of DBAPI connections which are pulled from the connection pool when a `Connection` object is created, but does not synchronize method access to the `Connection` or `Transaction` instances themselves, which are only proxy objects.  It is instead intended that many `Connection` instances would share access to a single "connection" object that is referenced in relation to the current thread.
 
 When `strategy` is set to `plain`, each implicit execution requests a unique connection from the connection pool, which is returned to the pool when the resulting `ResultProxy` falls out of scope (i.e. `__del__()` is called) or its `close()` method is called.  If a second implicit execution occurs while the `ResultProxy` from the previous execution is still open, then a second connection is pulled from the pool.