{"record":{"id":"38de0a7cdcea1a14","repo":"tursodatabase/turso","slug":"expected-turso-sync-connectionsync-got-type-dbap","errorCode":null,"errorMessage":"Expected turso.sync.ConnectionSync, got {type(dbapi_conn).__name__}. This function only works with sqlite+turso_sync:// connections.","messagePattern":"Expected turso\\.sync\\.ConnectionSync, got (.+?)\\. This function only works with sqlite\\+turso_sync:// connections\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"bindings/python/turso/sqlalchemy/dialect.py","lineNumber":533,"sourceCode":"        The underlying turso.sync.ConnectionSync object\n\n    Raises:\n        TypeError: If the connection is not a Turso sync connection\n    \"\"\"\n    from turso.lib_sync import ConnectionSync\n\n    # Get the raw DBAPI connection\n    # SQLAlchemy 2.0: connection.connection.dbapi_connection\n    # SQLAlchemy 1.4: connection.connection\n    raw_conn = getattr(connection, \"connection\", None)\n    if raw_conn is None:\n        raise TypeError(\"Cannot get raw connection from SQLAlchemy connection\")\n\n    # Handle SQLAlchemy 2.0 pooled connection wrapper\n    dbapi_conn = getattr(raw_conn, \"dbapi_connection\", raw_conn)\n\n    if not isinstance(dbapi_conn, ConnectionSync):\n        raise TypeError(\n            f\"Expected turso.sync.ConnectionSync, got {type(dbapi_conn).__name__}. \"\n            \"This function only works with sqlite+turso_sync:// connections.\"\n        )\n\n    return dbapi_conn\n","sourceCodeStart":515,"sourceCodeEnd":539,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/python/turso/sqlalchemy/dialect.py#L515-L539","documentation":"After successfully unwrapping a SQLAlchemy Connection, get_sync_connection requires the underlying DBAPI connection to be a turso.lib_sync.ConnectionSync. Engines created with plain sqlite:// (pysqlite), sqlite+turso:// (non-sync dialect), or any other driver produce a different type, and the TypeError names the actual type and states that only sqlite+turso_sync:// connections work.","triggerScenarios":"create_engine(\"sqlite:///local.db\") with pysqlite and passing its Connection to get_sync_connection; using the non-sync turso dialect (sqlite+turso://) and expecting sync features; a URL whose driver name fell back to another dialect.","commonSituations":"Projects that started on plain sqlite and added turso sync later without changing the URL; copy-paste dialect URLs; alembic env.py configured with sqlite:// while sync code expects ConnectionSync.","solutions":["Create the engine with the sync dialect: `create_engine(\"sqlite+turso_sync:///local.db?remote_url=libsql://...&auth_token=...\")`","Check the engine.url.drivername is 'turso_sync' before calling sync-specific helpers","Keep one canonical URL constant used by both app and migrations so the dialect stays consistent"],"exampleFix":"# before\nengine = create_engine(\"sqlite:///local.db\")\nwith engine.connect() as conn:\n    sync_conn = get_sync_connection(conn)  # TypeError: expected ConnectionSync\n\n# after\nengine = create_engine(\"sqlite+turso_sync:///local.db?remote_url=libsql://db.example.com\")\nwith engine.connect() as conn:\n    sync_conn = get_sync_connection(conn)","handlingStrategy":"type-guard","validationCode":"from sqlalchemy import create_engine\n\nengine = create_engine(\"sqlite+turso_sync:///local.db?remote_url=libsql://db.example.com\")\nassert engine.url.drivername == \"turso_sync\", \"sync helpers need the turso_sync driver\"","typeGuard":"from sqlalchemy.engine import Connection\nfrom turso.lib_sync import ConnectionSync\n\ndef is_sync_connection(conn: Connection) -> bool:\n    \"\"\"True when the SQLAlchemy Connection wraps a turso sync DBAPI connection.\"\"\"\n    raw = getattr(conn, \"connection\", None)\n    dbapi = getattr(raw, \"dbapi_connection\", raw)\n    return isinstance(dbapi, ConnectionSync)","tryCatchPattern":"try:\n    sync_conn = get_sync_connection(conn)\nexcept TypeError as e:\n    if \"only works with sqlite+turso_sync\" in str(e):\n        engine = create_engine(\"sqlite+turso_sync:///local.db?remote_url=...\")\n        with engine.connect() as c2:\n            sync_conn = get_sync_connection(c2)\n    else:\n        raise","preventionTips":["Create engines for sync workflows with sqlite+turso_sync://, never sqlite:// or sqlite+turso://","Centralize the database URL in one constant shared by app, migrations (alembic env.py), and scripts","Guard sync-specific helpers with an isinstance check on ConnectionSync before use"],"tags":["python","sqlalchemy","dialect","sync","connection-type"],"backgroundTag":"wrong-dialect-connection","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}