* Is the session thread-safe?
- Nope. It has no thread synchronization of any kind built in, and particularly when you do a flush operation, it definitely is not open to concurrent threads accessing it, because it holds onto a single database connection at that point. If you use a session which is non-transactional for read operations only, it's still not thread-"safe", but you also wont get any catastrophic failures either, since it opens and closes connections on an as-needed basis; it's just that different threads might load the same objects independently of each other, but only one will wind up in the identity map (however, the other one might still live in a collection somewhere).
+ Nope. It has no thread synchronization of any kind built in, and particularly when you do a flush operation, it definitely is not open to concurrent threads accessing it, because it holds onto a single database connection at that point. If you use a session which is non-transactional for read operations only, it's still not thread-"safe", but you also wont get any catastrophic failures either, since it checks out and returns connections to the connection pool on an as-needed basis; it's just that different threads might load the same objects independently of each other, but only one will wind up in the identity map (however, the other one might still live in a collection somewhere).
But the bigger point here is, you should not *want* to use the session with multiple concurrent threads. That would be like having everyone at a restaurant all eat from the same plate. The session is a local "workspace" that you use for a specific set of tasks; you don't want to, or need to, share that session with other threads who are doing some other task. If, on the other hand, there are other threads participating in the same task you are, such as in a desktop graphical application, then you would be sharing the session with those threads, but you also will have implemented a proper locking scheme (or your graphical framework does) so that those threads do not collide.
:func:`~sqlalchemy.orm.session.Session.rollback` rolls back the current transaction. With a default configured session, the post-rollback state of the session is as follows:
- * All connections are rolled back and returned to the connection pool, unless the Session was bound directly to a Connection, in which case the connection is still maintained (but still rolled back).
+ * All transactions are rolled back and all connections returned to the connection pool, unless the Session was bound directly to a Connection, in which case the connection is still maintained (but still rolled back).
* Objects which were initially in the *pending* state when they were added to the :class:`~sqlalchemy.orm.session.Session` within the lifespan of the transaction are expunged, corresponding to their INSERT statement being rolled back. The state of their attributes remains unchanged.
* Objects which were marked as *deleted* within the lifespan of the transaction are promoted back to the *persistent* state, corresponding to their DELETE statement being rolled back. Note that if those objects were first *pending* within the transaction, that operation takes precedence instead.
* All objects not expunged are fully expired.
The above example illustrates an explicit call to ``Session.remove()``. This has the effect such that each web request starts fresh with a brand new session. When integrating with a web framework, there's actually many options on how to proceed for this step:
-* Session.remove() - this is the most cut and dry approach; the :class:`~sqlalchemy.orm.session.Session` is thrown away, all of its transactional/connection resources are closed out, everything within it is explicitly gone. A new :class:`~sqlalchemy.orm.session.Session` will be used on the next request.
-* Session.close() - Similar to calling ``remove()``, in that all objects are explicitly expunged and all transactional/connection resources closed, except the actual :class:`~sqlalchemy.orm.session.Session` object hangs around. It doesn't make too much difference here unless the start of the web request would like to pass specific options to the initial construction of :class:`~sqlalchemy.orm.session.Session()`, such as a specific :class:`~sqlalchemy.engine.base.Engine` to bind to.
-* Session.commit() - In this case, the behavior is that any remaining changes pending are flushed, and the transaction is committed. The full state of the session is expired, so that when the next web request is started, all data will be reloaded. In reality, the contents of the :class:`~sqlalchemy.orm.session.Session` are weakly referenced anyway so its likely that it will be empty on the next request in any case.
-* Session.rollback() - Similar to calling commit, except we assume that the user would have called commit explicitly if that was desired; the :func:`~sqlalchemy.orm.session.Session.rollback` ensures that no transactional state remains and expires all data, in the case that the request was aborted and did not roll back itself.
+* Session.remove() - this is the most cut and dry approach; the :class:`~sqlalchemy.orm.session.Session` is thrown away, all of its transactional resources rolled back and connections checked back to the connection pool. A new :class:`~sqlalchemy.orm.session.Session` will be used on the next request.
+* Session.close() - Similar to calling ``remove()``, in that all objects are explicitly expunged, transactional resources are rolled back, connection resources checked back into the connection pool, except the actual :class:`~sqlalchemy.orm.session.Session` object hangs around. It doesn't make too much difference here unless the start of the web request would like to pass specific options to the initial construction of :class:`~sqlalchemy.orm.session.Session()`, such as a specific :class:`~sqlalchemy.engine.base.Engine` to bind to.
+* Session.commit() - In this case, the behavior is that any remaining changes pending are flushed, and the transaction is committed; connection resources are returned to the connection pool. The full state of the session is expired, so that when the next web request is started, all data will be reloaded. In reality, the contents of the :class:`~sqlalchemy.orm.session.Session` are weakly referenced anyway so its likely that it will be empty on the next request in any case.
+* Session.rollback() - Similar to calling commit, except we assume that the user would have called commit explicitly if that was desired; the :func:`~sqlalchemy.orm.session.Session.rollback` ensures that no transactional state remains, returns connections to the connection pool, and expires all data, in the case that the request was aborted and did not roll back itself.
* do nothing - this is a valid option as well. The controller code is responsible for doing one of the above steps at the end of the request.
Scoped Session API docs: :func:`sqlalchemy.orm.scoped_session`
====================================
-We're executing our :class:`~sqlalchemy.sql.expression.Insert` using a :class:`~sqlalchemy.engine.base.Connection`. There's two options that allow you to not have to deal with the connection part. You can execute in the **connectionless** style, using the engine, which opens and closes a connection for you:
+We're executing our :class:`~sqlalchemy.sql.expression.Insert` using a :class:`~sqlalchemy.engine.base.Connection`. There's two options that allow you to not have to deal with the connection part. You can execute in the **connectionless** style, using the engine, which checks out from the connection pool a connection for you, performs the execute operation with that connection, and then checks the connection back into the pool upon completion of the operation:
.. sourcecode:: pycon+sql
name: fred ; fullname: Fred Flintstone
name: mary ; fullname: Mary Contrary
-Result sets which have pending rows remaining should be explicitly closed before discarding. While the resources referenced by the :class:`~sqlalchemy.engine.base.ResultProxy` will be closed when the object is garbage collected, it's better to make it explicit as some database APIs are very picky about such things:
+Result sets which have pending rows remaining should be explicitly closed before discarding. While the cursor and connection resources referenced by the :class:`~sqlalchemy.engine.base.ResultProxy` will be respectively closed and returned to the connection pool when the object is garbage collected, it's better to make it explicit as some database APIs are very picky about such things:
.. sourcecode:: pycon+sql
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
