# Advanced Alchemy: the SQLAlchemy layer that gives Litestar a repository and service pattern

> Advanced Alchemy is a companion library for SQLAlchemy maintained by the Litestar organisation, packaging a repository and service pattern, async support and Alembic integration across PostgreSQL, MySQL, SQLite, Oracle, MSSQL, CockroachDB, DuckDB and Spanner. It ships as advanced_alchemy and works with Litestar, FastAPI, Flask and Sanic alike.

**litestar-org/advanced-alchemy** — A carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy

- Repository: https://github.com/litestar-org/advanced-alchemy
- Website: http://advanced-alchemy.litestar.dev/
- Stars: 814 · Forks: 85
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/litestar-org-advanced-alchemy

## What the library adds to SQLAlchemy

Advanced Alchemy describes itself as a carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy, and the project description in its package metadata is blunter: ready-to-go SQLAlchemy concoctions.

The dependency list is short enough to describe the whole design:

```toml
dependencies = [
  "sqlalchemy>=2.0.41",
  "alembic>=1.12.0",
  "typing-extensions>=4.0.0",
  "greenlet",
  "eval-type-backport ; python_full_version < '3.10'",
  "exceptiongroup ; python_full_version < '3.11'",
]
```

SQLAlchemy and Alembic are the foundation, and there is no framework dependency at all in the core list. That is the important fact about the library, because it means the repository and service pattern it provides is not tied to Litestar.

The two conditional dependencies are worth noting for a supported version range that starts at Python 3.9. eval-type-backport covers the newer annotation syntax on 3.9, and exceptiongroup provides the exception group behaviour on 3.10 and earlier, so the library can use modern typing and error grouping syntax while still supporting the older interpreters it claims.

The package is published as advanced_alchemy, at version 1.12.0, and the licence is MIT. The classifier list marks it as Development Status 3, Alpha, and Typing Typed, with operating system independence and Python support from 3.9 through 3.14.

## The feature surface, read from the documentation test list

The repository's Makefile lists the documentation pages that are executed as tests, and that list is the most precise inventory of what the library does. The pages are grouped under usage/modeling and usage/repositories, with usage/database_seeding.rst and usage/services.rst alongside them.

The modeling section covers basics, inheritance, sqlmodel and types. Inheritance and SQLModel support are the two that stand out, because both are places where people usually end up writing their own glue between SQLAlchemy's declarative base and the abstractions they want.

The repositories section covers basics, advanced and filtering. A filtering layer is a substantial addition rather than a thin wrapper, since it means you can express a query filter once and reuse it across a route handler, a background job and a test without repeating the WHERE clause.

Database seeding has its own page, which is a gap in most SQLAlchemy projects. Seeding a database is a chore that every application needs and few want to reinvent, and having it in the library with the same async behaviour as the repositories saves a project from writing and maintaining its own.

Services have their own page as well, and a service layer is the other common piece that sits between a repository and a framework route. The split between repository and service is a design decision rather than a necessity, so it is worth understanding what the library puts on each side before choosing it.

## Database breadth is the strongest argument for it

The topic tags on the repository list a wide set of engines: postgresql, mysql, sqlite, oracle-db, mssql, cockroachdb, duckdb and spanner, alongside alembic for migrations.

That list is the strongest single reason to use a companion library rather than plain SQLAlchemy, because each of those engines has its own quirks around types, upsert syntax, JSON columns and returning clauses, and a library that claims all of them has had to abstract over them in one place. The presence of DuckDB and Spanner alongside the conventional databases suggests the abstraction is not built around the behaviour of one vendor.

The framework breadth follows the same pattern. The examples directory contains a FastAPI example, a Flask example, a Litestar example, a Sanic module, and two standalone scripts, one plain and one JSON. A standalone example is a library that works without any web framework at all, which is what a service layer and repository pattern buys you: the same data access code behind a CLI tool, a worker or an HTTP service.

The topic tags also name fastapi, flask, sanic, litestar, starlette, sqlmodel and the repository pattern, which is a fair summary of the intended audience: teams who have picked a Python web framework and now need a data layer that is not welded to it.

## Who maintains it and how the project is run

The project sits under the Litestar organisation, and the authorship is spread across four names: Cody Fincher, Peter Schutt, Janek Nouvertné and Jacob Coffee. The maintainer list is longer still, with the Litestar Developers group account plus individual entries for Cody Fincher, Jacob Coffee, Janek Nouvertné and Julien Courtes, all on the litestar.dev domain.

The release history is steady. Version 1.12.0 was published on 2026-10-19, 1.11.0 on 2026-05-31 and 1.10.0 on 2026-05-23, and the last push to the repository was on 2026-10-20, the day before this article. Three minor versions in a year with a release on the day of the last push is the profile of an actively maintained library rather than a quiet one.

The quality signals in the project are visible in the repository. There is a codecov configuration, a sonar-project.properties file, a pre-commit configuration and a .sourcery.yaml file, and the README carries badges for a coverage report, a SonarCloud quality gate, and separate maintainability, reliability and security ratings. The Makefile also has a self-documenting help target that prints available targets with descriptions.

