Documentation for om.Session.flush() is misleading

This is a bit nit-picky, but it left me scratching my head for awhile. The documenation for orm.session.flush() says the following:

Database operations will be issued in the current transactional
context and do not affect the state of the transaction.  You may
flush() as often as you like within a transaction to move changes from
Python to the database's transaction buffer.

In reality, when you have autocommit=True and you've started your own transaction manually, a call to flush() can invalidate your session if you run an invalid SQL command - e.g. insert a null value into a non-nullable column. The code for flush does the following:

        flush_context.transaction = transaction = self.begin(
            subtransactions=True)
        try:
            flush_context.execute()

            for ext in self.extensions:
                ext.after_flush(self, flush_context)
            transaction.commit()
        except:
            transaction.rollback() #UNEXPECTED BEHAVIOR HERE!
            raise

If you're already in transaction, this code creates a nested transaction which, when rolled back, will invalidate your top-level transaction.

This is good behavior, but it should be documented more clearly.

Comments (4)