tursodatabase/turso · error · TypeError

Expected turso.sync.ConnectionSync, got

Error message

Expected turso.sync.ConnectionSync, got {type(dbapi_conn).__name__}. This function only works with sqlite+turso_sync:// connections.

What it means

After unwrapping, get_sync_connection checks isinstance(dbapi_conn, ConnectionSync). Anything else - a pysqlite connection, an async-dialect connection, a plain object - raises TypeError naming the actual type. The helper only works with connections created by the sqlite+turso_sync:// dialect, because only that dialect builds ConnectionSync instances underneath SQLAlchemy.

Solutions

1. Create the engine with the sqlite+turso_sync:// dialect for connections you will unwrap
2. For async engines, use the async access path instead of this sync helper
3. Branch on engine.dialect.name or the connection type before calling the helper

Example fix

# before
engine = create_engine("sqlite+turso:///:memory:")  # async-style dialect
with engine.connect() as conn:
    raw = get_sync_connection(conn)  # TypeError

# after
engine = create_engine("sqlite+turso_sync:///:memory:")
with engine.connect() as conn:
    raw = get_sync_connection(conn)

from turso.lib_sync import ConnectionSync

def unwrap_sync_connection(conn):
    dbapi = getattr(getattr(conn, "connection", None), "dbapi_connection", None)
    return dbapi if isinstance(dbapi, ConnectionSync) else None

from turso.lib_sync import ConnectionSync

def is_turso_sync_sa_connection(conn) -> bool:
    dbapi = getattr(getattr(conn, "connection", None), "dbapi_connection", None)
    return isinstance(dbapi, ConnectionSync)

try:
    raw = get_sync_connection(conn)
except TypeError as e:
    if "turso.sync.ConnectionSync" in str(e):
        raise TypeError("Create the engine with sqlite+turso_sync:// URLs") from e
    raise

When it happens

Trigger: Passing a Connection from the async dialect (sqlite+turso:// used with an async engine) or from SQLAlchemy's built-in sqlite dialect; passing a ConnectionSync created by hand instead of through the dialect.

Common situations: An app with both sync and async engines where the wrong connection object reaches the helper; refactors that switch dialect entry points; tests using in-memory pysqlite for speed.

Related errors

• Cannot get raw connection from SQLAlchemy connection
• Unrecognized query parameters ignored
• pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45
• Unsupported value type
• batch mode must be one of

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

Appendix: source

Thrown at bindings/python/turso/sqlalchemy/dialect.py:533

        The underlying turso.sync.ConnectionSync object

    Raises:
        TypeError: If the connection is not a Turso sync connection
    """
    from turso.lib_sync import ConnectionSync

    # Get the raw DBAPI connection
    # SQLAlchemy 2.0: connection.connection.dbapi_connection
    # SQLAlchemy 1.4: connection.connection
    raw_conn = getattr(connection, "connection", None)
    if raw_conn is None:
        raise TypeError("Cannot get raw connection from SQLAlchemy connection")

    # Handle SQLAlchemy 2.0 pooled connection wrapper
    dbapi_conn = getattr(raw_conn, "dbapi_connection", raw_conn)

    if not isinstance(dbapi_conn, ConnectionSync):
        raise TypeError(
            f"Expected turso.sync.ConnectionSync, got {type(dbapi_conn).__name__}. "
            "This function only works with sqlite+turso_sync:// connections."
        )

    return dbapi_conn

View on GitHub (pinned to 244cde92a7)