sqlalchemy-multiple-db
Explicit, typed SQLAlchemy 2.x session management for multiple named databases.
Requirements
- Python 3.11, 3.12, 3.13, or 3.14
- SQLAlchemy 2.x (installed automatically)
Installation
uv add sqlalchemy-multiple-db
# or
uv pip install sqlalchemy-multiple-db
Quick start
from sqlalchemy import text
from sqlalchemy_multiple_db import DatabaseConfig, DatabaseManager
configs = {
"primary": DatabaseConfig(url="sqlite:///primary.db"),
"analytics": DatabaseConfig(url="sqlite:///analytics.db"),
}
with DatabaseManager(configs) as databases:
with databases.session("primary") as session:
session.execute(text("CREATE TABLE IF NOT EXISTS events (id INTEGER PRIMARY KEY)"))
session.execute(text("INSERT INTO events DEFAULT VALUES"))
with databases.session("analytics") as session:
session.execute(text("SELECT 1"))
assert databases.healthcheck() == {"primary": True, "analytics": True}
Each session(name) call creates a new SQLAlchemy Session. A normal block commits; an exception
rolls back and is re-raised; the session always closes. Call close() when not using the manager as a
context manager. close() is idempotent, but the manager cannot be used afterward.
Configuration
DatabaseConfig(url, engine_options={}, session_options={}) forwards option mappings to SQLAlchemy's
create_engine and sessionmaker. Options are copied at construction. The library deliberately does
not choose pool sizes or deprecated autocommit behavior; configure dialect-specific options explicitly
when needed.
healthcheck() runs SELECT 1 for every configured engine and returns a {name: bool} mapping.
SQLAlchemy connection failures are logged and reported as False without stopping checks for other
databases.
Migrating from 2.x
| 2.x | 3.0 |
|---|---|
DBConfig(dsn="...") |
DatabaseConfig(url="...") |
DBHelper or global db |
DatabaseManager(configurations) |
setup() |
construct the manager |
session_scope() |
session(name) |
get_status_info() |
healthcheck() |
shutdown() |
close() or with DatabaseManager(...) |
There is no global manager or implicit default database in 3.0. Name every database explicitly.
Examples
Each example uses temporary SQLite files and needs no external database server:
- basic_usage.py — create, write to, and query isolated primary and analytics databases.
- transaction_rollback.py — verify that an exception rolls back a transaction.
- healthcheck_and_options.py — configure engine/session options and inspect database health.
Run an example from a synced checkout:
uv run python examples/basic_usage.py
Development
uv sync --all-groups
uv run pytest
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src
uv build
Use uv add <package> to add a dependency and uv lock --upgrade to refresh all locked dependency
versions. Commit every pyproject.toml and uv.lock change together.
License
Apache-2.0. See LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sqlalchemy_multiple_db-3.0.0.tar.gz.
File metadata
- Download URL: sqlalchemy_multiple_db-3.0.0.tar.gz
- Upload date:
- Size: 57.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3ca0835075a5f9bcb3e353fa2c727bee2c888cadbf79815a9e08d58645ce68ab
|
|
| MD5 |
49248959fb3fad46765d6232df4c709d
|
|
| BLAKE2b-256 |
fe821d212343f721e2febe91884acffb0123ee16b344a6bbd97a3aadc193654a
|
Provenance
The following attestation bundles were made for sqlalchemy_multiple_db-3.0.0.tar.gz:
Publisher:
publish.yml on bigbag/sqlalchemy-multiple-db
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sqlalchemy_multiple_db-3.0.0.tar.gz -
Subject digest:
3ca0835075a5f9bcb3e353fa2c727bee2c888cadbf79815a9e08d58645ce68ab - Sigstore transparency entry: 2204891161
- Sigstore integration time:
-
Permalink:
bigbag/sqlalchemy-multiple-db@0e4e519d009ebffb290994c756b956fee504b54c -
Branch / Tag:
refs/tags/v3.0.0 - Owner: https://github.com/bigbag
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@0e4e519d009ebffb290994c756b956fee504b54c -
Trigger Event:
push
-
Statement type:
File details
Details for the file sqlalchemy_multiple_db-3.0.0-py3-none-any.whl.
File metadata
- Download URL: sqlalchemy_multiple_db-3.0.0-py3-none-any.whl
- Upload date:
- Size: 9.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
01b737c8643e5dbefe2ed8587dc1f396e76c35496209926aca49e72bab5bb083
|
|
| MD5 |
79148a2c1772a8fffb88d0f12cd7d61e
|
|
| BLAKE2b-256 |
799c3a9d2d3f90460a2a2ea54583eacaab84ec8030d56d08bd07af7e047fa66b
|
Provenance
The following attestation bundles were made for sqlalchemy_multiple_db-3.0.0-py3-none-any.whl:
Publisher:
publish.yml on bigbag/sqlalchemy-multiple-db
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sqlalchemy_multiple_db-3.0.0-py3-none-any.whl -
Subject digest:
01b737c8643e5dbefe2ed8587dc1f396e76c35496209926aca49e72bab5bb083 - Sigstore transparency entry: 2204891168
- Sigstore integration time:
-
Permalink:
bigbag/sqlalchemy-multiple-db@0e4e519d009ebffb290994c756b956fee504b54c -
Branch / Tag:
refs/tags/v3.0.0 - Owner: https://github.com/bigbag
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@0e4e519d009ebffb290994c756b956fee504b54c -
Trigger Event:
push
-
Statement type:
