docs: some tweaks to existing wording

Signed-off-by: Grant Ramsay <[email protected]>

Author: seapagan

docs/explanation/database.md

@@ -35,8 +35,8 @@ DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
 We set a variable to be used later which contains the database URL. We are using
 PostgreSQL, but you can use any database that SQLAlchemy supports. The commented
 out line is for SQLite, which is a good choice for testing. You can comment out
-the PostgreSQL line (**13**)and uncomment the SQLite line (**14**)to use SQLite
-instead.
+the PostgreSQL line (**13**) and uncomment the SQLite line (**14**) to use
+SQLite instead.
 
 This is a basic connection string, in reality you would want to use environment
 variables to store the user/password and database name.
@@ -134,7 +134,7 @@ async def init_models() -> None:
     In a real-life example we would use Alembic to manage migrations.
     """
     async with async_engine.begin() as conn:
-        # await conn.run_sync(Base.metadata.drop_all)  # noqa: ERA001
+        # await conn.run_sync(Base.metadata.drop_all)
         await conn.run_sync(Base.metadata.create_all)
 ```
 
@@ -144,5 +144,9 @@ On line **57** we use the `run_sync` method to run the `create_all` method of
 the `Base.metadata` object (a syncronous function). This will create all of the
 tables defined in the models.
 
+If you want to drop the tables and recreate them every time the server restarts,
+you can uncomment line **56**. This is obviously not much good for production
+use, but it can be useful for testing.
+
 Next, we will look at the models themselves and the Schemas used to validate
 them within FastAPI.

docs/index.md

@@ -2,21 +2,42 @@
 
 ## Introduction
 
-I've been using [FastAPI][fastapi]{:target="_blank"} and
+This repository contains a very simple example how to use FastAPI with Async
+SQLAlchemy 2.0, in `ORM` mode. I'll probably add an example for `Core` mode
+also. No effort has been made to make this a production ready application, it's
+just a simple demo since at the time of writing there were few clear examples of
+how to do this.
+
+Last update 29th January 2024, and tested to work with the following versions:
+
+- Python 3.9+
+- FastAPI 0.109.0
+- SQLAlchemy  2.0.25
+
+## Why use Raw SQLAlchemy?
+
+I was using [FastAPI][fastapi]{:target="_blank"} and
 [SQLAlchemy][sqla]{:target="_blank"} combined with
-[encode/databases][databases]{:target="_blank"} for a while now.
+[encode/databases][databases]{:target="_blank"} for a while. This worked fine
+originally but I felt I needed a bit more control over the database session
+management.
 
-The `databases` package is a great wrapper around `SQLAlchemy` that allows you
-to use async/await with SQLAlchemy.
+!!! info
+    The [databases][databases]{:target="_blank"} package is a great wrapper
+    around `SQLAlchemy` that allows you to use async/await for database
+    operations. It also has a nice way of managing the database session, which
+    is why I used it originally.
 
-However, this does not seem be be actively maintained anymore. So I decided to
-give the new [Async SQLAlchemy][async-sqla]{:target="_blank"} a try instead.
+However, this did not seem be be actively maintained at the time, so I decided
+to give the newer [Async SQLAlchemy][async-sqla]{:target="_blank"} a try
+instead.
 
-This repository contains a very simple example how to use FastAPI with Async
-SQLAlchemy 2.0, in `ORM` mode. I'll probably add an example for `Core` mode
-also.
+This repository is the result of my exprimentation while converting my
+[FastAPI-template][fastapi-template]{:target="_blank"} project to use `Async
+SQLAlchemy` instead of `databases`.
 
-[fastapi]:https://fastapi.tiangolo.com/
+[fastapi]: https://fastapi.tiangolo.com/
 [sqla]: https://www.sqlalchemy.org/
-[databases]:https://www.encode.io/databases/
-[async-sqla]:https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
+[databases]: https://www.encode.io/databases/
+[async-sqla]: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
+[fastapi-template]: https://github.com/seapagan/fastapi-template