NHibernate ISession Flush: Where and when to use it, and why?

Briefly:

1. Always use transactions
2. Don’t use Close(), instead wrap your calls on an ISession inside a using statement or manage the lifecycle of your ISession somewhere else.

From the documentation:

From time to time the ISession will execute the SQL statements needed to synchronize the ADO.NET connection’s state with the state of objects held in memory. This process, flush, occurs by default at the following points

• from some invocations of Find() or Enumerable()
• from NHibernate.ITransaction.Commit()
• from ISession.Flush()

The SQL statements are issued in the following order

1. all entity insertions, in the same order the corresponding objects were saved using ISession.Save()
2. all entity updates
3. all collection deletions
4. all collection element deletions, updates and insertions
5. all collection insertions
6. all entity deletions, in the same order the corresponding objects were deleted using ISession.Delete()

(An exception is that objects using native ID generation are inserted when they are saved.)

Except when you explicity Flush(), there are absolutely no guarantees about when the Session executes the ADO.NET calls, only the order in which they are executed. However, NHibernate does guarantee that the ISession.Find(..) methods will never return stale data; nor will they return the wrong data.

It is possible to change the default behavior so that flush occurs less frequently. The FlushMode class defines three different modes: only flush at commit time (and only when the NHibernate ITransaction API is used), flush automatically using the explained routine, or never flush unless Flush() is called explicitly. The last mode is useful for long running units of work, where an ISession is kept open and disconnected for a long time.

…

Also refer to this section:

Ending a session involves four distinct phases:

• flush the session
• commit the transaction
• close the session
• handle exceptions

Flushing the Session

If you happen to be using the ITransaction API, you don’t need to worry about this step. It will be performed implicitly when the transaction is committed. Otherwise you should call ISession.Flush() to ensure that all changes are synchronized with the database.

Committing the database transaction

If you are using the NHibernate ITransaction API, this looks like:

tx.Commit(); // flush the session and commit the transaction

If you are managing ADO.NET transactions yourself you should manually Commit() the ADO.NET transaction.

sess.Flush();
currentTransaction.Commit();

If you decide not to commit your changes:

tx.Rollback();  // rollback the transaction

or:

currentTransaction.Rollback();

If you rollback the transaction you should immediately close and discard the current session to ensure that NHibernate’s internal state is consistent.

Closing the ISession

A call to ISession.Close() marks the end of a session. The main implication of Close() is that the ADO.NET connection will be relinquished by the session.

tx.Commit();
sess.Close();

sess.Flush();
currentTransaction.Commit();
sess.Close();

If you provided your own connection, Close() returns a reference to it, so you can manually close it or return it to the pool. Otherwise Close() returns it to the pool.