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

Briefly:

Always use transactions 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 all entity insertions, in the same order the corresponding objects were saved using ISession.Save() all entity updates all collection deletions all collection element deletions, updates and insertions all collection insertions 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.

Starting in NHibernate 2.0, transactions are required for DB operations. Therefore, the ITransaction.Commit() call will handle any necessary flushing. If for some reason you aren't using NHibernate transactions, then there will be no auto-flushing of the session.

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.

And always use

 using (var transaction = session.BeginTransaction())
 {
     transaction.Commit();
 }

after the changes are committed than this changes to save into database we use transaction.Commit();

Here are two examples of my code where it would fail without session.Flush():

http://www.lucidcoding.blogspot.co.uk/2012/05/changing-type-of-entity-persistence.html

at the end of this, you can see a section of code where I set identity insert on, save the entity then flush, then set identity insert off. Without this flush it seemed to be setting identity insert on and off then saving the entity.

The use of Flush() gave me more control over what was going on.

Here is another example:

Sending NServiceBus message inside TransactionScope

I don't fully understand why on this one, but Flush() prevented my error from happening.