本教程探讨了如何通过SQLModel和FastAPI异步地与SQLAlchemy合作。我们还将配置Alembic来处理数据库迁移。
本教程假定你有使用Docker的FastAPI和Postgres的工作经验。需要帮助来加速使用FastAPI、Postgres和Docker吗？请从以下资源开始。
项目设置
首先从fastapi-sqlmodel-alembicrepo中克隆基础项目。
$ git clone -b base https://github.com/testdrivenio/fastapi-sqlmodel-alembic
$ cd fastapi-sqlmodel-alembic
从项目根目录中，创建镜像并启动Docker容器。
$ docker-compose up -d --build
一旦构建完成，导航到http://localhost:8004/ping。你应该看到。
在继续前行之前，先快速浏览一下项目结构。
接下来，让我们添加SQLModel，这是一个用于从Python代码中与SQL数据库交互的库，有Python对象。基于Python的类型注解，它本质上是pydantic和SQLAlchemy之上的一个封装器，使得与两者的工作变得容易。
我们还需要Psycopg。
将这两个依赖项添加到project/requirements.txt中。
fastapi==0.68.1
psycopg2-binary==2.9.1
sqlmodel==0.0.4
uvicorn==0.15.0
在 "project/app "中创建两个新文件，db.py和models.py。
project/app/models.py。
from sqlmodel import SQLModel, Field
class SongBase(SQLModel):
name: str
artist: str
class Song(SongBase, table=True):
id: int = Field(default=None, primary_key=True)
class SongCreate(SongBase):
pass
在这里，我们定义了三个模型。
SongBase是基础模型，其他的模型继承自此。它有两个属性， 和 ，都是字符串。这是一个仅有数据的模型，因为它缺少 ，这意味着它仅作为一个语义模型使用。nameartisttable=TrueSong同时，在基础模型中添加了一个id属性。这是一个表模型，所以它是一个pydantic和SQLAlchemy模型。它代表了一个数据库表。SongCreate是一个仅有数据的pydantic模型，它将被用来创建新的歌曲实例。
project/app/db.py。
import os
from sqlmodel import create_engine, SQLModel, Session
DATABASE_URL = os.environ.get("DATABASE_URL")
engine = create_engine(DATABASE_URL, echo=True)
def init_db():
SQLModel.metadata.create_all(engine)
def get_session():
with Session(engine) as session:
yield session
在这里，我们
- 使用来自SQLModel的
create_engine，初始化了一个新的SQLAlchemy引擎。SQLModel的create_engine和SQLAlchemy的版本之间的主要区别是，SQLModel版本增加了类型注释（用于支持编辑器），并启用了SQLAlchemy "2.0 "风格的引擎和连接。此外，我们还传入了echo=True，因此我们可以在终端看到生成的SQL查询。在开发模式下启用这个功能总是很好的，可以达到调试的目的。 - 创建了一个SQLAlchemy会话。
接下来，在project/app/main.py中，让我们在启动时使用启动事件创建表。
from fastapi import FastAPI
from app.db import init_db
from app.models import Song
app = FastAPI()
@app.on_event("startup")
def on_startup():
init_db()
@app.get("/ping")
async def pong():
return {"ping": "pong!"}
值得注意的是，from app.models import Song 是必需的。没有它，歌曲表将不会被创建。
为了测试，把旧的容器和卷关闭，重建镜像，然后启动新的容器。
$ docker-compose down -v
$ docker-compose up -d --build
通过docker-compose logs web 打开容器的日志。你应该看到。
web_1 | CREATE TABLE song (
web_1 | name VARCHAR NOT NULL,
web_1 | artist VARCHAR NOT NULL,
web_1 | id SERIAL,
web_1 | PRIMARY KEY (id)
web_1 | )
打开psql。
$ docker-compose exec db psql --username=postgres --dbname=foo
psql (13.4 (Debian 13.4-1.pgdg100+1))
Type "help" for help.
foo=# \dt
List of relations
Schema | Name | Type | Owner
--------+------+-------+----------
public | song | table | postgres
(1 row)
foo=# \q
随着表的建立，让我们在project/app/main.py中添加一些新的路由。
from fastapi import Depends, FastAPI
from sqlalchemy import select
from sqlmodel import Session
from app.db import get_session, init_db
from app.models import Song, SongCreate
app = FastAPI()
@app.on_event("startup")
def on_startup():
init_db()
@app.get("/ping")
async def pong():
return {"ping": "pong!"}
@app.get("/songs", response_model=list[Song])
def get_songs(session: Session = Depends(get_session)):
result = session.execute(select(Song))
songs = result.scalars().all()
return [Song(name=song.name, artist=song.artist, id=song.id) for song in songs]
@app.post("/songs")
def add_song(song: SongCreate, session: Session = Depends(get_session)):
song = Song(name=song.name, artist=song.artist)
session.add(song)
session.commit()
session.refresh(song)
return song
添加一首歌曲。
$ curl -d '{"name":"Midnight Fit", "artist":"Mogwai"}' -H "Content-Type: application/json" -X POST http://localhost:8004/songs
{
"id": 1,
"name": "Midnight Fit",
"artist": "Mogwai"
}
在你的浏览器中，导航到http://localhost:8004/songs。你应该看到。
{
"id": 1,
"name": "Midnight Fit",
"artist": "Mogwai"
}
异步SQLModel
继续，让我们为SQLModel添加异步支持。
首先，关闭容器和卷。
更新docker-compose.yml中的数据库URI，加入+asyncpg 。
接下来，用asyncpg替换Psycopg。
asyncpg==0.24.0
fastapi==0.68.1
sqlmodel==0.0.4
uvicorn==0.15.0
更新project/app/db.py：以使用SQLAlchemy的引擎和会话的异步风味。
import os
from sqlmodel import SQLModel
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
DATABASE_URL = os.environ.get("DATABASE_URL")
engine = create_async_engine(DATABASE_URL, echo=True, future=True)
async def init_db():
async with engine.begin() as conn:
# await conn.run_sync(SQLModel.metadata.drop_all)
await conn.run_sync(SQLModel.metadata.create_all)
async def get_session() -> AsyncSession:
async_session = sessionmaker(
engine, class_=AsyncSession, expire_on_commit=False
)
async with async_session() as session:
yield session
注意。
- 我们使用了SQLAlchemy结构--例如create_async_engine和AsyncSession--因为SQLModel在编写时并没有对它们进行封装。
- 我们通过传入
expire_on_commit=False...来禁用过期提交行为。 metadata.create_all我们使用run_sync来在异步函数中同步执行它。
在project/app/main.py中把on_startup 变成一个异步函数。
@app.on_event("startup")
async def on_startup():
await init_db()
就这样了。重新构建镜像并启动容器。
$ docker-compose up -d --build
确保表被创建。
最后，更新project/app/main.py中的路由处理程序以使用异步执行。
from fastapi import Depends, FastAPI
from sqlalchemy.future import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.db import get_session, init_db
from app.models import Song, SongCreate
app = FastAPI()
@app.on_event("startup")
async def on_startup():
await init_db()
@app.get("/ping")
async def pong():
return {"ping": "pong!"}
@app.get("/songs", response_model=list[Song])
async def get_songs(session: AsyncSession = Depends(get_session)):
result = await session.execute(select(Song))
songs = result.scalars().all()
return [Song(name=song.name, artist=song.artist, id=song.id) for song in songs]
@app.post("/songs")
async def add_song(song: SongCreate, session: AsyncSession = Depends(get_session)):
song = Song(name=song.name, artist=song.artist)
session.add(song)
await session.commit()
await session.refresh(song)
return song
添加一首新歌，并确保http://localhost:8004/songs，如预期的那样工作。
最后，让我们把Alembic添加到组合中，以正确处理数据库模式变化。
把它添加到需求文件中。
alembic==1.7.1
asyncpg==0.24.0
fastapi==0.68.1
sqlmodel==0.0.4
uvicorn==0.15.0
从project/app/main.py中删除启动事件，因为我们不再需要在启动时创建表。
@app.on_event("startup")
async def on_startup():
await init_db()
再次，关闭现有的容器和卷。
把容器转回来。
$ docker-compose up -d --build
在构建新镜像时，快速浏览一下《使用Asyncio与Alembic》。
一旦容器恢复了，就用异步模板初始化Alembic。
$ docker-compose exec web alembic init -t async migrations
在生成的 "project/migrations "文件夹中，将SQLModel导入script.py.mako，一个Mako模板文件。
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from alembic import op
import sqlalchemy as sa
import sqlmodel # NEW
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
branch_labels = ${repr(branch_labels)}
depends_on = ${repr(depends_on)}
def upgrade():
${upgrades if upgrades else "pass"}
def downgrade():
${downgrades if downgrades else "pass"}
现在，当一个新的迁移文件被生成时，它将包括import sqlmodel 。
接下来，我们需要像这样更新project/migrations/env.py的顶部。
import asyncio
from logging.config import fileConfig
from sqlalchemy import engine_from_config
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import AsyncEngine
from sqlmodel import SQLModel # NEW
from alembic import context
from app.models import Song # NEW
# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config
# Interpret the config file for Python logging.
# This line sets up loggers basically.
fileConfig(config.config_file_name)
# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = SQLModel.metadata # UPDATED
# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.
...
这里，我们导入了SQLModel和我们的歌曲模型。然后我们将target_metadata 设置为我们模型的MetaData，SQLModel.metadata 。关于target_metadata 这个参数的更多信息，请查看Alembic官方文档中的自动生成迁移功能。
在project/alembic.ini中更新sqlalchemy.url 。
sqlalchemy.url = postgresql+asyncpg://postgres:postgres@db:5432/foo
要生成第一个迁移文件，请运行。
$ docker-compose exec web alembic revision --autogenerate -m "init"
如果一切顺利，你应该在 "project/migrations/versions "中看到一个新的迁移文件，看起来像这样。
"""init
Revision ID: f9c634db477d
Revises:
Create Date: 2021-09-10 00:24:32.718895
"""
from alembic import op
import sqlalchemy as sa
import sqlmodel
# revision identifiers, used by Alembic.
revision = 'f9c634db477d'
down_revision = None
branch_labels = None
depends_on = None
def upgrade():
# ### commands auto generated by Alembic - please adjust! ###
op.create_table('song',
sa.Column('name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column('artist', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column('id', sa.Integer(), nullable=True),
sa.PrimaryKeyConstraint('id')
)
op.create_index(op.f('ix_song_artist'), 'song', ['artist'], unique=False)
op.create_index(op.f('ix_song_id'), 'song', ['id'], unique=False)
op.create_index(op.f('ix_song_name'), 'song', ['name'], unique=False)
# ### end Alembic commands ###
def downgrade():
# ### commands auto generated by Alembic - please adjust! ###
op.drop_index(op.f('ix_song_name'), table_name='song')
op.drop_index(op.f('ix_song_id'), table_name='song')
op.drop_index(op.f('ix_song_artist'), table_name='song')
op.drop_table('song')
# ### end Alembic commands ###
应用迁移。
$ docker-compose exec web alembic upgrade head
确保你可以添加一首歌曲。
让我们快速测试一下模式的变化。更新project/app/models.py中的SongBase 模型。
class SongBase(SQLModel):
name: str
artist: str
year: Optional[int] = None
不要忘记导入。
创建一个新的迁移文件。
$ docker-compose exec web alembic revision --autogenerate -m "add year"
像这样更新自动生成的迁移文件中的upgrade 和downgrade 函数。
def upgrade():
# ### commands auto generated by Alembic - please adjust! ###
op.add_column('song', sa.Column('year', sa.Integer(), nullable=True))
op.create_index(op.f('ix_song_year'), 'song', ['year'], unique=False)
# ### end Alembic commands ###
def downgrade():
# ### commands auto generated by Alembic - please adjust! ###
op.drop_index(op.f('ix_song_year'), table_name='song')
op.drop_column('song', 'year')
# ### end Alembic commands ###
应用迁移。
$ docker-compose exec web alembic upgrade head
更新路由处理程序。
@app.get("/songs", response_model=list[Song])
async def get_songs(session: AsyncSession = Depends(get_session)):
result = await session.execute(select(Song))
songs = result.scalars().all()
return [Song(name=song.name, artist=song.artist, year=song.year, id=song.id) for song in songs]
@app.post("/songs")
async def add_song(song: SongCreate, session: AsyncSession = Depends(get_session)):
song = Song(name=song.name, artist=song.artist, year=song.year)
session.add(song)
await session.commit()
await session.refresh(song)
return song
测试。
$ curl -d '{"name":"Midnight Fit", "artist":"Mogwai", "year":"2021"}' -H "Content-Type: application/json" -X POST http://localhost:8004/songs
结语
在本教程中，我们介绍了如何配置SQLAlchemy、SQLModel和Alembic，以便与FastAPI异步工作。
如果你正在寻找更多的挑战，请查看我们所有的FastAPI教程和课程。
你可以在fastapi-sqlmodel-alembicrepo中找到源代码。干杯!
