diff --git a/docs/configuration/authentication/strategies/database.md b/docs/configuration/authentication/strategies/database.md index 85667de2..635e620a 100644 --- a/docs/configuration/authentication/strategies/database.md +++ b/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" ``` diff --git a/docs/configuration/databases/sqlalchemy.md b/docs/configuration/databases/sqlalchemy.md index 262bdcc6..ccfc6d36 100644 --- a/docs/configuration/databases/sqlalchemy.md +++ b/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. diff --git a/docs/configuration/oauth.md b/docs/configuration/oauth.md index c08085ad..e6ce5bcc 100644 --- a/docs/configuration/oauth.md +++ b/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" ``` diff --git a/docs/installation.md b/docs/installation.md index d60712fd..e7e41ae0 100644 --- a/docs/installation.md +++ b/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 diff --git a/docs/src/db_sqlalchemy.py b/docs/src/db_sqlalchemy.py index aae20014..04302c1d 100644 --- a/docs/src/db_sqlalchemy.py +++ b/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) diff --git a/docs/src/db_sqlalchemy_access_tokens.py b/docs/src/db_sqlalchemy_access_tokens.py index 3e4955c2..2c77a178 100644 --- a/docs/src/db_sqlalchemy_access_tokens.py +++ b/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) diff --git a/docs/src/db_sqlalchemy_oauth.py b/docs/src/db_sqlalchemy_oauth.py index 0b0222d7..acbb2eb5 100644 --- a/docs/src/db_sqlalchemy_oauth.py +++ b/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) diff --git a/examples/sqlalchemy-oauth/app/db.py b/examples/sqlalchemy-oauth/app/db.py index c9604b75..4afdcf2c 100644 --- a/examples/sqlalchemy-oauth/app/db.py +++ b/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) diff --git a/examples/sqlalchemy/app/db.py b/examples/sqlalchemy/app/db.py index 5f70da69..cf5ab128 100644 --- a/examples/sqlalchemy/app/db.py +++ b/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) diff --git a/pyproject.toml b/pyproject.toml index 4a5f6ea7..f4927373 100644 --- a/pyproject.toml +++ b/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",