Improve compatibility with SQLAlchemy

Author: antoineleclair

src/dqlitedbapi/aio/__init__.py

@@ -2,6 +2,18 @@
 
 from dqlitedbapi.aio.connection import AsyncConnection
 from dqlitedbapi.aio.cursor import AsyncCursor
+from dqlitedbapi.exceptions import (
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
 
 # PEP 249 module-level attributes (required by SQLAlchemy dialect initialization)
 apilevel = "2.0"
@@ -13,15 +25,53 @@
 sqlite_version = "3.35.0"
 
 __all__ = [
+    # Module attributes
     "apilevel",
     "threadsafety",
     "paramstyle",
+    # Functions
+    "connect",
     "aconnect",
+    # Classes
     "AsyncConnection",
     "AsyncCursor",
+    # Exceptions
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
 ]
 
 
+def connect(
+    address: str,
+    *,
+    database: str = "default",
+    timeout: float = 10.0,
+) -> AsyncConnection:
+    """Create a dqlite connection (connects lazily on first use).
+
+    This is a sync function that returns an AsyncConnection without
+    establishing the TCP connection yet. SQLAlchemy requires connect()
+    to be sync; the actual connection is made when the first query runs.
+
+    Args:
+        address: Node address in "host:port" format
+        database: Database name to open
+        timeout: Connection timeout in seconds
+
+    Returns:
+        An AsyncConnection object
+    """
+    return AsyncConnection(address, database=database, timeout=timeout)
+
+
 async def aconnect(
     address: str,
     *,
@@ -30,13 +80,15 @@ async def aconnect(
 ) -> AsyncConnection:
     """Connect to a dqlite database asynchronously.
 
+    Unlike connect(), this awaits the TCP connection before returning.
+
     Args:
         address: Node address in "host:port" format
         database: Database name to open
         timeout: Connection timeout in seconds
 
     Returns:
-        An AsyncConnection object
+        A connected AsyncConnection object
     """
     conn = AsyncConnection(address, database=database, timeout=timeout)
     await conn.connect()

src/dqlitedbapi/aio/connection.py

@@ -30,24 +30,28 @@ def __init__(
         self._async_conn: DqliteConnection | None = None
         self._closed = False
 
-    async def connect(self) -> None:
-        """Establish the connection."""
+    async def _ensure_connection(self) -> DqliteConnection:
+        """Ensure the underlying connection is established."""
         if self._closed:
             raise InterfaceError("Connection is closed")
 
-        if self._async_conn is not None:
-            return
-
-        self._async_conn = DqliteConnection(
-            self._address,
-            database=self._database,
-            timeout=self._timeout,
-        )
-        try:
-            await self._async_conn.connect()
-        except Exception as e:
-            self._async_conn = None
-            raise OperationalError(f"Failed to connect: {e}") from e
+        if self._async_conn is None:
+            self._async_conn = DqliteConnection(
+                self._address,
+                database=self._database,
+                timeout=self._timeout,
+            )
+            try:
+                await self._async_conn.connect()
+            except Exception as e:
+                self._async_conn = None
+                raise OperationalError(f"Failed to connect: {e}") from e
+
+        return self._async_conn
+
+    async def connect(self) -> None:
+        """Establish the connection."""
+        await self._ensure_connection()
 
     async def close(self) -> None:
         """Close the connection."""
@@ -72,8 +76,12 @@ async def rollback(self) -> None:
         if self._async_conn is not None:
             await self._async_conn.execute("ROLLBACK")
 
-    async def cursor(self) -> AsyncCursor:
-        """Return a new AsyncCursor object."""
+    def cursor(self) -> AsyncCursor:
+        """Return a new AsyncCursor object.
+
+        This is intentionally sync — SQLAlchemy calls cursor() from
+        sync context within its greenlet-based async adapter.
+        """
         if self._closed:
             raise InterfaceError("Connection is closed")
         return AsyncCursor(self)

src/dqlitedbapi/aio/cursor.py

@@ -58,10 +58,7 @@ async def execute(
         """Execute a database operation (query or command)."""
         self._check_closed()
 
-        conn = self._connection._async_conn
-        if conn is None:
-            raise InterfaceError("Connection is not open")
-
+        conn = await self._connection._ensure_connection()
         params = list(parameters) if parameters else None
 
         # Determine if this is a query that returns rows