tursodatabase/turso · error · TypeError

Cannot get raw connection from SQLAlchemy connection

Error message

Cannot get raw connection from SQLAlchemy connection

What it means

get_sync_connection(connection) unwraps a SQLAlchemy Connection in two steps: first connection.connection, then the dbapi_connection attribute on SQLAlchemy 2.0's pooled-connection wrapper. If the object has no .connection attribute at all (getattr returns None), the function raises TypeError('Cannot get raw connection from SQLAlchemy connection') - the argument simply is not a live SQLAlchemy Connection.

Solutions

1. Pass a Connection: with engine.connect() as conn: get_sync_connection(conn)
2. Pull the connection from a Session via session.connection() when using the ORM
3. Do not feed raw turso connections or engines into this helper

Example fix

# before
raw = get_sync_connection(engine)  # TypeError

# after
with engine.connect() as conn:
    raw = get_sync_connection(conn)

def is_sqlalchemy_connection(obj) -> bool:
    return hasattr(obj, "connection")

def is_sqlalchemy_connection(obj) -> bool:
    # A live SQLAlchemy Connection exposes .connection; engines and strings do not.
    return hasattr(obj, "connection")

try:
    raw = get_sync_connection(conn)
except TypeError as e:
    if "raw connection" in str(e):
        raise TypeError("Pass engine.connect()'s result, not the engine") from e
    raise

When it happens

Trigger: Passing an Engine instead of a Connection (engine.connection does not exist); passing a Session, a raw string, a ConnectionSync that is already unwrapped, or a test double.

Common situations: Refactoring code that used to call engine.connect() inline; helpers meant to accept 'a connection-like thing'; tests passing mocks.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Expected turso.sync.ConnectionSync, got
• pyturso's SQLAlchemy dialects require SQLAlchemy >= 2.0.45
• Unrecognized query parameters ignored
• Unsupported value type
• batch mode must be one of

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

Appendix: source

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

            sync.push()

    Args:
        connection: A SQLAlchemy Connection object

    Returns:
        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)