polydb

One async API for PostgreSQL, MongoDB, SQLite, and MySQL.

Source: https://github.com/Genius740Code/polydb

polydb gives application code a single async API for CRUD, schema, transactions, and raw-query escape hatches, backed by three adapters (Postgres, Mongo, and a SQL-generic family covering SQLite + MySQL). Switching backends is a connection-string change — see the planning document for the full support matrix and build order.

Current status

Planned, not fully built. Implemented so far (planning doc §1.1 Connection management + §1.2 Create + §1.3 Read):

Filters are compiled by the shared sql_compiler.py into fully parameterized SQL; column/table names are validated against [A-Za-z_][A-Za-z0-9_]* and quoted. SQLite quotes identifiers with backticks on purpose — double-quoted unknown identifiers silently become string literals in SQLite, hiding typos.

Postgres / Mongo / SQL-MySQL legs raise NotImplementedError until their respective build steps land (see build order §6).

Installation

The PyPI distribution is genius74o-polydb (the plain polydb name is squatted); the Python package you import is still polydb:

pip install genius74o-polydb              # core (no drivers)
pip install "genius74o-polydb[sqlite]"    # + a driver, or: postgres / mongo / mysql
pip install "genius74o-polydb[all]"       # every driver

Quick start (SQLite — the one working leg)

import asyncio

from polydb import Database


async def main() -> None:
    async with Database.from_url("sqlite:///:memory:") as db:
        assert await db.ping() is True

asyncio.run(main())

Connecting to other backends

Database.from_url() resolves all supported schemes to their adapter class, returning an unconnected instance:

Under the hood

• docs/connection.md — connection URL format, adapter resolution, tuning knobs.
• examples/switching_backends.py — one script, three connection strings.
• plan.md — planning document: feature list, DSL spec, build order, testing strategy.

Development

# install dev extras (pytest, pytest-asyncio, drivers)
pip install -e ".[dev]"

# run the test suite from the repo root
PYTHONPATH=src pytest

Branching & releases

All development happens on the development branch; master is release-only. The publish.yml workflow automates publishing:

To cut a release: bump version in pyproject.toml, merge development into master, and push — PyPI rejects re-uploaded versions, so bump first.

Publishing authenticates with PyPI API tokens stored as GitHub repo secrets (Settings → Secrets and variables → Actions):

or from the CLI: gh secret set TESTPYPI_API_TOKEN / gh secret set PYPI_API_TOKEN.