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

Importing turso.sqlalchemy compares the installed SQLAlchemy version against a minimum of 2.0.45 and raises ImportError with an upgrade hint when it is older. The floor exists because 2.0.42 first shipped AsyncAdapt_dbapi_module (imported by the dialect module) and 2.0.45 fixed SQLite reflection of multiple CHECK constraints. Without the guard, older releases die with a confusing ImportError about SQLAlchemy internals.

Solutions

1. Install the required version: pip install 'sqlalchemy>=2.0.45'
2. Update the lockfile or requirements line and recreate the environment
3. Verify with: python -c "import sqlalchemy; print(sqlalchemy.__version__)"

Example fix

# before (requirements.txt)
sqlalchemy==2.0.36

# after
sqlalchemy>=2.0.45

import re
import sqlalchemy

def sqlalchemy_supported() -> bool:
    nums = tuple(int(n) for n in re.findall(r"\d+", sqlalchemy.__version__)[:3])
    return nums >= (2, 0, 45)

if not sqlalchemy_supported():
    raise RuntimeError("Upgrade first: pip install 'sqlalchemy>=2.0.45'")
import turso.sqlalchemy

try:
    import turso.sqlalchemy
except ImportError as e:
    if "SQLAlchemy >= 2.0.45" in str(e):
        raise SystemExit("Run: pip install 'sqlalchemy>=2.0.45'") from e
    raise

When it happens

Trigger: import turso.sqlalchemy or use the sqlite+turso:// dialect with sqlalchemy < 2.0.45 installed; a lockfile pinning sqlalchemy==2.0.36; another dependency's constraint forcing a downgrade below 2.0.45.

Common situations: Fresh clone of a project with stale requirements.txt; poetry/pipenv locks not updated after adding pyturso; CI layer caches holding an old sqlalchemy wheel; system packages shipping old SQLAlchemy.

Related errors

• Cannot get raw connection from SQLAlchemy connection
• Expected turso.sync.ConnectionSync, got
• Unrecognized query parameters ignored
• batch mode must be one of
• batch mode must be one of

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

Appendix: 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 244cde92a7)