Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Sessions and Transactions

Object States, Flush, Expire and Refresh

Follow an ORM object through its life: transient, pending, persistent, detached. Learn flush vs commit, expire_on_commit, refresh, merge and DetachedInstanceError.

Every mapped object is in one of a handful of states relative to a session. Knowing them explains error messages such as DetachedInstanceError, tells you why an attribute is suddenly None or triggers a query, and shows when you need refresh() or merge().

The five states

State Meaning How you get there
Transient A plain object, no session, no row User(name="Ada")
Pending Added to a session, INSERT not sent yet session.add(user)
Persistent In a session and has a database row after flush, or loaded by a query
Deleted Marked for delete, flushed but the transaction is open session.delete(user) then flush
Detached Has a row but its session is gone session.close(), expunge(), or commit with a closed session
stateDiagram-v2
    [*] --> Transient: create object
    Transient --> Pending: add()
    Pending --> Persistent: flush
    Persistent --> Deleted: delete() + flush
    Deleted --> Detached: commit
    Persistent --> Detached: close() or expunge()
    Detached --> Persistent: add() again

The life cycle of a mapped object. sqlalchemy.inspect(obj) tells you where an object is right now.

Inspecting state

Python Watch an object change state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last step is the classic DetachedInstanceError. After commit() every attribute was expired. After close() the object lost its session, so SQLAlchemy cannot reload name. There are three standard fixes: keep the session open while you use the object, copy the data you need into plain values (or a Pydantic/dataclass) before closing, or set expire_on_commit=False on the session.

flush versus commit

Flush sends pending SQL inside the current transaction. The database now has the rows (visible to your own connection), the objects get their primary keys and defaults, but nothing is permanent. Commit flushes first, then ends the transaction so everyone can see the changes.

Calling flush() yourself is useful when you need a generated id before commit, for instance to create a child by id, and you can still rollback() afterwards.

Python flush gives ids, rollback discards them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Expire and refresh

An expired object has no loaded attribute values; the next access runs a SELECT for that row. Commit expires everything; you can also expire manually:

  • session.expire(obj) marks one object (or session.expire_all() all) as stale.
  • session.refresh(obj) reloads right now, overwriting in-memory values with the database's.
  • session.expunge(obj) removes an object from the session without touching the database.
Python refresh picks up changes made elsewhere

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

expire_on_commit=False keeps loaded values after commit. It is handy in web handlers that return objects after saving, but then you take responsibility for stale data.

merge: bring a detached object back

session.add(detached) re-attaches it. session.merge(obj) is different: it copies the state of obj onto the persistent object with the same primary key (loading it if necessary) and returns that persistent object. Use it for objects that arrive from outside, such as a cache, a form, or another session.

Python merge copies state onto the session's own object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

merge() overwrites loaded attributes with every attribute that is set on the incoming object. An attribute you never set is left alone, but one set to None overwrites the column with NULL. Build partial objects carefully.

Why autoflush matters

By default a query flushes pending changes first, so a select sees rows you just added. You can disable it for a block with with session.no_autoflush: when you build objects in a half-valid state, for instance when a validation query would otherwise flush an incomplete row.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. An object was created with User(name='x') but never added to a session. Which state is it in?

    A transient object has no session and no database row.
  2. 2. What is the difference between flush and commit?

    Flush writes within the transaction and can still be rolled back; commit ends the transaction.
  3. 3. You read user.name after session.close() and get DetachedInstanceError. What is a valid fix?

    The expired attribute cannot reload without a session. Load or copy values before closing, or keep values after commit.
  4. 4. What does session.refresh(obj) do?

    refresh issues a SELECT and overwrites the in-memory values with the row's current values.

Summary

  • Objects move through transient, pending, persistent, deleted and detached states; inspect(obj) shows which.
  • Flush writes inside the transaction; commit makes it permanent and expires all objects by default.
  • DetachedInstanceError means an expired attribute was read after the session closed.
  • expire, refresh and expunge control what the session remembers.
  • merge() copies an outside object's state onto the session's own instance.

Next: Transactions, Savepoints and Isolation