sqlalchemy-jdbcapi 2.0.0.post2__py3-none-any.whl

sqlalchemy_jdbcapi/jdbc/connection.py

@@ -0,0 +1,244 @@
+"""
+JDBC Connection implementation following DB-API 2.0 specification.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .cursor import Cursor
+from .exceptions import DatabaseError, InterfaceError
+from .jvm import start_jvm
+
+logger = logging.getLogger(__name__)
+
+
+class Connection:
+    """
+    DB-API 2.0 compliant connection to a JDBC database.
+
+    This class wraps a JDBC Connection object from JPype.
+    """
+
+    def __init__(
+        self,
+        jclassname: str,
+        url: str,
+        driver_args: dict[str, Any] | list[Any] | None = None,
+        jars: list[str] | None = None,
+        libs: list[str] | None = None,
+    ) -> None:
+        """
+        Create a JDBC connection.
+
+        Args:
+            jclassname: Fully qualified Java class name of JDBC driver
+            url: JDBC connection URL
+            driver_args: Connection properties (dict) or [user, password] (list)
+            jars: List of JAR file paths (for classpath)
+            libs: Additional native library paths
+
+        Raises:
+            InterfaceError: If JVM or driver cannot be loaded
+            DatabaseError: If connection fails
+        """
+        self._jclassname = jclassname
+        self._url = url
+        self._jdbc_connection: Any = None
+        self._closed = False
+
+        # Start JVM if not already running
+        # Note: JVM can only be started once per Python process
+        try:
+            start_jvm(classpath=list(jars or []), jvm_args=None)
+        except Exception as e:
+            raise InterfaceError(f"Failed to start JVM: {e}") from e
+
+        # Load driver and establish connection
+        try:
+            import jpype
+
+            # Load the JDBC driver class - this registers it with DriverManager
+            # Even though we don't use the returned class, loading it has side effects
+            jpype.JClass(jclassname)
+            logger.debug(f"Loaded JDBC driver: {jclassname}")
+
+            # Get DriverManager - this is the main entry point for JDBC connections
+            dm = jpype.JClass("java.sql.DriverManager")
+
+            # Create connection based on driver_args format
+            # We support multiple formats for flexibility
+            if driver_args is None:
+                # Simple connection without credentials
+                self._jdbc_connection = dm.getConnection(url)
+
+            elif isinstance(driver_args, dict):
+                # Dict format - convert to Java Properties
+                # This allows passing custom JDBC properties like SSL settings
+                props = jpype.JClass("java.util.Properties")()
+                for k, v in driver_args.items():
+                    props.setProperty(str(k), str(v))
+                self._jdbc_connection = dm.getConnection(url, props)
+
+            elif isinstance(driver_args, (list, tuple)) and len(driver_args) == 2:
+                # List format for simple user/password auth
+                usr, pwd = driver_args
+                self._jdbc_connection = dm.getConnection(url, str(usr), str(pwd))
+
+            else:
+                # TODO: Maybe support more argument formats in the future?
+                raise ValueError("driver_args must be dict, [user, password], or None")
+
+            logger.info(f"Connected to database: {url}")
+
+        except Exception as e:
+            logger.exception(f"Connection failed: {e}")
+            raise DatabaseError(f"Failed to connect to database: {e}") from e
+
+    def close(self) -> None:
+        """Close the connection."""
+        if self._closed:
+            return
+
+        try:
+            if self._jdbc_connection is not None:
+                self._jdbc_connection.close()
+                logger.debug("Connection closed")
+        except Exception as e:
+            logger.warning(f"Error closing connection: {e}")
+        finally:
+            self._jdbc_connection = None
+            self._closed = True
+
+    def commit(self) -> None:
+        """Commit current transaction."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        try:
+            if self._jdbc_connection is not None:
+                self._jdbc_connection.commit()
+                logger.debug("Transaction committed")
+        except Exception as e:
+            raise DatabaseError(f"Commit failed: {e}") from e
+
+    def rollback(self) -> None:
+        """Rollback current transaction."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        try:
+            if self._jdbc_connection is not None:
+                self._jdbc_connection.rollback()
+                logger.debug("Transaction rolled back")
+        except Exception as e:
+            raise DatabaseError(f"Rollback failed: {e}") from e
+
+    def cursor(self) -> Cursor:
+        """
+        Create a new cursor.
+
+        Returns:
+            Cursor object
+
+        Raises:
+            InterfaceError: If connection is closed
+        """
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        return Cursor(self, self._jdbc_connection)
+
+    def set_auto_commit(self, auto_commit: bool) -> None:
+        """
+        Set auto-commit mode.
+
+        Args:
+            auto_commit: True to enable auto-commit, False to disable
+        """
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        try:
+            self._jdbc_connection.setAutoCommit(auto_commit)
+            logger.debug(f"Auto-commit set to {auto_commit}")
+        except Exception as e:
+            raise DatabaseError(f"Failed to set auto-commit: {e}") from e
+
+    def get_auto_commit(self) -> bool:
+        """Get current auto-commit mode."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        try:
+            return self._jdbc_connection.getAutoCommit()
+        except Exception as e:
+            raise DatabaseError(f"Failed to get auto-commit: {e}") from e
+
+    @property
+    def closed(self) -> bool:
+        """Check if connection is closed."""
+        return self._closed
+
+    def __enter__(self) -> Connection:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        if exc_type is None:
+            self.commit()
+        else:
+            self.rollback()
+        self.close()
+
+    def __del__(self) -> None:
+        """Destructor to ensure connection is closed."""
+        if not self._closed:
+            try:
+                self.close()
+            except Exception:
+                pass
+
+
+def connect(
+    jclassname: str,
+    url: str,
+    driver_args: dict[str, Any] | list[Any] | None = None,
+    jars: list[str] | None = None,
+    libs: list[str] | None = None,
+) -> Connection:
+    """
+    Create a JDBC database connection.
+
+    This is the main entry point for creating connections, following DB-API 2.0.
+
+    Args:
+        jclassname: Fully qualified Java class name of JDBC driver
+        url: JDBC connection URL
+        driver_args: Connection properties (dict) or [user, password] (list)
+        jars: List of JAR file paths for classpath
+        libs: Additional native library paths
+
+    Returns:
+        Connection object
+
+    Example:
+        >>> conn = connect(
+        ...     'org.postgresql.Driver',
+        ...     'jdbc:postgresql://localhost:5432/mydb',
+        ...     {'user': 'myuser', 'password': 'mypass'}
+        ... )
+        >>> cursor = conn.cursor()
+        >>> cursor.execute('SELECT * FROM users')
+        >>> rows = cursor.fetchall()
+        >>> conn.close()
+    """
+    return Connection(
+        jclassname=jclassname,
+        url=url,
+        driver_args=driver_args,
+        jars=jars,
+        libs=libs,
+    )

