Mistake in the "Update Data" documentation section

[Danstiv]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from sqlmodel import Field, Session, SQLModel, create_engine, select


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    secret_name: str
    age: int | None = Field(default=None, index=True)


sqlite_file_name = ""
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True-1)


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


def create_heroes():
    hero = Hero(name="Captain North America", secret_name="Esteban Rogelios", age=93)
    with Session(engine) as session:
        session.add(hero)
        session.commit()


def update_heroes():
    with Session(engine) as session:
        statement = select(Hero).where(Hero.name == "Captain North America")
        results = session.exec(statement)
        hero = results.one()
        print("Hero:", hero)
        hero.name = "Captain North America Except Canada"
        hero.age = 110
        # No session.add here!
        session.commit()
        session.refresh(hero)
        print("Updated hero:", hero)


def main():
    create_db_and_tables()
    create_heroes()
    update_heroes()


if __name__ == "__main__":
    main()

# Output
# Hero: age=93 name='Captain North America' secret_name='Esteban Rogelios' id=1                                                                                                                                    
# Updated hero: age=110 name='Captain North America Except Canada' secret_name='Esteban Rogelios' id=1

Description

The documentation contains the following statement:

Now that the hero object in memory has a change, in this case a new value for the age, we need to add it to the session.

But the sqlalchemy documentation says the following:

In the preceding section Using UPDATE and DELETE Statements, we introduced the Update construct that represents a SQL UPDATE statement. When using the ORM, there are two ways in which this construct is used. The primary way is that it is emitted automatically as part of the unit of work process used by the Session, where an UPDATE statement is emitted on a per-primary key basis corresponding to individual objects that have changes on them.
Supposing we loaded the User object for the username sandy into a transaction (also showing off the Select.filter_by() method as well as the Result.scalar_one() method):

>>> sandy = session.execute(select(User).filter_by(name="sandy")).scalar_one()
...

The Python object sandy as mentioned before acts as a proxy for the row in the database, more specifically the database row in terms of the current transaction, that has the primary key identity of 2:
...
If we alter the attributes of this object, the Session tracks this change:

>>> sandy.fullname = "Sandy Squirrel"

The object appears in a collection called Session.dirty, indicating the object is “dirty”:

>>> sandy in session.dirty
True

When the Session next emits a flush, an UPDATE will be emitted that updates this value in the database.

Thus, it turns out that re-adding the updated instance to the session is not required.

Just in case, I copied the code from the documentation and checked the behavior in the in memory database, the rows are updated regardless of whether add is called after changing the attributes.

Operating System

Windows

Operating System Details

Windows 11 23H2 (AMD64) build 22631.3296

SQLModel Version

0.0.16

Python Version

Python 3.12.0

Additional Context

SQLModel documentation link: https://sqlmodel.tiangolo.com/tutorial/update/

SQLAlchemy documentation link: https://docs.sqlalchemy.org/en/20/tutorial/orm_data_manipulation.html#updating-orm-objects-using-the-unit-of-work-pattern

[RanaUniverse]

so please say me i am using sqlmodel, i have not idea of sqlalchemy codes 😅

when i search a row instance and want to change the data, should i need to use session.add() or not .
will it cause any cpu usage problem