Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/febus982/sqlalchemy-bind-manager
Framework-agnostic SQLAlchemy bind manager and repository pattern implementation
https://github.com/febus982/sqlalchemy-bind-manager
orm python repository-pattern sqlalchemy sqlalchemy-python
Last synced: 2 months ago
JSON representation
Framework-agnostic SQLAlchemy bind manager and repository pattern implementation
- Host: GitHub
- URL: https://github.com/febus982/sqlalchemy-bind-manager
- Owner: febus982
- License: mit
- Created: 2022-11-20T20:01:07.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-08T03:14:59.000Z (3 months ago)
- Last Synced: 2024-10-10T13:09:05.920Z (3 months ago)
- Topics: orm, python, repository-pattern, sqlalchemy, sqlalchemy-python
- Language: Python
- Homepage: https://febus982.github.io/sqlalchemy-bind-manager/
- Size: 1.46 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# SQLAlchemy bind manager
[](https://pypi.org/project/sqlalchemy-bind-manager/)
[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)
[](https://github.com/febus982/sqlalchemy-bind-manager/actions/workflows/python-tests.yml)
[](https://codeclimate.com/github/febus982/sqlalchemy-bind-manager/maintainability)
[](https://codeclimate.com/github/febus982/sqlalchemy-bind-manager/test_coverage)
[](https://mypy-lang.org/)
[](https://github.com/psf/black)
[](https://github.com/charliermarsh/ruff)
[](https://github.com/PyCQA/bandit)
This package provides an easy way to configure and use SQLAlchemy engines and sessions
without depending on frameworks.
It is composed by two main components:
* A manager class for SQLAlchemy engine and session configuration
* A repository/unit-of-work pattern implementation for model retrieval and persistence
## Installation
```bash
pip install sqlalchemy-bind-manager
```
## Components maturity
[//]: # (https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md)
* [](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta) **SQLAlchemy manager:** Implementation is mostly finalised, needs testing in production.
* [](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta) **Repository:** Implementation is mostly finalised, needs testing in production.
* [](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#experimental) **Unit of work:** The implementation is working but limited to repositories using the same engine. Distributed transactions across different engines are not yet supported.
## Documentation
The complete documentation can be found [here](https://febus982.github.io/sqlalchemy-bind-manager)
## SQLAlchemy manager
Initialise the manager providing an instance of `SQLAlchemyConfig`
```python
from sqlalchemy_bind_manager import SQLAlchemyConfig, SQLAlchemyBindManager
config = SQLAlchemyConfig(
engine_url="sqlite:///./sqlite.db",
engine_options=dict(connect_args={"check_same_thread": False}, echo=True),
session_options=dict(expire_on_commit=False),
)
sa_manager = SQLAlchemyBindManager(config)
```
🚨 NOTE: Using global variables is not thread-safe, please read the [Documentation](https://febus982.github.io/sqlalchemy-bind-manager/manager/session/#note-on-multithreaded-applications) if your application uses multi-threading.
The `engine_url` and `engine_options` dictionaries accept the same parameters as SQLAlchemy [create_engine()](https://docs.sqlalchemy.org/en/14/core/engines.html#sqlalchemy.create_engine)
The `session_options` dictionary accepts the same parameters as SQLALchemy [sessionmaker()](https://docs.sqlalchemy.org/en/14/orm/session_api.html#sqlalchemy.orm.sessionmaker)
The `SQLAlchemyBindManager` provides some helper methods for common operations:
* `get_bind`: returns a `SQLAlchemyBind` or `SQLAlchemyAsyncBind` object
* `get_session`: returns a `Session` object, which works also as a context manager
* `get_mapper`: returns the mapper associated with the bind
Example:
```python
bind = sa_manager.get_bind()
class MyModel(bind.declarative_base):
pass
# Persist an object
o = MyModel()
o.name = "John"
with sa_manager.get_session() as session:
session.add(o)
session.commit()
```
[Imperative model declaration](https://febus982.github.io/sqlalchemy-bind-manager/manager/models/) is also supported.
### Multiple database binds
`SQLAlchemyBindManager` accepts also multiple databases configuration, provided as a dictionary. The dictionary keys are used as a reference name for each bind.
```python
from sqlalchemy_bind_manager import SQLAlchemyConfig, SQLAlchemyBindManager
config = {
"default": SQLAlchemyConfig(
engine_url="sqlite:///./sqlite.db",
engine_options=dict(connect_args={"check_same_thread": False}, echo=True),
session_options=dict(expire_on_commit=False),
),
"secondary": SQLAlchemyConfig(
engine_url="sqlite:///./secondary.db",
engine_options=dict(connect_args={"check_same_thread": False}, echo=True),
session_options=dict(expire_on_commit=False),
),
}
sa_manager = SQLAlchemyBindManager(config)
```
All the `SQLAlchemyBindManager` helper methods accept the `bind_name` optional parameter:
* `get_bind(bind_name="default")`: returns a `SQLAlchemyBind` or `SQLAlchemyAsyncBind` object
* `get_session(bind_name="default")`: returns a `Session` or `AsyncSession` object, which works also as a context manager
* `get_mapper(bind_name="default")`: returns the mapper associated with the bind
### Asynchronous database binds
Is it possible to supply configurations for asyncio supported engines.
```python
config = SQLAlchemyAsyncConfig(
engine_url="postgresql+asyncpg://scott:tiger@localhost/test",
)
```
This will make sure we have an `AsyncEngine` and an `AsyncSession` are initialised, as an asynchronous context manager.
```python
async with sa_manager.get_session() as session:
session.add(o)
await session.commit()
```
Note that async implementation has several differences from the sync one, make sure
to check [SQLAlchemy asyncio documentation](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
## Repository / Unit of work
The `SQLAlchemyRepository` and `SQLAlchemyAsyncRepository` class can be used directly or by extending them.
```python
from sqlalchemy_bind_manager.repository import SQLAlchemyRepository
class MyModel(declarative_base):
pass
# Direct usage
repo_instance = SQLAlchemyRepository(sqlalchemy_bind_manager.get_bind(), model_class=MyModel)
class ModelRepository(SQLAlchemyRepository[MyModel]):
_model = MyModel
def _some_custom_method_implemented(self):
...
# Extended class usage
extended_repo_instance = ModelRepository(sqlalchemy_bind_manager.get_bind())
```
The repository classes provides methods for common use case:
* `get`: Retrieve a model by primary key
* `save`: Persist a model
* `save_many`: Persist multiple models in a single transaction
* `delete`: Delete a model
* `find`: Search for a list of models (basically an adapter for SELECT queries)
* `paginated_find`: Search for a list of models, with pagination support
* `cursor_paginated_find`: Search for a list of models, with cursor based pagination support
### Use the Unit Of Work to share a session among multiple repositories
It is possible we need to run several operations in a single database transaction. While a single
repository provide by itself an isolated session for single operations, we have to use a different
approach for multiple operations.
We can use the `UnitOfWork` or the `AsyncUnitOfWork` class to provide a shared session to
be used for repository operations, **assumed the same bind is used for all the repositories**.
```python
class MyRepo(SQLAlchemyRepository):
_model = MyModel
bind = sa_manager.get_bind()
uow = UnitOfWork(bind)
uow.register_repository("repo_a", MyRepo)
uow.register_repository("repo_b", SQLAlchemyRepository, MyOtherModel)
with uow.transaction():
uow.repository("repo_a").save(some_model)
uow.repository("repo_b").save(some_other_model)
```