tursodatabase/turso · error · ImportError

pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45 (

Error message

pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45 (found {sqlalchemy.__version__}). Upgrade with: pip install 'sqlalchemy>=2.0.45'

What it means

Import-time version guard in turso.sqlalchemy: the dialects need AsyncAdapt_dbapi_module (first shipped in SQLAlchemy 2.0.42, imported by .dialect) and the multiple-CHECK-constraint reflection fix from 2.0.45, so 2.0.45 is the minimum. Importing turso.sqlalchemy (or letting SQLAlchemy load the dialect from a sqlite+turso:// URL) with an older SQLAlchemy raises ImportError with explicit upgrade instructions instead of a confusing ImportError about SQLAlchemy internals.

Source

Thrown at bindings/python/turso/sqlalchemy/__init__.py:45

        sync.pull()  # Pull remote changes
        result = conn.execute(text("SELECT * FROM users"))
        conn.commit()
        sync.push()  # Push local changes
"""

import re

import sqlalchemy

# SQLAlchemy 2.0.42 first shipped AsyncAdapt_dbapi_module (imported by .dialect),
# and 2.0.45 fixed SQLite reflection of multiple CHECK constraints, so 2.0.45 is
# the oldest release the dialects fully work on. This guard must run before
# importing .dialect, which fails on releases before 2.0.42 with an ImportError
# about SQLAlchemy internals instead of a clear message.
_MIN_SQLALCHEMY_VERSION = (2, 0, 45)

if tuple(int(n) for n in re.findall(r"\d+", sqlalchemy.__version__)[:3]) < _MIN_SQLALCHEMY_VERSION:
    raise ImportError(
        f"pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45 "
        f"(found {sqlalchemy.__version__}). Upgrade with: pip install 'sqlalchemy>=2.0.45'"
    )

from .dialect import (  # noqa: E402
    AioTursoDialect,
    TursoDialect,
    TursoSyncDialect,
    get_sync_connection,
)

__all__ = [
    "AioTursoDialect",
    "TursoDialect",
    "TursoSyncDialect",
    "get_sync_connection",
]

View on GitHub (pinned to bad083fafb)

Solutions

Upgrade: `pip install 'sqlalchemy>=2.0.45'`
If another dependency pins SQLAlchemy lower, upgrade or loosen that pin so both constraints resolve >= 2.0.45
Verify after installing: `python -c "import sqlalchemy; print(sqlalchemy.__version__)"`

Example fix

# before (requirements.txt)
sqlalchemy==2.0.36

# after
sqlalchemy>=2.0.45

Defensive patterns

Strategy: validation

Validate before calling

import sqlalchemy

MIN = (2, 0, 45)
version = tuple(int(n) for n in __import__("re").findall(r"\d+", sqlalchemy.__version__)[:3])
if version < MIN:
    raise SystemExit(
        f"sqlalchemy {sqlalchemy.__version__} too old for turso dialects; "
        "run: pip install 'sqlalchemy>=2.0.45'"
    )
import turso.sqlalchemy  # now safe

Try / catch

try:
    import turso.sqlalchemy  # noqa: F401
except ImportError as e:
    if "SQLAlchemy >= 2.0.45" in str(e):
        raise SystemExit(str(e))  # surface the actionable upgrade instruction
    raise

Prevention

Pin `sqlalchemy>=2.0.45` in requirements once you adopt turso dialects
Check the installed version in CI before the first import of turso.sqlalchemy
Beware platforms bundling their own SQLAlchemy (Airflow, Jupyter, Superset) — verify, don't assume

When it happens

Trigger: `import turso.sqlalchemy` or `create_engine("sqlite+turso://...")` in an environment where sqlalchemy < 2.0.45 is installed — e.g. pinned by requirements.txt, locked by Poetry/Pipenv, or bundled by another framework.

Common situations: Projects pinning `sqlalchemy==2.0.x` older than 2.0.45; platforms (Airflow, Jupyter, Superset) that ship their own SQLAlchemy; dependency resolvers picking a older version to satisfy another package's constraint.

Related errors

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/3553116cdbc1b9ef. Report an issue: GitHub.