If you want to control the database transactions yourself (maybe because you want to accumulate several calls to session.flush() before committing the transaction), you can. See the Transactions section, below, for details.

New in 0.2: The session.flush() function used to be called objectstore.commit(). The method name changed from commit() to flush() in 0.2 because commit() sounded like what you do to a database transaction, and it was causing some people to confuse SQLAlchemy sessions and database transactions, which are two completely separate concepts.

fred = User()
fred.name = 'Fred'
fred.age = 37

Here we're creating a new instance of our data class, User. This will eventually result in a new database row once we call session.flush().

print "About to flush() without a save()..."
session.flush()  # Will *not* save Fred's data yet

Look at the output from running this example. Notice that this session.flush() call resulted in no database activity whatsoever, even though we just created a new instance of our data class, which is supposed to automatically create a new row in our database table. Why didn't session.flush() do what it's supposed to do?

See if you can figure it out before proceeding to the next section. Hint: remember that you're not necessarily limited to having only one Session object around at any given time, and that "Explicit is better than implicit."

session.save(fred)
print "Just called save(). Now flush() will actually do something."
session.flush()  # Now Fred's data will be saved

Now we see why the previous session.flush() call didn't actually save Fred's data to the database. The fred object wasn't yet associated with any Session objects! Explicit is better than implicit. By calling session.save(fred), we explicitly made session responsible for managing the fred instance. From now on, any changes made to the fred instance will be tracked by our session instance. That includes fred's current state of "instance has been created, but database row has not yet been created". Any such "pending" objects will be flushed to the database at the next call to session.flush(), as you can see from the output of running the example.

As was mentioned before, there are advanced features that let you have a "default Session context". If you're using those features, then any newly-created data instances (like our fred instance above) would be automatically registered with the Session object from the current context, and there'd be no need to call session.save(fred) -- and therefore, the first session.flush() call in our above example would have created a new row in the database.

However, it's usually best to learn the explicit way of doing things first; learning the implicit way of doing things can wait until you're comfortable with the explicit way. Then, when you hit the limits of the implicit way and need to drop into "explicit mode" for a while, you won't be stepping outside the limits of your comfort zone. It's much harder to go the other way around: if you get too used to using implicit, default Session objects, then it will be hard to remember how to use them explicitly. This can lead to mistakes like calling flush() without calling save() first, followed by much head-scratching as you try to figure out why the database doesn't contain Fred's newly-created data.