docs: Add AsyncSession and async tools tutorial (#626)

[alexbthundiyil-spec]

Fixes #626. Adds comprehensive tutorial documentation for using SQLModel with async engines and FastAPI async dependencies.

[mahdirajaee]

The tutorial is a useful addition, but there are a few technical issues worth addressing. First, the variable name sqlite_url is misleading when it holds a PostgreSQL connection string ("postgresql+asyncpg://..."). This will confuse readers following along — should be renamed to something like database_url or async_url. Second, the create_heroes function calls session.commit() and session.refresh() but has no error handling — an async tutorial should ideally demonstrate try/except with rollback, or at minimum mention that exceptions during commit leave the session in a broken state and need await session.rollback().

Third, the FastAPI integration example references engine and Hero without imports or definitions, which means it won't run as-is. Since this is a tutorial, each code block should either be self-contained or clearly reference the earlier block. Finally, the get_session dependency yields a session but doesn't show what happens on exception — FastAPI's dependency injection will call session.close() via the generator cleanup, but session.rollback() on error is a common pattern that's worth showing for write operations. The read-only example is fine as a starting point, but a note about write endpoints needing explicit rollback handling would round this out.

[alexbthundiyil-spec]

Thanks for the feedback! I've addressed all the points:

1. Renamed sqlite_url to async_url since it's a Postgres connection.
2. Added try/except with await session.rollback() to the create_heroes function.
3. Updated the FastAPI integration block to be fully self-contained (added the imports, the model definition, and engine initialization).
4. Added a POST endpoint to the FastAPI example to explicitly demonstrate the session.rollback() pattern during write operations.

Let me know if there's anything else you'd like me to tweak!

[eternal-sorrow]

except Exception is almost always bad code. You should catch specific exceptions. In this case probably sqlalchemy.exc.DBAPIError.

[svlandeg]

Hi @alexbthundiyil-spec, all,

Thanks for the contribution 🙏

We've discussed this internally and decided that we prefer to write the first draft of this new documentation section ourselves. We are now tracking this on our internal TODO list. We'll go ahead and close this one in the meantime.