Update doc for SQLALchemy2 adapter

docs/configuration/authentication/strategies/database.md

@@ -29,7 +29,7 @@ It is structured like this:
 
 === "SQLAlchemy"
 
-    ```py hl_lines="4-7 10 21-22 31 38-39"
+    ```py hl_lines="5-8 13 23-24 45-46"
     --8<-- "docs/src/db_sqlalchemy_access_tokens.py"
     ```
 

docs/configuration/databases/sqlalchemy.md

@@ -1,22 +1,16 @@
 # SQLAlchemy
 
-**FastAPI Users** provides the necessary tools to work with SQL databases thanks to [SQLAlchemy Core](https://docs.sqlalchemy.org/en/13/core/) and [encode/databases](https://www.encode.io/databases/) package for full async support.
+**FastAPI Users** provides the necessary tools to work with SQL databases thanks to [SQLAlchemy ORM with asyncio](https://docs.sqlalchemy.org/en/14/orm/extensions/asyncio.html).
 
-## Installation
+!!! warning
+    The previous adapter using `encode/databases` is now deprecated but can still be installed using `fastapi-users[sqlalchemy]`.
 
-Install the database driver that corresponds to your DBMS:
+## Asynchronous driver
 
-```sh
-pip install 'databases[postgresql]'
-```
+To work with your DBMS, you'll need to install the corresponding asyncio driver. The common choices are:
 
-```sh
-pip install 'databases[mysql]'
-```
-
-```sh
-pip install 'databases[sqlite]'
-```
+* For PostgreSQL: `pip install asyncpg`
+* For SQLite: `pip install aiosqlite`
 
 For the sake of this tutorial from now on, we'll use a simple SQLite databse.
 
@@ -24,20 +18,22 @@ For the sake of this tutorial from now on, we'll use a simple SQLite databse.
 
 Let's declare our SQLAlchemy `User` table.
 
-```py hl_lines="13 14"
+```py hl_lines="15 16"
 --8<-- "docs/src/db_sqlalchemy.py"
 ```
 
 As you can see, **FastAPI Users** provides a mixin that will include base fields for our `User` table. You can of course add you own fields there to fit to your needs!
 
-## Create the tables
+## Implement a function to create the tables
 
-We'll now create an SQLAlchemy engine and ask it to create all the defined tables.
+We'll now create an utility function to create all the defined tables.
 
-```py hl_lines="17 18 19 20"
+```py hl_lines="23-25"
 --8<-- "docs/src/db_sqlalchemy.py"
 ```
 
+This function can be called, for example, during the initialization of your FastAPI app.
+
 !!! warning
     In production, it's strongly recommended to setup a migration system to update your SQL schemas. See [Alembic](https://alembic.sqlalchemy.org/en/latest/).
 
@@ -45,16 +41,14 @@ We'll now create an SQLAlchemy engine and ask it to create all the defined table
 
 The database adapter of **FastAPI Users** makes the link between your database configuration and the users logic. It should be generated by a FastAPI dependency.
 
-```py hl_lines="25 26"
+```py hl_lines="28-34"
 --8<-- "docs/src/db_sqlalchemy.py"
 ```
 
-Notice that we pass it three things:
+Notice that we define first a `get_async_session` dependency returning us a fresh SQLAlchemy session to interact with the database.
+
+It's then used inside the `get_user_db` dependency to generate our adapter. Notice that we pass it three things:
 
 * A reference to your [`UserDB` model](../models.md).
-* A `database` instance, which allows us to do asynchronous request to the database.
-* The `users` variable, which is the actual SQLAlchemy table behind the table class.
-
-## What about SQLAlchemy ORM?
-
-The primary objective was to use pure async approach as much as possible. However, we understand that ORM is convenient and useful for many developers. If this feature becomes very demanded, we will add a database adapter for SQLAlchemy ORM.
+* The `session` instance we just injected.
+* The `UserTable` variable, which is the actual SQLAlchemy model.

docs/configuration/oauth.md

