hey list -

i have committed my work on the 0.2 series so far to a branch in SVN. 
this branch is available at:


Its not all working yet.  SQLite is up, Postgres is sort of up, the rest
still need some conversion.  unittests are 50/50.

I would encourage everyone to check it out, particularly those who:

   - do stuff with explicit transactions
   - have written wrappers around SQLEngine, etc.
   - want to get into explicit connections and Sessions (the whole reason
for the branch....)

At the end of the day, there will be a few changes for everyone.  These

  - SQLEngine is now, at its base, called Engine, and has a simplified
  - objectstore.commit() is now called objectstore.flush()
  - create_engine URLs are going into
engine://user:[EMAIL PROTECTED]:port/database format.
  - while you can still create a Table with an Engine, its deprecated, and
you should create it with MetaData object that is then (optionally)
"bound" to an Engine.  You can also fly all the way without Tables or
any other constructed SQL having any associated engine (these are
"unbound" constructs).
  - when you execute things in the usual way, i.e. a "bound" construct
like statement.execute(), the returned ResultProxy has a close() method
on it  which returns the underlying connection to the connection pool. 
this method is more important if you are working without a thread-local
configuration or cant trust __del__ to clean up connections.
  - the entire "thread-local" concept, which regulates connections
returned by the engine from the connection pool as well as provides a
default thread-local Session object, is now optional.  at the moment,
its disabled by default and you turn it on by placing
"install_mods('threadlocal')" anywhere in your application (im sort of
torn on if it should be that way).   if you dont do that, then you cant
rely upon any implicit get_session() functionality and have to use
explicit sessions, you have to use an explicit transaction object off
the Engine instead of doing "begin()/commit()" directly off the engine,
and when you execute bound clause objects (like selects, etc) you
probably want to make sure their resources are close()'d or
dereferenced, so that the next execution in the same thread does not
call up a second connection from the pool.
  - Session.begin()/commit() is totally out.  if you want to use that,
there is a mod 'legacy_session' that will turn it back on, but thats
only meant as a transitional thing.  One Session is now just one
Session.  if you want to compartmentalize things, use a second Session.
  - on the flip side, the Session knows all about associating itself with
one or more Engines, and now has a neat "create_transaction" of its own
that will automatically do a "begin" on each Engine encountered.  You
can also call mapper queries and SQL calls off a Session, which you
probably want to do if you have threadlocal turned off and/or are
dealing with "unbound" tables (tables that are not attached to an

So anyway, for those who have dealt with the code before, first check out
the file lib/sqlalchemy/engine/base.py .  this is the set of interfaces
that form the components of the new Engine object.  the other modules in
the engine/ package provide implementations of those interfaces as well as
some factory stuff.

The other thing to look at is the new Session object inside the
objectstore module.  a typical totally explicit session (i.e. no
threadlocal, no bound Tables) at the moment looks like:

 e = create_engine('postgres://user:[EMAIL PROTECTED]/db')
 metadata = MetaData()
 t = Table('mytable', metadata, columns...)
 m = mapper(MyClass, t, ...)
 s = Session(bind_to=e)

 o = MyClass()
 s.register_new(o)   # can also say _sa_session=s

 objects = s.query(m).select()
 objects[1].foo = 'bar'

theres more you can do..the Session can bind different tables to different
engines, it can bind to Connections instead of Engines, and the Session
can provide a real transactional interface too.  whats missing is, the
docs, and also some convention on how these patterns will be most
expediently used.

keep in mind though that the old way of doing things is still pretty much
intact, and the docs will more often than not refer to the "thread-local"
way of doing things.

with all of this , SA will become more viable as a set of tools with which
to build database frameworks on top of (and probably even more daunting to

This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
Sqlalchemy-users mailing list

Reply via email to