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 sqlalchemy import Boolean, Column, Integer, String, create_engine |
|||
from sqlalchemy.ext.declarative import declarative_base, declared_attr |
|||
from sqlalchemy.orm import scoped_session, sessionmaker |
|||
|
|||
# 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( |
|||
sessionmaker(autocommit=False, autoflush=False, bind=engine) |
|||
) |
|||
@ -30,15 +32,25 @@ class User(Base): |
|||
is_active = Column(Boolean(), default=True) |
|||
|
|||
|
|||
def get_user(username, db_session): |
|||
return db_session.query(User).filter(User.id == username).first() |
|||
Base.metadata.create_all(bind=engine) |
|||
|
|||
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 |
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/users/{username}") |
|||
def read_user(username: str): |
|||
user = get_user(username, db_session) |
|||
@app.get("/users/{user_id}") |
|||
def read_user(user_id: int): |
|||
user = get_user(db_session, user_id=user_id) |
|||
return user |
|||
|
|||
@ -12,7 +12,9 @@ You can easily adapt it to any database supported by SQLAlchemy, like: |
|||
* Oracle |
|||
* 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 |
|||
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: |
|||
|
|||
```Python hl_lines="3 4 5" |
|||
```Python hl_lines="2 3 4" |
|||
{!./src/sql_databases/tutorial001.py!} |
|||
``` |
|||
|
|||
## 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!} |
|||
``` |
|||
|
|||
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 |
|||
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` |
|||
|
|||
```Python hl_lines="10" |
|||
```Python hl_lines="10 11 12" |
|||
{!./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` |
|||
|
|||
```Python hl_lines="11 12 13" |
|||
```Python hl_lines="13 14 15" |
|||
{!./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. |
|||
|
|||
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 |
|||
|
|||
@ -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). |
|||
|
|||
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. |
|||
|
|||
```Python hl_lines="16 17 18 19 20" |
|||
```Python hl_lines="18 19 20 21 22" |
|||
{!./src/sql_databases/tutorial001.py!} |
|||
``` |
|||
|
|||
## Create the SQLAlchemy `Base` model |
|||
|
|||
```Python hl_lines="23" |
|||
```Python hl_lines="25" |
|||
{!./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: |
|||
|
|||
```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!} |
|||
``` |
|||
|
|||
### 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 |
|||
|
|||
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!} |
|||
``` |
|||
|
|||
@ -103,7 +154,7 @@ Now, finally, here's the standard **FastAPI** code. |
|||
|
|||
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!} |
|||
``` |
|||
|
|||
@ -113,25 +164,25 @@ We can just call `get_user` directly from inside of 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". |
|||
|
|||
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 |
|||
user = await get_user(username, db_session) |
|||
user = await get_user(db_session, user_id=user_id) |
|||
``` |
|||
|
|||
...and instead we are using: |
|||
|
|||
```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`: |
|||
|
|||
```Python hl_lines="42" |
|||
```Python hl_lines="54" |
|||
{!./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. |
|||
|
|||
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