The community channels are a Discord server and a Matrix room, with Matrix bridged to Discord, which is the arrangement the wider Litestar project uses.

## How the project is built

The Makefile is written to be read. It sets the shell to bash with strict flags, uses .ONESHELL so that each recipe runs as a single script rather than line by line, exports all variables so that recipes see the environment, and passes --no-print-directory to make so the output stays clean.

The colour and symbol handling is done with shell escape sequences rather than a Python helper, with blue, green, red and yellow defined and reset at the end, and an info, ok, warn and error prefix per line. The help target is a single awk one-liner that scans the Makefile for targets with a double hash comment and prints them in a table.

The documentation test list at the top of the file is a directory of .rst files under docs/usage. The naming convention tells you the documentation is organised by concept rather than by API, since the entries are basics, inheritance, sqlmodel and types under modeling, basics, advanced and filtering under repositories, and then database_seeding and services as their own topics.

The repository layout matches. There is an advanced_alchemy package directory, a docs directory, an examples directory, a tests directory, a tools directory, a uv.lock, a CONTRIBUTING document in reStructuredText, and a Makefile with the configuration and environment variable section at the top.

## Where Advanced Alchemy is the wrong choice

The first limitation is that the library is classified as Alpha while carrying a 1.x version number. Those two facts are in tension, and a team with a strict policy on pre-1.0 stability may reasonably read Alpha as the more important of them. The release cadence suggests active work, but active work on an API that has not yet declared itself stable is a different risk profile from a mature library with a slower pace.

The second is that the value depends on how much of the layer you actually want. If your application has five tables and simple CRUD, SQLAlchemy plus a handful of query functions is less to learn and less to depend on. The repository and service pattern earns its cost when there are dozens of models, consistent filtering across many endpoints, seeding that runs in several environments, and a team that would otherwise write the same boilerplate in each service module.

The third is the framework question. The library sits in the Litestar organisation, which means its roadmap and its defaults will follow what Litestar needs, and the maintainers are the same people. For a Litestar project that is an advantage, because the two are designed to work together. For a FastAPI or Flask project it is a reasonable dependency with a slightly different centre of gravity, and the standalone examples suggest it is intended to work that way, though the Litestar path will be the best documented.

The comparison to plain SQLAlchemy is therefore the one to make honestly. Advanced Alchemy does not make SQLAlchemy faster and does not change what SQLAlchemy does. It removes decisions you would otherwise have to make and then defend, which is valuable when those decisions are many, and unnecessary when they are few.

## Conclusion

Advanced Alchemy fits a Python team that has already chosen SQLAlchemy and wants a repository and service layer with async support, typed models and migrations rather than writing those layers itself, whether the framework is Litestar, FastAPI, Flask or Sanic. It does not fit a project that wants raw SQLAlchemy, or one on a database outside the listed backends. Before adopting it, read the documentation pages the Makefile tests, since that list is the clearest map of the feature surface, pin the version because the 1.x line has moved through 1.10, 1.11 and 1.12 in a single year, and check the maintenance status yourself, since the project is still classified as Alpha despite a 1.x version number.

## FAQ

### What is Advanced Alchemy and what does it add to SQLAlchemy?

It is a companion library for SQLAlchemy maintained by the Litestar organisation, providing a repository and service pattern, model modeling helpers, filtering, database seeding and Alembic integration. Its core dependencies are SQLAlchemy 2.0.41 or newer, Alembic 1.12.0 or newer, typing-extensions, greenlet, and backports for older Python versions.

### Which databases and web frameworks does Advanced Alchemy support?

The project topics name PostgreSQL, MySQL, SQLite, Oracle, MSSQL, CockroachDB, DuckDB and Spanner, and the examples directory includes FastAPI, Flask, Litestar, Sanic and standalone scripts that use no web framework at all.

### Which Python versions does Advanced Alchemy support?

It requires Python 3.9 or newer, with classifiers covering 3.9 through 3.14. The package pulls in eval-type-backport on Python below 3.10 and exceptiongroup below 3.11 so that modern typing and exception group syntax works on the older interpreters.

### Is Advanced Alchemy still in development?

The project classifiers list Development Status 3, Alpha, and it is published under the MIT licence with a version of 1.12.0. The release history shows 1.10.0 in May 2026, 1.11.0 later that month and 1.12.0 in October 2026, with the last push on 2026-10-20.

### What documentation does the project test automatically?

The Makefile lists the pages run as documentation tests, covering modeling basics, inheritance, sqlmodel and types, repository basics, advanced usage and filtering, database seeding and services. The repository also carries a codecov configuration, a sonar-project.properties file and a pre-commit configuration.

## Sources

- [License: MIT](https://github.com/litestar-org/advanced-alchemy/blob/main/LICENSE)
- [litestar-org/advanced-alchemy on GitHub](https://github.com/litestar-org/advanced-alchemy)
- [Project website](http://advanced-alchemy.litestar.dev/)
- [README](https://github.com/litestar-org/advanced-alchemy/blob/main/README.md)
- [Releases](https://github.com/litestar-org/advanced-alchemy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/litestar-org-advanced-alchemy