Open source

SynAlchemy

Async multi-database toolkit for SQLAlchemy 2.x

Type
Library
Built with
Python
Source
Public repository
Librarypublic repo
SA
SQLAlchemy 2.x (asyncio)PostgreSQLMySQL / MariaDB

Overview

An async multi-database toolkit for SQLAlchemy 2.x: one model base spans several databases, each model declares which database it lives in, and engines, pools, sessions and migrations are handled for you.

Core features

Per-model routing with __db_name__; async, sync and migration engines created on first use with the right pool strategy (pooled for servers, unpooled for serverless, or external behind PgBouncer); zero-wiring configuration from a synalchemy.toml with environment interpolation; one session that queries the right database automatically; timestamped, strictly linear async migrations per database with migrations and migrate commands; ENUM changes migrated on every dialect; PostgreSQL, MySQL, MariaDB, SQLite, SQL Server and Oracle.

Architecture

A thin layer over SQLAlchemy and Alembic, both used as dependencies and never forked. Typer provides the CLI, optional dependency groups pull the right async driver per dialect, and the package is built and locked with uv. It is documented as short question-per-page guides, ships a runnable three-database example shop, and is released as GitHub release wheels. It already runs inside CUT2STYLE, Synlor and Commerza.

Frameworks, tools & libraries

The stack behind it

Frameworks

  • SQLAlchemy 2.x (asyncio)

Tools & infrastructure

  • PostgreSQL
  • MySQL / MariaDB
  • SQLite
  • SQL Server
  • Oracle
  • uv
  • pytest
  • Ruff
  • GitHub Actions

Libraries

  • Alembic
  • Typer
  • asyncpg
  • aiosqlite
  • aiomysql
  • oracledb

Where it runs

My own products that depend on this library.

Skills applied

What I brought to it

  1. 01

    Async SQLAlchemy 2.x internals: engines, pools, sessions and routing

  2. 02

    Alembic revision-graph design and migration tooling

  3. 03

    Cross-dialect compatibility across six database engines

  4. 04

    Library and API design focused on zero-configuration ergonomics

  5. 05

    CLI design with Typer

  6. 06

    Packaging and release: wheels, optional extras, uv

  7. 07

    Technical documentation

Languages

What it's written in

  • Python~36 files

    library, CLI and tests

Next project

SynMail

A self-hostable mail platform