fix: name the async driver when a database URL uses a sync one

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 974018508

Author: GWeale

src/google/adk/sessions/database_session_service.py

@@ -40,6 +40,7 @@
   from sqlalchemy.engine import make_url
   from sqlalchemy.exc import ArgumentError
   from sqlalchemy.exc import IntegrityError
+  from sqlalchemy.exc import InvalidRequestError
   from sqlalchemy.ext.asyncio import async_sessionmaker
   from sqlalchemy.ext.asyncio import AsyncEngine
   from sqlalchemy.ext.asyncio import AsyncSession as DatabaseSessionFactory
@@ -95,6 +96,15 @@
     _MYSQL_DIALECT,
     _MARIADB_DIALECT,
 )
+# The driver a URL falls back to when it names none is synchronous for each of
+# these backends, and the asyncio extension of SQLAlchemy refuses a synchronous
+# driver, so such a URL cannot be used here.
+_ASYNC_DRIVER_BY_BACKEND = {
+    _SQLITE_DIALECT: "aiosqlite",
+    _POSTGRESQL_DIALECT: "asyncpg",
+    _MYSQL_DIALECT: "aiomysql",
+    _MARIADB_DIALECT: "asyncmy",
+}
 # Tuple key order for in-process per-session lock maps:
 # (app_name, user_id, session_id).
 _SessionLockKey: TypeAlias = tuple[str, str, str]
@@ -358,6 +368,16 @@ def __init__(
           raise ValueError(
               f"Invalid database URL format or argument '{redacted_url}'."
           ) from e
+        if isinstance(e, InvalidRequestError):
+          backend = make_url(db_url).get_backend_name()
+          async_driver = _ASYNC_DRIVER_BY_BACKEND.get(backend)
+          message = (
+              f"Database URL '{redacted_url}' resolves to a synchronous"
+              " driver, but this service requires an asynchronous one."
+          )
+          if async_driver:
+            message += f" Use a '{backend}+{async_driver}://' URL instead."
+          raise ValueError(message) from e
         if isinstance(e, ImportError):
           raise ValueError(
               f"Database related module not found for URL '{redacted_url}'."

tests/unittests/sessions/test_session_service.py

@@ -46,6 +46,7 @@
 from sqlalchemy import text
 from sqlalchemy import update
 from sqlalchemy.exc import ArgumentError
+from sqlalchemy.exc import InvalidRequestError
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlalchemy.pool import StaticPool
 
@@ -2799,6 +2800,7 @@ async def test_database_session_service_requires_one_argument():
         RuntimeError('boom'),
         ArgumentError('bad argument'),
         ImportError('no driver'),
+        InvalidRequestError('not an async driver'),
     ],
 )
 def test_database_session_service_engine_error_hides_password(raised_error):
@@ -2835,6 +2837,16 @@ def test_database_session_service_malformed_url_reports_usable_error():
   assert isinstance(exc_info.value.__cause__, ArgumentError)
 
 
+def test_database_session_service_sync_driver_url_names_async_driver():
+  """A synchronous URL is the common mistake, so name the driver that works."""
+  with pytest.raises(ValueError) as exc_info:
+    DatabaseSessionService('sqlite:///sessions.db')
+
+  message = str(exc_info.value)
+  assert 'synchronous' in message
+  assert 'sqlite+aiosqlite' in message
+
+
 @pytest.mark.asyncio
 async def test_database_session_service_sqlite_file_timestamp_read_after_reopen(
     tmp_path,