[tutorial] Many-to-many relationship commit works w/o session.add

[UncleGoogle]

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, Relationship, Session, SQLModel, create_engine, select


class HeroTeamLink(SQLModel, table=True):
    team_id: int = Field(primary_key=True, foreign_key="team.id")
    hero_id: int = Field(primary_key=True, foreign_key="hero.id")


class Team(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    headquarters: str

    heroes: list["Hero"] = Relationship(back_populates="teams", link_model=HeroTeamLink)


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)

    teams: list[Team] = Relationship(back_populates="heroes", link_model=HeroTeamLink)


sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

engine = create_engine(sqlite_url, echo=True)


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


def create_heroes():
    team_preventers = Team(name="Preventers", headquarters="Shart Tower")
    team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")

    hero_deadpond = Hero(  # noqa
        name="Deadpond",
        secret_name="Dive Wilson",
        teams=[team_preventers, team_z_force],
    )
    hero_rusty_man = Hero(  # noqa
        name="Rusty Man", secret_name="Tommy Sharp", teams=[team_preventers]
    )
    hero_spider_boy = Hero(  # noqa
        name="Spider-Boy", secret_name="Pedro Parqueador", teams=[team_preventers]
    )

    with Session(engine) as session:
        session.add(team_preventers)
        session.commit()

def update_heroes():
    with Session(engine) as session:
        hero_spider_boy = session.exec(
            select(Hero).where(Hero.name == "Spider-Boy")
        ).one()
        team_z_force = session.exec(select(Team).where(Team.name == "Z-Force")).one()
        hero_spider_boy.teams.append(team_z_force)
        print("-0---------")
        # looks like this `add` is not needed at all
        # session.add(team_z_force)
        session.commit()
        print("-0---------")

        session.refresh(hero_spider_boy)
        print(hero_spider_boy.teams)
        print(team_z_force.heroes)

    with Session(engine) as session:
        hero_spider_boy = session.exec(
            select(Hero).where(Hero.name == "Spider-Boy")
        ).one()
        print("spider boy teams", hero_spider_boy.teams)

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


if __name__ == "__main__":
    main()

Description

In the tutorial there is a sentence:

Notice that we only add Z-Force to the session, then we commit.

When I tested this, it looks like removing session.add(team_z_force) also works as expected. Why is that?

---- UPDATE after short reserarch

I found that (from sqlalchemy perspective):

hero_spider_boy and team_z_force are loaded into the session using the select() statement. When we append team_z_force to hero_spider_boy.teams, SQLAlchemy detects this change and will include it in the next commit() operation.

is the above sentence true?

Operating System

Linux

Operating System Details

No response

SQLModel Version

0.0.16

Python Version

3.12.2

Additional Context

No response