FQE-1715 - Microsoft Access handler error (#11825)

Author: setohe0909

mindsdb/integrations/handlers/access_handler/README.md

@@ -1,28 +1,32 @@
-# Microsoft Access Handler
-
-This is the implementation of the Microsoft Access handler for MindsDB.
-
-## Microsoft Access
-Microsoft Access is a pseudo-relational database engine from Microsoft. It is part of the Microsoft Office suite of applications that also includes Word, Outlook and Excel, among others. Access is also available for purchase as a stand-alone product. Access uses the Jet Database Engine for data storage.
-https://www.techopedia.com/definition/1218/microsoft-access
-
-## Implementation
-This handler was implemented using `pyodbc`, the Python ODBC bridge.
-
-The only required argument to establish a connection is `db_file`. This points to the database file that the connection is to be made to.
-
-## Usage
-In order to make use of this handler and connect to an Access database in MindsDB, the following syntax can be used,
-~~~~sql
-CREATE DATABASE access_datasource
-WITH
-engine='access',
-parameters={
-    "db_file":"C:\\Users\\minurap\\Documents\\example_db.accdb"
-};
-~~~~
-
-Now, you can use this established connection to query your database as follows,
-~~~~sql
-SELECT * FROM access_datasource.example_tbl
+# Microsoft Access Handler
+
+This is the implementation of the Microsoft Access handler for MindsDB.
+
+## Microsoft Access
+Microsoft Access is a pseudo-relational database engine from Microsoft. It is part of the Microsoft Office suite of applications that also includes Word, Outlook and Excel, among others. Access is also available for purchase as a stand-alone product. Access uses the Jet Database Engine for data storage.
+https://www.techopedia.com/definition/1218/microsoft-access
+
+## Implementation
+This handler was implemented using `pyodbc`, the Python ODBC bridge.
+
+**Platform Requirements:**
+- **Windows Only**: This handler requires the Microsoft Access ODBC driver, which is only available on Windows operating systems.
+- The Microsoft Access Driver (*.mdb, *.accdb) must be installed on the system.
+
+The only required argument to establish a connection is `db_file`. This points to the database file that the connection is to be made to.
+
+## Usage
+In order to make use of this handler and connect to an Access database in MindsDB, the following syntax can be used,
+~~~~sql
+CREATE DATABASE access_datasource
+WITH
+engine='access',
+parameters={
+    "db_file":"C:\\Users\\minurap\\Documents\\example_db.accdb"
+};
+~~~~
+
+Now, you can use this established connection to query your database as follows,
+~~~~sql
+SELECT * FROM access_datasource.example_tbl
 ~~~~

mindsdb/integrations/handlers/access_handler/__about__.py

@@ -1,9 +1,9 @@
-__title__ = 'MindsDB Microsoft Access handler'
-__package_name__ = 'mindsdb_access_handler'
-__version__ = '0.0.1'
+__title__ = "MindsDB Microsoft Access handler"
+__package_name__ = "mindsdb_access_handler"
+__version__ = "0.0.1"
 __description__ = "MindsDB handler for Microsoft Access"
-__author__ = 'Minura Punchihewa'
-__github__ = 'https://github.com/mindsdb/mindsdb'
-__pypi__ = 'https://pypi.org/project/mindsdb/'
-__license__ = 'MIT'
-__copyright__ = 'Copyright 2022 - MindsDB'
+__author__ = "Minura Punchihewa"
+__github__ = "https://github.com/mindsdb/mindsdb"
+__pypi__ = "https://pypi.org/project/mindsdb/"
+__license__ = "MIT"
+__copyright__ = "Copyright 2025 - MindsDB"

mindsdb/integrations/handlers/access_handler/access_handler.py

@@ -1,22 +1,29 @@
 from typing import Optional
+import platform
 
 import pandas as pd
-import pyodbc
 
 from mindsdb_sql_parser import parse_sql
-from mindsdb.utilities.render.sqlalchemy_render import SqlalchemyRender
-from sqlalchemy_access.base import AccessDialect
-from mindsdb.integrations.libs.base import DatabaseHandler
-
 from mindsdb_sql_parser.ast.base import ASTNode
-
 from mindsdb.utilities import log
+from mindsdb.utilities.render.sqlalchemy_render import SqlalchemyRender
+from mindsdb.integrations.libs.base import DatabaseHandler
 from mindsdb.integrations.libs.response import (
     HandlerStatusResponse as StatusResponse,
     HandlerResponse as Response,
-    RESPONSE_TYPE
+    RESPONSE_TYPE,
 )
 
+try:
+    import pyodbc
+    from sqlalchemy_access.base import AccessDialect
+
+    IMPORT_ERROR = None
+except ImportError as e:
+    pyodbc = None
+    AccessDialect = None
+    IMPORT_ERROR = e
+
 logger = log.getLogger(__name__)
 
 
@@ -25,7 +32,7 @@ class AccessHandler(DatabaseHandler):
     This handler handles connection and execution of the Microsoft Access statements.
     """
 
-    name = 'access'
+    name = "access"
 
     def __init__(self, name: str, connection_data: Optional[dict], **kwargs):
         """
@@ -37,7 +44,7 @@ def __init__(self, name: str, connection_data: Optional[dict], **kwargs):
         """
         super().__init__(name)
         self.parser = parse_sql
-        self.dialect = 'access'
+        self.dialect = "access"
         self.connection_data = connection_data
         self.kwargs = kwargs
 
@@ -48,18 +55,29 @@ def __del__(self):
         if self.is_connected is True:
             self.disconnect()
 
-    def connect(self) -> StatusResponse:
+    def connect(self):
         """
         Set up the connection required by the handler.
         Returns:
-            HandlerStatusResponse
+            pyodbc.Connection: A connection object to the Access database.
         """
-
         if self.is_connected is True:
             return self.connection
 
+        if IMPORT_ERROR is not None:
+            raise RuntimeError(
+                f"Microsoft Access handler requires pyodbc and sqlalchemy-access packages. "
+                f"Install them with: pip install pyodbc sqlalchemy-access. Error: {IMPORT_ERROR}"
+            )
+
+        if platform.system() != "Windows":
+            raise RuntimeError(
+                "Microsoft Access handler is only supported on Windows. "
+                "The Microsoft Access ODBC driver is not available on other operating systems."
+            )
+
         self.connection = pyodbc.connect(
-            r'Driver={Microsoft Access Driver (*.mdb, *.accdb)};DBQ=' + self.connection_data['db_file']
+            r"Driver={Microsoft Access Driver (*.mdb, *.accdb)};DBQ=" + self.connection_data["db_file"]
         )
         self.is_connected = True
 
@@ -69,7 +87,6 @@ def disconnect(self):
         """
         Close any existing connections.
         """
-
         if self.is_connected is False:
             return
 
@@ -83,15 +100,14 @@ def check_connection(self) -> StatusResponse:
         Returns:
             HandlerStatusResponse
         """
-
         response = StatusResponse(False)
         need_to_close = self.is_connected is False
 
         try:
             self.connect()
             response.success = True
         except Exception as e:
-            logger.error(f'Error connecting to SQLite {self.connection_data["db_file"]}, {e}!')
+            logger.error(f"Error connecting to Microsoft Access database {self.connection_data['db_file']}, {e}!")
             response.error_message = str(e)
         finally:
             if response.success is True and need_to_close:
@@ -109,7 +125,6 @@ def native_query(self, query: str) -> StatusResponse:
         Returns:
             HandlerResponse
         """
-
         need_to_close = self.is_connected is False
 
         connection = self.connect()
@@ -120,21 +135,15 @@ def native_query(self, query: str) -> StatusResponse:
                 if result:
                     response = Response(
                         RESPONSE_TYPE.TABLE,
-                        data_frame=pd.DataFrame.from_records(
-                            result,
-                            columns=[x[0] for x in cursor.description]
-                        )
+                        data_frame=pd.DataFrame.from_records(result, columns=[x[0] for x in cursor.description]),
                     )
 
                 else:
                     response = Response(RESPONSE_TYPE.OK)
                     connection.commit()
             except Exception as e:
-                logger.error(f'Error running query: {query} on {self.connection_data["db_file"]}!')
-                response = Response(
-                    RESPONSE_TYPE.ERROR,
-                    error_message=str(e)
-                )
+                logger.error(f"Error running query: {query} on {self.connection_data['db_file']}!")
+                response = Response(RESPONSE_TYPE.ERROR, error_message=str(e))
 
         if need_to_close is True:
             self.disconnect()
@@ -150,6 +159,11 @@ def query(self, query: ASTNode) -> StatusResponse:
         Returns:
             HandlerResponse
         """
+        if IMPORT_ERROR is not None:
+            raise RuntimeError(
+                f"Microsoft Access handler requires pyodbc and sqlalchemy-access packages. "
+                f"Install them with: pip install pyodbc sqlalchemy-access. Error: {IMPORT_ERROR}"
+            )
 
         renderer = SqlalchemyRender(AccessDialect)
         query_str = renderer.get_string(query, with_failback=True)
@@ -161,15 +175,11 @@ def get_tables(self) -> StatusResponse:
         Returns:
             HandlerResponse
         """
-
         connection = self.connect()
         with connection.cursor() as cursor:
-            df = pd.DataFrame([table.table_name for table in cursor.tables(tableType='Table')], columns=['table_name'])
+            df = pd.DataFrame([table.table_name for table in cursor.tables(tableType="Table")], columns=["table_name"])
 
-        response = Response(
-            RESPONSE_TYPE.TABLE,
-            df
-        )
+        response = Response(RESPONSE_TYPE.TABLE, df)
 
         return response
 
@@ -181,17 +191,13 @@ def get_columns(self, table_name: str) -> StatusResponse:
         Returns:
             HandlerResponse
         """
-
         connection = self.connect()
         with connection.cursor() as cursor:
             df = pd.DataFrame(
                 [(column.column_name, column.type_name) for column in cursor.columns(table=table_name)],
-                columns=['column_name', 'data_type']
+                columns=["column_name", "data_type"],
             )
 
-        response = Response(
-            RESPONSE_TYPE.TABLE,
-            df
-        )
+        response = Response(RESPONSE_TYPE.TABLE, df)
 
         return response

mindsdb/integrations/handlers/access_handler/connection_args.py

@@ -5,11 +5,11 @@
 
 connection_args = OrderedDict(
     db_file={
-        'type': ARG_TYPE.STR,
-        'description': 'The database file where the data will be stored.'
+        "type": ARG_TYPE.PATH,
+        "description": "The full path to the Microsoft Access database file (.mdb or .accdb). On Windows, use absolute paths like C:\\Users\\username\\Documents\\database.accdb",
+        "required": True,
+        "label": "Database File Path",
     }
 )
 
-connection_args_example = OrderedDict(
-    db_file='C:\\Users\\minurap\\Documents\\example_db.accdb'
-)
+connection_args_example = OrderedDict(db_file="C:\\Users\\minurap\\Documents\\example_db.accdb")

mindsdb/integrations/handlers/access_handler/requirements.txt

@@ -1,2 +1,2 @@
-pyodbc
-sqlalchemy-access
+pyodbc>=5.0.0; sys_platform == 'win32'
+sqlalchemy-access>=2.0.0; sys_platform == 'win32'