sqlalchemy_jdbcapi/jdbc/cursor.py

@@ -0,0 +1,329 @@
+"""
+JDBC Cursor implementation following DB-API 2.0 specification.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+from .exceptions import (
+    DataError,
+    InterfaceError,
+    ProgrammingError,
+)
+from .type_converter import TypeConverter
+
+logger = logging.getLogger(__name__)
+
+
+class Cursor:
+    """
+    DB-API 2.0 compliant cursor for JDBC connections.
+
+    This class wraps a JDBC Statement/PreparedStatement and ResultSet.
+    """
+
+    def __init__(self, connection: Any, jdbc_connection: Any) -> None:
+        """
+        Initialize cursor.
+
+        Args:
+            connection: Parent Connection object
+            jdbc_connection: JDBC Connection object from JPype
+        """
+        self._connection = connection
+        self._jdbc_connection = jdbc_connection
+
+        # These will be set when we execute queries
+        self._jdbc_statement: Any = None
+        self._jdbc_resultset: Any = None
+
+        # DB-API 2.0 spec requires these attributes
+        self._description: tuple[tuple[str, ...], ...] | None = None
+        self._rowcount: int = -1  # -1 means "unknown" per DB-API spec
+        self._arraysize: int = 1  # default fetch size
+
+        # We handle type conversion ourselves since JDBC types don't map 1:1 to Python
+        self._type_converter = TypeConverter()
+        self._closed = False
+
+    @property
+    def description(
+        self,
+    ) -> tuple[tuple[str, Any, None, None, None, None, None], ...] | None:
+        """
+        Get column descriptions from last query.
+
+        Returns 7-item tuples: (name, type_code, display_size, internal_size,
+        precision, scale, null_ok). We only provide name and type_code.
+        """
+        return self._description
+
+    @property
+    def rowcount(self) -> int:
+        """Get number of rows affected by last operation."""
+        return self._rowcount
+
+    @property
+    def arraysize(self) -> int:
+        """Get default number of rows to fetch."""
+        return self._arraysize
+
+    @arraysize.setter
+    def arraysize(self, size: int) -> None:
+        """Set default number of rows to fetch."""
+        self._arraysize = size
+
+    def close(self) -> None:
+        """Close the cursor."""
+        if self._closed:
+            return
+
+        try:
+            if self._jdbc_resultset is not None:
+                self._jdbc_resultset.close()
+            if self._jdbc_statement is not None:
+                self._jdbc_statement.close()
+        except Exception as e:
+            logger.warning(f"Error closing cursor: {e}")
+        finally:
+            self._jdbc_resultset = None
+            self._jdbc_statement = None
+            self._closed = True
+
+    def execute(
+        self, operation: str, parameters: Sequence[Any] | None = None
+    ) -> Cursor:
+        """
+        Execute a database operation.
+
+        Args:
+            operation: SQL query or command
+            parameters: Parameters for the query
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ProgrammingError: If cursor is closed or operation fails
+        """
+        if self._closed:
+            raise InterfaceError("Cursor is closed")
+
+        try:
+            # Close previous statement and resultset
+            if self._jdbc_statement is not None:
+                self._jdbc_statement.close()
+            if self._jdbc_resultset is not None:
+                self._jdbc_resultset.close()
+
+            self._description = None
+            self._rowcount = -1
+
+            # Prepare statement
+            if parameters:
+                self._jdbc_statement = self._jdbc_connection.prepareStatement(operation)
+                self._bind_parameters(self._jdbc_statement, parameters)
+                has_resultset = self._jdbc_statement.execute()
+            else:
+                self._jdbc_statement = self._jdbc_connection.createStatement()
+                has_resultset = self._jdbc_statement.execute(operation)
+
+            # Process results
+            if has_resultset:
+                self._jdbc_resultset = self._jdbc_statement.getResultSet()
+                self._build_description()
+            else:
+                self._rowcount = self._jdbc_statement.getUpdateCount()
+
+            return self
+
+        except Exception as e:
+            logger.exception(f"Execute failed: {e}")
+            raise ProgrammingError(f"Failed to execute operation: {e}") from e
+
+    def executemany(
+        self, operation: str, seq_of_parameters: Sequence[Sequence[Any]]
+    ) -> None:
+        """
+        Execute a database operation multiple times.
+
+        Args:
+            operation: SQL query or command
+            seq_of_parameters: Sequence of parameter sequences
+
+        Raises:
+            ProgrammingError: If operation fails
+        """
+        if self._closed:
+            raise InterfaceError("Cursor is closed")
+
+        try:
+            self._jdbc_statement = self._jdbc_connection.prepareStatement(operation)
+
+            for parameters in seq_of_parameters:
+                self._bind_parameters(self._jdbc_statement, parameters)
+                self._jdbc_statement.addBatch()
+
+            results = self._jdbc_statement.executeBatch()
+            self._rowcount = sum(r for r in results if r >= 0)
+
+        except Exception as e:
+            logger.exception(f"ExecuteManyJDBC failed: {e}")
+            raise ProgrammingError(f"Failed to execute batch: {e}") from e
+
+    def fetchone(self) -> tuple[Any, ...] | None:
+        """
+        Fetch next row from query result.
+
+        Returns:
+            Tuple of column values or None if no more rows
+
+        Raises:
+            InterfaceError: If no query has been executed
+        """
+        if self._jdbc_resultset is None:
+            raise InterfaceError("No query has been executed")
+
+        try:
+            if self._jdbc_resultset.next():
+                return self._fetch_row()
+            return None
+        except Exception as e:
+            raise DataError(f"Failed to fetch row: {e}") from e
+
+    def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
+        """
+        Fetch multiple rows from query result.
+
+        Args:
+            size: Number of rows to fetch (default: arraysize)
+
+        Returns:
+            List of row tuples
+
+        Raises:
+            InterfaceError: If no query has been executed
+        """
+        if self._jdbc_resultset is None:
+            raise InterfaceError("No query has been executed")
+
+        if size is None:
+            size = self._arraysize
+
+        rows = []
+        try:
+            for _ in range(size):
+                if self._jdbc_resultset.next():
+                    rows.append(self._fetch_row())
+                else:
+                    break
+            return rows
+        except Exception as e:
+            raise DataError(f"Failed to fetch rows: {e}") from e
+
+    def fetchall(self) -> list[tuple[Any, ...]]:
+        """
+        Fetch all remaining rows from query result.
+
+        Returns:
+            List of row tuples
+
+        Raises:
+            InterfaceError: If no query has been executed
+        """
+        if self._jdbc_resultset is None:
+            raise InterfaceError("No query has been executed")
+
+        rows = []
+        try:
+            while self._jdbc_resultset.next():
+                rows.append(self._fetch_row())
+            return rows
+        except Exception as e:
+            raise DataError(f"Failed to fetch all rows: {e}") from e
+
+    def setinputsizes(self, sizes: Sequence[int | None]) -> None:
+        """Does nothing, for DB-API 2.0 compliance."""
+        # JDBC handles this automatically, so we just ignore it
+
+    def setoutputsize(self, size: int, column: int | None = None) -> None:
+        """Does nothing, for DB-API 2.0 compliance."""
+        # Same as above - JDBC doesn't need this hint
+
+    def _bind_parameters(self, statement: Any, parameters: Sequence[Any]) -> None:
+        """Bind parameters to prepared statement."""
+        # JDBC uses 1-based indexing for parameters (yeah, I know...)
+        for i, param in enumerate(parameters, start=1):
+            if param is None:
+                # NULL values need special handling in JDBC
+                statement.setNull(i, 0)  # 0 = java.sql.Types.NULL
+            else:
+                # setObject auto-converts Python types to Java
+                statement.setObject(i, param)
+
+    def _build_description(self) -> None:
+        """Build column description from ResultSetMetaData."""
+        if self._jdbc_resultset is None:
+            return
+
+        try:
+            metadata = self._jdbc_resultset.getMetaData()
+            column_count = metadata.getColumnCount()
+
+            description = []
+            for i in range(1, column_count + 1):
+                name = metadata.getColumnName(i)
+                type_code = metadata.getColumnType(i)
+                description.append(
+                    (
+                        name,
+                        type_code,
+                        None,  # display_size
+                        None,  # internal_size
+                        None,  # precision
+                        None,  # scale
+                        None,  # null_ok
+                    )
+                )
+
+            self._description = tuple(description)
+
+        except Exception as e:
+            logger.warning(f"Failed to build description: {e}")
+            self._description = None
+
+    def _fetch_row(self) -> tuple[Any, ...]:
+        """Fetch a single row and convert types."""
+        if self._jdbc_resultset is None or self._description is None:
+            return ()
+
+        row = []
+        for i, (name, type_code, *_) in enumerate(self._description, start=1):
+            value = self._type_converter.convert_from_jdbc(
+                self._jdbc_resultset, i, type_code
+            )
+            row.append(value)
+
+        return tuple(row)
+
+    def __enter__(self) -> Cursor:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def __iter__(self) -> Cursor:
+        """Make cursor iterable."""
+        return self
+
+    def __next__(self) -> tuple[Any, ...]:
+        """Fetch next row for iteration."""
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row