Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork64
A carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy
License
litestar-org/advanced-alchemy
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Check out theproject documentation 📚 for more information.
A carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy,offering:
- Sync and async repositories, featuring common CRUD and highly optimized bulk operations
- Integration with major web frameworks including Litestar, Starlette, FastAPI, Sanic
- Custom-built alembic configuration and CLI with optional framework integration
- Utility base classes with audit columns, primary keys and utility functions
- Built in
File Objectdata type for storing objects: - Optimized JSON types including a custom JSON type for Oracle
- Integrated support for UUID6 and UUID7 using
uuid-utils(install with theuuidextra) - Integrated support for Nano ID using
fastnanoid(install with thenanoidextra) - Custom encrypted text type with multiple backend support including
pgcryptofor PostgreSQL and the Fernet implementation fromcryptographyfor other databases - Custom password hashing type with multiple backend support including
Argon2,Passlib, andPwdlibwith automatic salt generation - Pre-configured base classes with audit columns UUID or Big Integer primary keys andasentinel column.
- Synchronous and asynchronous repositories featuring:
- Common CRUD operations for SQLAlchemy models
- Bulk inserts, updates, upserts, and deletes with dialect-specific enhancements
- Integrated counts, pagination, sorting, filtering with
LIKE,IN, and dates before and/or after.
- Tested support for multiple database backends including:
- SQLite viaaiosqlite orsqlite
- Postgres viaasyncpg orpsycopg3 (async or sync)
- MySQL viaasyncmy
- Oracle viaoracledb (async or sync) (tested on 18c and 23c)
- Google Spanner viaspanner-sqlalchemy
- DuckDB viaduckdb_engine
- Microsoft SQL Server viapyodbc oraioodbc
- CockroachDB viasqlalchemy-cockroachdb (async or sync)
- ...and much more
pip install advanced-alchemy
Important
Check outthe installation guide in our official documentation!
Advanced Alchemy includes a set of asynchronous and synchronous repository classes for easy CRUDoperations on your SQLAlchemy models.
Click to expand the example
fromadvanced_alchemyimportbase,repository,configfromsqlalchemyimportcreate_enginefromsqlalchemy.ormimportMapped,sessionmakerclassUser(base.UUIDBase):# you can optionally override the generated table name by manually setting it.__tablename__="user_account"# type: ignore[assignment]email:Mapped[str]name:Mapped[str]classUserRepository(repository.SQLAlchemySyncRepository[User]):"""User repository."""model_type=Userdb=config.SQLAlchemySyncConfig(connection_string="duckdb:///:memory:",session_config=config.SyncSessionConfig(expire_on_commit=False))# Initializes the database.withdb.get_engine().begin()asconn:User.metadata.create_all(conn)withdb.get_session()asdb_session:repo=UserRepository(session=db_session)# 1) Create multiple users with `add_many`bulk_users= [ {"email":'cody@litestar.dev','name':'Cody'}, {"email":'janek@litestar.dev','name':'Janek'}, {"email":'peter@litestar.dev','name':'Peter'}, {"email":'jacob@litestar.dev','name':'Jacob'} ]objs=repo.add_many([User(**raw_user)forraw_userinbulk_users])db_session.commit()print(f"Created{len(objs)} new objects.")# 2) Select paginated data and total row count. Pass additional filters as kwargscreated_objs,total_objs=repo.list_and_count(LimitOffset(limit=10,offset=0),name="Cody")print(f"Selected{len(created_objs)} records out of a total of{total_objs}.")# 3) Let's remove the batch of records selected.deleted_objs=repo.delete_many([new_obj.idfornew_objincreated_objs])print(f"Removed{len(deleted_objs)} records out of a total of{total_objs}.")# 4) Let's count the remaining rowsremaining_count=repo.count()print(f"Found{remaining_count} remaining records after delete.")
For a full standalone example, see the samplehere
Advanced Alchemy includes an additional service class to make working with a repository easier.This class is designed to accept data as a dictionary or SQLAlchemy model,and it will handle the type conversions for you.
Here's the same example from above but using a service to create the data:
fromadvanced_alchemyimportbase,repository,filters,service,configfromsqlalchemyimportcreate_enginefromsqlalchemy.ormimportMapped,sessionmakerclassUser(base.UUIDBase):# you can optionally override the generated table name by manually setting it.__tablename__="user_account"# type: ignore[assignment]email:Mapped[str]name:Mapped[str]classUserService(service.SQLAlchemySyncRepositoryService[User]):"""User repository."""classRepo(repository.SQLAlchemySyncRepository[User]):"""User repository."""model_type=Userrepository_type=Repodb=config.SQLAlchemySyncConfig(connection_string="duckdb:///:memory:",session_config=config.SyncSessionConfig(expire_on_commit=False))# Initializes the database.withdb.get_engine().begin()asconn:User.metadata.create_all(conn)withdb.get_session()asdb_session:service=UserService(session=db_session)# 1) Create multiple users with `add_many`objs=service.create_many([ {"email":'cody@litestar.dev','name':'Cody'}, {"email":'janek@litestar.dev','name':'Janek'}, {"email":'peter@litestar.dev','name':'Peter'}, {"email":'jacob@litestar.dev','name':'Jacob'} ])print(objs)print(f"Created{len(objs)} new objects.")# 2) Select paginated data and total row count. Pass additional filters as kwargscreated_objs,total_objs=service.list_and_count(LimitOffset(limit=10,offset=0),name="Cody")print(f"Selected{len(created_objs)} records out of a total of{total_objs}.")# 3) Let's remove the batch of records selected.deleted_objs=service.delete_many([new_obj.idfornew_objincreated_objs])print(f"Removed{len(deleted_objs)} records out of a total of{total_objs}.")# 4) Let's count the remaining rowsremaining_count=service.count()print(f"Found{remaining_count} remaining records after delete.")
Advanced Alchemy works with nearly all Python web frameworks.Several helpers for popular libraries are included, and additional PRs to support others are welcomed.
Advanced Alchemy is the official SQLAlchemy integration for Litestar.
In addition to installing withpip install advanced-alchemy,it can also be installed as a Litestar extra withpip install litestar[sqlalchemy].
Litestar Example
fromlitestarimportLitestarfromlitestar.plugins.sqlalchemyimportSQLAlchemyPlugin,SQLAlchemyAsyncConfig# alternately...# from advanced_alchemy.extensions.litestar import SQLAlchemyAsyncConfig, SQLAlchemyPluginalchemy=SQLAlchemyPlugin(config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"),)app=Litestar(plugins=[alchemy])
For a full Litestar example, checkhere
Flask Example
fromflaskimportFlaskfromadvanced_alchemy.extensions.flaskimportAdvancedAlchemy,SQLAlchemySyncConfigapp=Flask(__name__)alchemy=AdvancedAlchemy(config=SQLAlchemySyncConfig(connection_string="duckdb:///:memory:"),app=app,)
For a full Flask example, seehere
FastAPI Example
fromadvanced_alchemy.extensions.fastapiimportAdvancedAlchemy,SQLAlchemyAsyncConfigfromfastapiimportFastAPIapp=FastAPI()alchemy=AdvancedAlchemy(config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"),app=app,)
For a full FastAPI example with optional CLI integration, seehere
Pre-built Example Apps
fromadvanced_alchemy.extensions.starletteimportAdvancedAlchemy,SQLAlchemyAsyncConfigfromstarlette.applicationsimportStarletteapp=Starlette()alchemy=AdvancedAlchemy(config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"),app=app,)
Pre-built Example Apps
fromsanicimportSanicfromsanic_extimportExtendfromadvanced_alchemy.extensions.sanicimportAdvancedAlchemy,SQLAlchemyAsyncConfigapp=Sanic("AlchemySanicApp")alchemy=AdvancedAlchemy(sqlalchemy_config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"),)Extend.register(alchemy)
AllLitestar Organization projects will always be a community-centered, available for contributions of any size.
Before contributing, please review thecontribution guide.
If you have any questions, reach out to us onDiscord, our org-wideGitHub discussions page,or theproject-specific GitHub discussions page.
An officialLitestar Organization Project
About
A carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy
Topics
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.