Understanding the role of advanced-alchemy

[hyperknot]

I'm evaluating frameworks after happily using Pyramid + SQLAlchemy + Postgres in production for many years.

One of my biggest reasons for preferring Litestar over FastAPI is FastAPI's requirements of using Pydantic, so much that instead of being able to use pure SQLAlchemy, you are supposed to use SQLModel.

SQLModel is advertised as a "thin" wrapper, yet it's main folder contains 1500 lines of source code, with many parts implementing logic, instead of just being a thin type wrapper. It's so complicated actually that SQLModel is kind of abandoned, still on Pydantic 1 + SQLAlchemy 1 while FastAPI has long been on Pydantic 2.

Now, for Litestar part, I'm really happy to see the direction which removed Pydantic, Starlette, and is generally going for a more minimalistic core for this lib. What I cannot put anywhere is the advanced-alchemy dependency.

1. There is the official tutorial for SQLAlchemy usage, which is very clean, minimal and elegant. Using the contrib lib is optional and only contains 187 lines of code, super nice!
2. But if I look, litestar[sqlalchemy] is actually installing advanced-alchemy today:

   litestar/pyproject.toml

   Line 87 in a2fab8e

   sqlalchemy = ["advanced-alchemy==0.2.2"]

3. And this is where I get puzzled: advanced-alchemy is a 4400 line lib for I don't really know what.

I respect the work which went into this lib, but if I learned one thing with using SQLAlchemy in production is that it's an extremely powerful, yet very complicated to setup software. It's especially the connection handling / transaction / request-scoping part which is not easy to get right, when using with Postgres.

I fully support having the critical parts simplified into a few contrib files, but adding a 4400 line library between the app <> SQLAlchemy part doesn't give me the same "clean" feeling, as I've seen with the contrib dir or with the approach to removing Pydantic + Starlette.

Can you explain it a bit, as well as the direction you see with SQLAlchemy integration?

[provinzkraut]

but adding a 4400 line library between the app <> SQLAlchemy part doesn't give me the same "clean" feeling, as I've seen with the contrib dir or with the approach to removing Pydantic + Starlette.

advanced-alchemy is a 4400 line lib for I don't really know what.

Well, advanced-alchemy pretty much contains what was in contrib.sqlalchemy contrib.repository.sqlalchemy before, so it's not really a difference. It's just bundled up into a single, standalone package.

Can you explain it a bit, as well as the direction you see with SQLAlchemy integration?

As you already noticed, one of the things it does is handle the tricky stuff of integrating SQLAlchemy with a web framework, but it does so in a very non-intrusive way (contrary to SQLModel or flask-sqlalchemy).

For Litestar, it provides session management, serialization and data validation based on SQLAlchemy models and OpenAPI integration.

But it does more than that. It also offers synchronous and asynchronous repositories, which handle CRUD and bulk operations, both of which are highly optimised and specialise to the dialect being used, a few custom types and base classes and an alembic integration.

This is not necessarily related to Litestar, it's basically just boilerplate code you'd often have to write when building a web app.

Advanced Alchemy came into being because we realised that much of what we had built there could also be used independently of Litestar and could probably be of good use for people not using Litestar. Advanced Alchemy now offer integrations for FastAPI and Sanic as well, with more to come.

In general, you can think of it as a companion library for SQLAlchemy that aims to reduce the boilerplate needed when building web apps with it.

As you mentioned, there are quite a few tricky bits when it comes to dealing with SQLAlchemy; Advanced Alchemy tries to handle them for you, so you don't have to.
You are still free to use as little of it as you want and it will generally stay out of your way as much as possible.

[hyperknot]

Thank you for your detailed answer. I think I understand more about it now.

I'm happy that you choose the non-intrusive way. For my personal choice, I'll copy and paste a few bits from advanced-alchemy master into my repo and remove the dependency altogether.