@@ -7,7 +7,7 @@ FastAPI Users provides an optional OAuth2 authentication support. It relies on [
 You should install the library with the optional dependencies for OAuth:
 
 ```sh
-pip install 'fastapi-users[sqlalchemy,oauth]'
+pip install 'fastapi-users[sqlalchemy2,oauth]'
 ```
 
 ```sh
@@ -68,15 +68,17 @@ Notice that we inherit from the `BaseOAuthAccountMixin`, which adds a `List` of
 
 #### SQLAlchemy
 
-You'll need to define the table for storing the OAuth account model. We provide a base one for this:
+You'll need to define the SQLAlchemy model for storing OAuth accounts. We provide a base one for this:
 
-```py hl_lines="21 22"
+```py hl_lines="19-24"
 --8<-- "docs/src/db_sqlalchemy_oauth.py"
 ```
 
-When instantiating the database adapter, you should pass this table in argument::
+Notice that we also manually added a `relationship` on the `UserTable` so that SQLAlchemy can properly retrieve the OAuth accounts of the user.
 
-```py hl_lines="31 34 35"
+When instantiating the database adapter, you should pass this SQLAlchemy model:
+
+```py hl_lines="41-42"
 --8<-- "docs/src/db_sqlalchemy_oauth.py"
 ```
 

docs/installation.md

@@ -5,7 +5,7 @@ You can add **FastAPI Users** to your FastAPI project in a few easy steps. First
 ## With SQLAlchemy support
 
 ```sh
-pip install 'fastapi-users[sqlalchemy]'
+pip install 'fastapi-users[sqlalchemy2]'
 ```
 
 ## With MongoDB support

docs/src/db_sqlalchemy.py

@@ -1,12 +1,14 @@
-import databases
-import sqlalchemy
+from typing import AsyncGenerator
+
+from fastapi import Depends
 from fastapi_users.db import SQLAlchemyBaseUserTable, SQLAlchemyUserDatabase
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
 from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
+from sqlalchemy.orm import sessionmaker
 
 from .models import UserDB
 
-DATABASE_URL = "sqlite:///./test.db"
-database = databases.Database(DATABASE_URL)
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
 Base: DeclarativeMeta = declarative_base()
 
 
@@ -14,13 +16,19 @@ class UserTable(Base, SQLAlchemyBaseUserTable):
     pass
 
 
-engine = sqlalchemy.create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-Base.metadata.create_all(engine)
-
-users = UserTable.__table__
+engine = create_async_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
 
 
-async def get_user_db():
-    yield SQLAlchemyUserDatabase(UserDB, database, users)
+async def create_db_and_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyUserDatabase(UserDB, session, UserTable)

docs/src/db_sqlalchemy_access_tokens.py

@@ -1,16 +1,18 @@
-import databases
-import sqlalchemy
+from typing import AsyncGenerator
+
+from fastapi import Depends
 from fastapi_users.db import SQLAlchemyBaseUserTable, SQLAlchemyUserDatabase
 from fastapi_users_db_sqlalchemy.access_token import (
     SQLAlchemyAccessTokenDatabase,
     SQLAlchemyBaseAccessTokenTable,
 )
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
 from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
+from sqlalchemy.orm import sessionmaker
 
 from .models import AccessToken, UserDB
 
-DATABASE_URL = "sqlite:///./test.db"
-database = databases.Database(DATABASE_URL)
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
 Base: DeclarativeMeta = declarative_base()
 
 
@@ -22,18 +24,23 @@ class AccessTokenTable(SQLAlchemyBaseAccessTokenTable, Base):
     pass
 
 
-engine = sqlalchemy.create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-Base.metadata.create_all(engine)
-
-users = UserTable.__table__
-access_tokens = AccessTokenTable.__table__
+engine = create_async_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
 
 
-async def get_user_db():
-    yield SQLAlchemyUserDatabase(UserDB, database, users)
+async def create_db_and_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
 
 
-async def get_access_token_db():
-    yield SQLAlchemyAccessTokenDatabase(AccessToken, database, access_tokens)
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyUserDatabase(UserDB, session, UserTable)
+
+
+async def get_access_token_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyAccessTokenDatabase(AccessToken, session, AccessTokenTable)

docs/src/db_sqlalchemy_oauth.py

@@ -1,35 +1,42 @@
-import databases
-import sqlalchemy
+from typing import AsyncGenerator
+
+from fastapi import Depends
 from fastapi_users.db import (
     SQLAlchemyBaseOAuthAccountTable,
     SQLAlchemyBaseUserTable,
     SQLAlchemyUserDatabase,
 )
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
 from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
+from sqlalchemy.orm import relationship, sessionmaker
 
 from .models import UserDB
 
-DATABASE_URL = "sqlite:///./test.db"
-database = databases.Database(DATABASE_URL)
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
 Base: DeclarativeMeta = declarative_base()
 
 
 class UserTable(Base, SQLAlchemyBaseUserTable):
+    oauth_accounts = relationship("OAuthAccount")
+
+
+class OAuthAccountTable(SQLAlchemyBaseOAuthAccountTable, Base):
     pass
 
 
-class OAuthAccount(SQLAlchemyBaseOAuthAccountTable, Base):
-    pass
+engine = create_async_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
 
 
-engine = sqlalchemy.create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-Base.metadata.create_all(engine)
-
-users = UserTable.__table__
-oauth_accounts = OAuthAccount.__table__
+async def create_db_and_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
 
 
-async def get_user_db():
-    yield SQLAlchemyUserDatabase(UserDB, database, users, oauth_accounts)
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyUserDatabase(UserDB, session, UserTable, OAuthAccountTable)

examples/sqlalchemy-oauth/app/db.py

@@ -1,35 +1,42 @@
-import databases
-import sqlalchemy
+from typing import AsyncGenerator
+
+from fastapi import Depends
 from fastapi_users.db import (
     SQLAlchemyBaseOAuthAccountTable,
     SQLAlchemyBaseUserTable,
     SQLAlchemyUserDatabase,
 )
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
 from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
+from sqlalchemy.orm import relationship, sessionmaker
 
 from app.models import UserDB
 
-DATABASE_URL = "sqlite:///./test.db"
-database = databases.Database(DATABASE_URL)
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
 Base: DeclarativeMeta = declarative_base()
 
 
 class UserTable(Base, SQLAlchemyBaseUserTable):
+    oauth_accounts = relationship("OAuthAccount")
+
+
+class OAuthAccountTable(SQLAlchemyBaseOAuthAccountTable, Base):
     pass
 
 
-class OAuthAccount(SQLAlchemyBaseOAuthAccountTable, Base):
-    pass
+engine = create_async_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
 
 
-engine = sqlalchemy.create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-Base.metadata.create_all(engine)
-
-users = UserTable.__table__
-oauth_accounts = OAuthAccount.__table__
+async def create_db_and_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
 
 
-async def get_user_db():
-    yield SQLAlchemyUserDatabase(UserDB, database, users, oauth_accounts)
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyUserDatabase(UserDB, session, UserTable, OAuthAccountTable)

examples/sqlalchemy/app/db.py

@@ -1,12 +1,14 @@
-import databases
-import sqlalchemy
+from typing import AsyncGenerator
+
+from fastapi import Depends
 from fastapi_users.db import SQLAlchemyBaseUserTable, SQLAlchemyUserDatabase
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
 from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
+from sqlalchemy.orm import sessionmaker
 
 from app.models import UserDB
 
-DATABASE_URL = "sqlite:///./test.db"
-database = databases.Database(DATABASE_URL)
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
 Base: DeclarativeMeta = declarative_base()
 
 
@@ -14,13 +16,19 @@ class UserTable(Base, SQLAlchemyBaseUserTable):
     pass
 
 
-engine = sqlalchemy.create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-Base.metadata.create_all(engine)
-
-users = UserTable.__table__
+engine = create_async_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
 
 
-async def get_user_db():
-    yield SQLAlchemyUserDatabase(UserDB, database, users)
+async def create_db_and_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+
+async def get_user_db(session: AsyncSession = Depends(get_async_session)):
+    yield SQLAlchemyUserDatabase(UserDB, session, UserTable)

pyproject.toml

@@ -34,7 +34,10 @@ requires = [
 
 [tool.flit.metadata.requires-extra]
 sqlalchemy = [
-    "fastapi-users-db-sqlalchemy >=1.1.0",
+    "fastapi-users-db-sqlalchemy >=1.1.0,<2.0.0",
+]
+sqlalchemy2 = [
+    "fastapi-users-db-sqlalchemy >=2.0.0",
 ]
 mongodb = [
     "fastapi-users-db-mongodb >=1.1.0",