Browse Source
✨ SQLAlchemy ORM support Improved jsonable_encoder with SQLAlchemy support, tests running with SQLite, improved and updated SQL docs * ➕ Add SQLAlchemy to development dependencies (not required for using FastAPI) * ➕ Add sqlalchemy to testing dependencies (not required to use FastAPI)pull/34/head
Sebastián Ramírez
6 years ago
committed by
GitHub
GitHub
10 changed files with 338 additions and 109 deletions
|
After Width: | Height: | Size: 77 KiB |
@ -1,13 +1,15 @@ |
|||||
from fastapi import FastAPI |
from fastapi import FastAPI |
||||
|
|
||||
from sqlalchemy import Boolean, Column, Integer, String, create_engine |
from sqlalchemy import Boolean, Column, Integer, String, create_engine |
||||
from sqlalchemy.ext.declarative import declarative_base, declared_attr |
from sqlalchemy.ext.declarative import declarative_base, declared_attr |
||||
from sqlalchemy.orm import scoped_session, sessionmaker |
from sqlalchemy.orm import scoped_session, sessionmaker |
||||
|
|
||||
# SQLAlchemy specific code, as with any other app |
# SQLAlchemy specific code, as with any other app |
||||
SQLALCHEMY_DATABASE_URI = "postgresql://user:password@postgresserver/db" |
SQLALCHEMY_DATABASE_URI = "sqlite:///./test.db" |
||||
|
# SQLALCHEMY_DATABASE_URI = "postgresql://user:password@postgresserver/db" |
||||
|
|
||||
engine = create_engine(SQLALCHEMY_DATABASE_URI, convert_unicode=True) |
engine = create_engine( |
||||
|
SQLALCHEMY_DATABASE_URI, connect_args={"check_same_thread": False} |
||||
|
) |
||||
db_session = scoped_session( |
db_session = scoped_session( |
||||
sessionmaker(autocommit=False, autoflush=False, bind=engine) |
sessionmaker(autocommit=False, autoflush=False, bind=engine) |
||||
) |
) |
||||
@ -30,15 +32,25 @@ class User(Base): |
|||||
is_active = Column(Boolean(), default=True) |
is_active = Column(Boolean(), default=True) |
||||
|
|
||||
|
|
||||
def get_user(username, db_session): |
Base.metadata.create_all(bind=engine) |
||||
return db_session.query(User).filter(User.id == username).first() |
|
||||
|
first_user = db_session.query(User).first() |
||||
|
if not first_user: |
||||
|
u = User(email="[email protected]", hashed_password="notreallyhashed") |
||||
|
db_session.add(u) |
||||
|
db_session.commit() |
||||
|
|
||||
|
|
||||
|
# Utility |
||||
|
def get_user(db_session, user_id: int): |
||||
|
return db_session.query(User).filter(User.id == user_id).first() |
||||
|
|
||||
|
|
||||
# FastAPI specific code |
# FastAPI specific code |
||||
app = FastAPI() |
app = FastAPI() |
||||
|
|
||||
|
|
||||
@app.get("/users/{username}") |
@app.get("/users/{user_id}") |
||||
def read_user(username: str): |
def read_user(user_id: int): |
||||
user = get_user(username, db_session) |
user = get_user(db_session, user_id=user_id) |
||||
return user |
return user |
||||
|
|||||
@ -12,7 +12,9 @@ You can easily adapt it to any database supported by SQLAlchemy, like: |
|||||
* Oracle |
* Oracle |
||||
* Microsoft SQL Server, etc. |
* Microsoft SQL Server, etc. |
||||
|
|
||||
In this example, we'll use **PostgreSQL**. |
In this example, we'll use **SQLite**, because it uses a single file and Python has integrated support. So, you can copy this example and run it as is. |
||||
|
|
||||
|
Later, for your production application, you might want to use a database server like **PostgreSQL**. |
||||
|
|
||||
!!! note |
!!! note |
||||
Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework. |
Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework. |
||||
@ -23,30 +25,58 @@ In this example, we'll use **PostgreSQL**. |
|||||
|
|
||||
For now, don't pay attention to the rest, only the imports: |
For now, don't pay attention to the rest, only the imports: |
||||
|
|
||||
```Python hl_lines="3 4 5" |
```Python hl_lines="2 3 4" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
## Define the database |
## Define the database |
||||
|
|
||||
Define the database that SQLAlchemy should connect to: |
Define the database that SQLAlchemy should "connect" to: |
||||
|
|
||||
```Python hl_lines="8" |
```Python hl_lines="7" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
|
In this example, we are "connecting" to a SQLite database (opening a file with the SQLite database). |
||||
|
|
||||
|
The file will be located at the same directory in the file `test.db`. That's why the last part is `./test.db`. |
||||
|
|
||||
|
If you were using a **PostgreSQL** database instead, you would just have to uncomment the line: |
||||
|
|
||||
|
```Python |
||||
|
SQLALCHEMY_DATABASE_URI = "postgresql://user:password@postgresserver/db" |
||||
|
``` |
||||
|
|
||||
|
...and adapt it with your database data and credentials (equivalently for MySQL, MariaDB or any other). |
||||
|
|
||||
!!! tip |
!!! tip |
||||
This is the main line that you would have to modify if you wanted to use a different database than **PostgreSQL**. |
|
||||
|
This is the main line that you would have to modify if you wanted to use a different database. |
||||
|
|
||||
## Create the SQLAlchemy `engine` |
## Create the SQLAlchemy `engine` |
||||
|
|
||||
```Python hl_lines="10" |
```Python hl_lines="10 11 12" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
|
### Note |
||||
|
|
||||
|
The argument: |
||||
|
|
||||
|
```Python |
||||
|
connect_args={"check_same_thread": False} |
||||
|
``` |
||||
|
|
||||
|
...is needed only for `SQLite`. It's not needed for other databases. |
||||
|
|
||||
|
!!! info "Technical Details" |
||||
|
|
||||
|
That argument `check_same_thread` is there mainly to be able to run the tests that cover this example. |
||||
|
|
||||
|
|
||||
## Create a `scoped_session` |
## Create a `scoped_session` |
||||
|
|
||||
```Python hl_lines="11 12 13" |
```Python hl_lines="13 14 15" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
@ -55,9 +85,9 @@ Define the database that SQLAlchemy should connect to: |
|||||
|
|
||||
This `scoped_session` is a feature of SQLAlchemy. |
This `scoped_session` is a feature of SQLAlchemy. |
||||
|
|
||||
The resulting object, the `db_session` can then be used anywhere a a normal SQLAlchemy session. |
The resulting object, the `db_session` can then be used anywhere as a normal SQLAlchemy session. |
||||
|
|
||||
It can be used as a global because it is implemented to work independently on each "<abbr title="A sequence of code being executed by the program, while at the same time, or at intervals, there can be others being executed too.">thread</abbr>", so the actions you perform with it in one path operation function won't affect the actions performed (possibly concurrently) by other path operation functions. |
It can be used as a "global" variable because it is implemented to work independently on each "<abbr title="A sequence of code being executed by the program, while at the same time, or at intervals, there can be others being executed too.">thread</abbr>", so the actions you perform with it in one path operation function won't affect the actions performed (possibly concurrently) by other path operation functions. |
||||
|
|
||||
## Create a `CustomBase` model |
## Create a `CustomBase` model |
||||
|
|
||||
@ -65,17 +95,17 @@ This is more of a trick to facilitate your life than something required. |
|||||
|
|
||||
But by creating this `CustomBase` class and inheriting from it, your models will have automatic `__tablename__` attributes (that are required by SQLAlchemy). |
But by creating this `CustomBase` class and inheriting from it, your models will have automatic `__tablename__` attributes (that are required by SQLAlchemy). |
||||
|
|
||||
That way you don't have to declare them explicitly. |
That way you don't have to declare them explicitly in every model. |
||||
|
|
||||
So, your models will behave very similarly to, for example, Flask-SQLAlchemy. |
So, your models will behave very similarly to, for example, Flask-SQLAlchemy. |
||||
|
|
||||
```Python hl_lines="16 17 18 19 20" |
```Python hl_lines="18 19 20 21 22" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
## Create the SQLAlchemy `Base` model |
## Create the SQLAlchemy `Base` model |
||||
|
|
||||
```Python hl_lines="23" |
```Python hl_lines="25" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
@ -85,15 +115,36 @@ Now this is finally code specific to your app. |
|||||
|
|
||||
Here's a user model that will be a table in the database: |
Here's a user model that will be a table in the database: |
||||
|
|
||||
```Python hl_lines="26 27 28 29 30" |
```Python hl_lines="28 29 30 31 32" |
||||
|
{!./src/sql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
## Initialize your application |
||||
|
|
||||
|
In a very simplistic way, initialize your database (create the tables, etc) and make sure you have a first user: |
||||
|
|
||||
|
```Python hl_lines="35 37 38 39 40 41" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
|
### Note |
||||
|
|
||||
|
Normally you would probably initialize your database (create tables, etc) with <a href="https://alembic.sqlalchemy.org/en/latest/" target="_blank">Alembic</a>. |
||||
|
|
||||
|
And you would also use Alembic for migrations (that's its main job). For whenever you change the structure of your database, add a new column, a new table, etc. |
||||
|
|
||||
|
The same way, you would probably make sure there's a first user in an external script that runs before your application, or as part of the application startup. |
||||
|
|
||||
|
In this example we are doing those two operations in a very simple way, directly in the code, to focus on the main points. |
||||
|
|
||||
|
Also, as all the functionality is self-contained in the same code, you can copy it and run it directly, and it will work as is. |
||||
|
|
||||
|
|
||||
## Get a user |
## Get a user |
||||
|
|
||||
By creating a function that is only dedicated to getting your user from a `username` (or any other parameter) independent of your path operation function, you can more easily re-use it in multiple parts and also add <abbr title="Automated test, written in code, that checks if another piece of code is working correctly.">unit tests</abbr> for it: |
By creating a function that is only dedicated to getting your user from a `user_id` (or any other parameter) independent of your path operation function, you can more easily re-use it in multiple parts and also add <abbr title="Automated tests, written in code, that check if another piece of code is working correctly.">unit tests</abbr> for it: |
||||
|
|
||||
```Python hl_lines="33 34" |
```Python hl_lines="45 46" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
@ -103,7 +154,7 @@ Now, finally, here's the standard **FastAPI** code. |
|||||
|
|
||||
Create your app and path operation function: |
Create your app and path operation function: |
||||
|
|
||||
```Python hl_lines="38 41 42 43 44" |
```Python hl_lines="50 53 54 55 56" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
@ -113,25 +164,25 @@ We can just call `get_user` directly from inside of the path operation function |
|||||
|
|
||||
## Create the path operation function |
## Create the path operation function |
||||
|
|
||||
Here we are using SQLAlchemy code inside of the path operation function, and it in turn will go and communicate with an external database. |
Here we are using SQLAlchemy code inside of the path operation function, and in turn it will go and communicate with an external database. |
||||
|
|
||||
That could potentially require some "waiting". |
That could potentially require some "waiting". |
||||
|
|
||||
But as SQLAlchemy doesn't have compatibility for using `await`, as would be with something like: |
But as SQLAlchemy doesn't have compatibility for using `await` directly, as would be with something like: |
||||
|
|
||||
```Python |
```Python |
||||
user = await get_user(username, db_session) |
user = await get_user(db_session, user_id=user_id) |
||||
``` |
``` |
||||
|
|
||||
...and instead we are using: |
...and instead we are using: |
||||
|
|
||||
```Python |
```Python |
||||
user = get_user(username, db_session) |
user = get_user(db_session, user_id=user_id) |
||||
``` |
``` |
||||
|
|
||||
Then we should declare the path operation without `async def`, just with a normal `def`: |
Then we should declare the path operation without `async def`, just with a normal `def`: |
||||
|
|
||||
```Python hl_lines="42" |
```Python hl_lines="54" |
||||
{!./src/sql_databases/tutorial001.py!} |
{!./src/sql_databases/tutorial001.py!} |
||||
``` |
``` |
||||
|
|
||||
@ -140,3 +191,47 @@ Then we should declare the path operation without `async def`, just with a norma |
|||||
Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database <abbr title="Automatically updating the database to have any new column we define in our models.">migrations</abbr> with <a href="https://alembic.sqlalchemy.org" target="_blank">Alembic</a> directly. |
Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database <abbr title="Automatically updating the database to have any new column we define in our models.">migrations</abbr> with <a href="https://alembic.sqlalchemy.org" target="_blank">Alembic</a> directly. |
||||
|
|
||||
You would probably want to declare your database and models in a different file or set of files, this would allow Alembic to import it and use it without even needing to have **FastAPI** installed for the migrations. |
You would probably want to declare your database and models in a different file or set of files, this would allow Alembic to import it and use it without even needing to have **FastAPI** installed for the migrations. |
||||
|
|
||||
|
## Check it |
||||
|
|
||||
|
You can copy this code and use it as is. |
||||
|
|
||||
|
!!! info |
||||
|
|
||||
|
In fact, the code shown here is part of the tests. As most of the code in these docs. |
||||
|
|
||||
|
|
||||
|
You can copy it, let's say, to a file `main.py`. |
||||
|
|
||||
|
Then you can run it with Uvicorn: |
||||
|
|
||||
|
```bash |
||||
|
uvicorn main:app --debug |
||||
|
``` |
||||
|
|
||||
|
And then, you can open your browser at <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>. |
||||
|
|
||||
|
And you will be able to interact with your **FastAPI** application, reading data from a real database: |
||||
|
|
||||
|
<img src="/img/tutorial/sql-databases/image01.png"> |
||||
|
|
||||
|
## Response schema and security |
||||
|
|
||||
|
This section has the minimum code to show how it works and how you can integrate SQLAlchemy with FastAPI. |
||||
|
|
||||
|
But it is recommended that you also create a response model with Pydantic, as described in the section about <a href="/tutorial/extra-models/" target="_blank">Extra Models</a>. |
||||
|
|
||||
|
That way you will document the schema of the responses of your API, and you will be able to limit/filter the returned data. |
||||
|
|
||||
|
Limiting the returned data is important for security, as for example, you shouldn't be returning the `hashed_password` to the clients. |
||||
|
|
||||
|
That's something that you can improve in this example application, here's the current response data: |
||||
|
|
||||
|
```JSON |
||||
|
{ |
||||
|
"is_active": true, |
||||
|
"hashed_password": "notreallyhashed", |
||||
|
"email": "[email protected]", |
||||
|
"id": 1 |
||||
|
} |
||||
|
``` |
||||
|
|||||
@ -0,0 +1,88 @@ |
|||||
|
from starlette.testclient import TestClient |
||||
|
|
||||
|
from sql_databases.tutorial001 import app |
||||
|
|
||||
|
client = TestClient(app) |
||||
|
|
||||
|
openapi_schema = { |
||||
|
"openapi": "3.0.2", |
||||
|
"info": {"title": "Fast API", "version": "0.1.0"}, |
||||
|
"paths": { |
||||
|
"/users/{user_id}": { |
||||
|
"get": { |
||||
|
"responses": { |
||||
|
"200": { |
||||
|
"description": "Successful Response", |
||||
|
"content": {"application/json": {"schema": {}}}, |
||||
|
}, |
||||
|
"422": { |
||||
|
"description": "Validation Error", |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": { |
||||
|
"$ref": "#/components/schemas/HTTPValidationError" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
}, |
||||
|
}, |
||||
|
"summary": "Read User Get", |
||||
|
"operationId": "read_user_users__user_id__get", |
||||
|
"parameters": [ |
||||
|
{ |
||||
|
"required": True, |
||||
|
"schema": {"title": "User_Id", "type": "integer"}, |
||||
|
"name": "user_id", |
||||
|
"in": "path", |
||||
|
} |
||||
|
], |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"components": { |
||||
|
"schemas": { |
||||
|
"ValidationError": { |
||||
|
"title": "ValidationError", |
||||
|
"required": ["loc", "msg", "type"], |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"loc": { |
||||
|
"title": "Location", |
||||
|
"type": "array", |
||||
|
"items": {"type": "string"}, |
||||
|
}, |
||||
|
"msg": {"title": "Message", "type": "string"}, |
||||
|
"type": {"title": "Error Type", "type": "string"}, |
||||
|
}, |
||||
|
}, |
||||
|
"HTTPValidationError": { |
||||
|
"title": "HTTPValidationError", |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"detail": { |
||||
|
"title": "Detail", |
||||
|
"type": "array", |
||||
|
"items": {"$ref": "#/components/schemas/ValidationError"}, |
||||
|
} |
||||
|
}, |
||||
|
}, |
||||
|
} |
||||
|
}, |
||||
|
} |
||||
|
|
||||
|
|
||||
|
def test_openapi_schema(): |
||||
|
response = client.get("/openapi.json") |
||||
|
assert response.status_code == 200 |
||||
|
assert response.json() == openapi_schema |
||||
|
|
||||
|
|
||||
|
def test_first_user(): |
||||
|
response = client.get("/users/1") |
||||
|
assert response.status_code == 200 |
||||
|
assert response.json() == { |
||||
|
"is_active": True, |
||||
|
"hashed_password": "notreallyhashed", |
||||
|
"email": "[email protected]", |
||||
|
"id": 1, |
||||
|
} |
||||
Loading…
Reference in new issue