matrixone-python-sdk 0.1.14__tar.gz → 0.1.16__tar.gz

{matrixone_python_sdk-0.1.14/matrixone_python_sdk.egg-info → matrixone_python_sdk-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixone-python-sdk
-Version: 0.1.14
+Version: 0.1.16
 Summary: A comprehensive Python SDK for MatrixOne database operations with vector search, fulltext search, and advanced features
 Home-page: https://github.com/matrixorigin/matrixone
 Author: MatrixOne Team

{matrixone_python_sdk-0.1.14 → matrixone_python_sdk-0.1.16}/README.md

@@ -56,11 +56,18 @@ A comprehensive Python SDK for MatrixOne that provides SQLAlchemy-like interface
 - 📸 **Snapshot Management**: Create and manage database snapshots at multiple levels
 - ⏰ **Point-in-Time Recovery**: PITR functionality for precise data recovery
 - 🔄 **Table Cloning**: Clone databases and tables efficiently with data replication
+  - ⭐ **SQLAlchemy-style statement builders** (`clone_table()`, `clone_database()`)
+  - Snapshot-based point-in-time cloning
+  - Cross-tenant cloning with TO ACCOUNT support
+  - IF NOT EXISTS for idempotent operations
 - 🌿 **Branch Management**: Git-style version control for databases and tables
   - Create isolated branches for development and testing
   - Compare differences between branches with count-only optimization
   - Merge branches with conflict resolution strategies
   - Point-in-time branching from snapshots
+  - ⭐ **SQLAlchemy-style statement builders** (`create_table_branch()`, `diff_table_branch()`, etc.)
+  - Advanced DIFF output: COUNT, LIMIT, FILE export, snapshot on both sides
+  - Cross-tenant branching with TO ACCOUNT support
 - 👥 **Account Management**: Comprehensive user, role, and permission management
 - 📊 **Pub/Sub**: Real-time publication and subscription support
 - 🔧 **Version Management**: Automatic backend version detection and compatibility checking
@@ -1384,6 +1391,12 @@ Check out the `examples/` directory for comprehensive usage examples:
 **Stage Management Examples:**
 - `example_26_stage_operations.py` - External stage management and data loading from stages
 
+**Branch Builder Examples:**
+- `example_branch_builder.py` - SQLAlchemy-style branch statement builders (create, diff, merge)
+
+**Clone Builder Examples:**
+- `example_clone_builder.py` - SQLAlchemy-style clone statement builders (table, database)
+
 **Specialized Examples:**
 - `example_connection_hooks.py` - Connection hooks for custom initialization
 - `example_dynamic_logging.py` - Dynamic logging configuration

matrixone_python_sdk-0.1.16/examples/example_branch_builder.py

@@ -0,0 +1,226 @@
+"""
+Example: Branch Statement Builders - SQLAlchemy Style API
+
+This example demonstrates the new branch statement builders that work like
+SQLAlchemy's select(), insert(), delete(), update() functions.
+
+No client dependency - just build SQL statements and execute them.
+"""
+
+from matrixone.branch_builder import (
+    create_table_branch,
+    create_database_branch,
+    delete_table_branch,
+    delete_database_branch,
+    diff_table_branch,
+    merge_table_branch,
+)
+
+
+def example_create_table_branch():
+    """Create table branch statements"""
+    print("=" * 60)
+    print("CREATE TABLE BRANCH Examples")
+    print("=" * 60)
+
+    # Basic table branch
+    stmt = create_table_branch('users_dev').from_table('users')
+    print(f"Basic: {stmt}")
+
+    # With snapshot
+    stmt = create_table_branch('users_backup').from_table('users', snapshot='daily_snap')
+    print(f"With snapshot: {stmt}")
+
+    # Cross-tenant (sys only)
+    stmt = create_table_branch('users_dev').from_table('users').to_account('tenant1')
+    print(f"Cross-tenant: {stmt}")
+
+    # Full example
+    stmt = create_table_branch('users_historical').from_table('users', snapshot='2024_01_01').to_account('analytics_team')
+    print(f"Full: {stmt}\n")
+
+
+def example_create_database_branch():
+    """Create database branch statements"""
+    print("=" * 60)
+    print("CREATE DATABASE BRANCH Examples")
+    print("=" * 60)
+
+    # Basic database branch
+    stmt = create_database_branch('dev_db').from_database('prod_db')
+    print(f"Basic: {stmt}")
+
+    # With snapshot
+    stmt = create_database_branch('backup_db').from_database('prod_db', snapshot='weekly_snap')
+    print(f"With snapshot: {stmt}")
+
+    # Cross-tenant
+    stmt = create_database_branch('dev_db').from_database('prod_db').to_account('dev_team')
+    print(f"Cross-tenant: {stmt}\n")
+
+
+def example_delete_branch():
+    """Delete branch statements"""
+    print("=" * 60)
+    print("DELETE BRANCH Examples")
+    print("=" * 60)
+
+    # Delete table branch
+    stmt = delete_table_branch('users_dev')
+    print(f"Delete table: {stmt}")
+
+    # Delete database branch
+    stmt = delete_database_branch('dev_db')
+    print(f"Delete database: {stmt}\n")
+
+
+def example_diff_branch():
+    """Diff branch statements"""
+    print("=" * 60)
+    print("DIFF BRANCH Examples")
+    print("=" * 60)
+
+    # Basic diff
+    stmt = diff_table_branch('users_dev').against('users')
+    print(f"Basic diff: {stmt}")
+
+    # Diff with snapshots
+    stmt = diff_table_branch('users').snapshot('snap_v1').against('users', snapshot='snap_v2')
+    print(f"With snapshots: {stmt}")
+
+    # Diff with output count
+    stmt = diff_table_branch('users_dev').against('users').output_count()
+    print(f"Output count: {stmt}")
+
+    # Diff with output limit
+    stmt = diff_table_branch('users_dev').against('users').output_limit(100)
+    print(f"Output limit: {stmt}")
+
+    # Diff with file export (local)
+    stmt = diff_table_branch('users_dev').against('users').output_file('/tmp/diff.sql')
+    print(f"Export to file: {stmt}")
+
+    # Diff with file export (stage)
+    stmt = diff_table_branch('users_dev').against('users').output_file('stage://backup_stage/')
+    print(f"Export to stage: {stmt}")
+
+    # Diff with output as table
+    stmt = diff_table_branch('users_dev').against('users').output_as('diff_result')
+    print(f"Output as table: {stmt}\n")
+
+
+def example_merge_branch():
+    """Merge branch statements"""
+    print("=" * 60)
+    print("MERGE BRANCH Examples")
+    print("=" * 60)
+
+    # Basic merge (default: skip conflicts)
+    stmt = merge_table_branch('users_dev').into('users')
+    print(f"Basic merge (skip): {stmt}")
+
+    # Merge with accept strategy
+    stmt = merge_table_branch('users_dev').into('users').when_conflict('accept')
+    print(f"Merge (accept): {stmt}")
+
+    # Merge with enum
+    from matrixone.branch_builder import MergeConflictStrategy
+
+    stmt = merge_table_branch('users_dev').into('users').when_conflict(MergeConflictStrategy.ACCEPT)
+    print(f"Merge with enum: {stmt}\n")
+
+
+def example_with_session():
+    """Example of using statements with session"""
+    print("=" * 60)
+    print("Using with Session")
+    print("=" * 60)
+
+    # Build statements
+    create_stmt = create_table_branch('users_dev').from_table('users')
+    diff_stmt = diff_table_branch('users_dev').against('users').output_count()
+    merge_stmt = merge_table_branch('users_dev').into('users')
+
+    print("Statements ready to execute:")
+    print(f"  1. {create_stmt}")
+    print(f"  2. {diff_stmt}")
+    print(f"  3. {merge_stmt}")
+
+    print("\nUsage with session:")
+    print("""
+    from matrixone import Client
+    
+    client = Client()
+    client.connect(database='test')
+    
+    # Execute statements
+    with client.session() as session:
+        # Create branch
+        session.execute(create_table_branch('users_dev').from_table('users'))
+        
+        # Check differences
+        result = session.execute(
+            diff_table_branch('users_dev').against('users').output_count()
+        )
+        print(f"Differences: {result.fetchone()}")
+        
+        # Merge back
+        session.execute(
+            merge_table_branch('users_dev').into('users').when_conflict('accept')
+        )
+    """)
+
+
+def example_complex_workflow():
+    """Complex workflow example"""
+    print("=" * 60)
+    print("Complex Workflow Example")
+    print("=" * 60)
+
+    print("""
+    # Development workflow with branches
+    
+    # 1. Create development branch from production
+    create_dev = create_table_branch('orders_dev').from_table('orders')
+    
+    # 2. Create testing branch from development
+    create_test = create_table_branch('orders_test').from_table('orders_dev')
+    
+    # 3. Compare test with production
+    diff_test = (diff_table_branch('orders_test')
+                 .against('orders')
+                 .output_file('stage://reports/test_diff.sql'))
+    
+    # 4. Merge test back to production
+    merge_prod = (merge_table_branch('orders_test')
+                  .into('orders')
+                  .when_conflict('accept'))
+    
+    # 5. Clean up development branch
+    delete_dev = delete_table_branch('orders_dev')
+    
+    # Execute in transaction
+    with client.session() as session:
+        session.execute(create_dev)
+        session.execute(create_test)
+        
+        # Verify differences
+        result = session.execute(
+            diff_table_branch('orders_test').against('orders').output_count()
+        )
+        
+        if result.fetchone()[0] == 0:
+            # No differences, safe to merge
+            session.execute(merge_prod)
+            session.execute(delete_dev)
+    """)
+
+
+if __name__ == '__main__':
+    example_create_table_branch()
+    example_create_database_branch()
+    example_delete_branch()
+    example_diff_branch()
+    example_merge_branch()
+    example_with_session()
+    example_complex_workflow()

matrixone_python_sdk-0.1.16/examples/example_clone_builder.py

@@ -0,0 +1,54 @@
+"""
+Example: Clone Statement Builders - SQLAlchemy Style API
+
+Demonstrates the clone statement builders that produce SQL strings
+independently of the client, similar to SQLAlchemy's select()/insert().
+"""
+
+from matrixone.clone_builder import clone_table, clone_database
+
+
+def example_clone_table():
+    print("=" * 60)
+    print("CLONE TABLE Examples")
+    print("=" * 60)
+
+    stmt = clone_table('users_copy').from_table('users')
+    print(f"Basic:            {stmt}")
+
+    stmt = clone_table('users_copy').if_not_exists().from_table('users')
+    print(f"If not exists:    {stmt}")
+
+    stmt = clone_table('users_copy').from_table('users', snapshot='snap1')
+    print(f"With snapshot:    {stmt}")
+
+    stmt = clone_table('db2.users').from_table('db1.users')
+    print(f"Cross-database:   {stmt}")
+
+    stmt = clone_table('users_copy').if_not_exists().from_table('users', snapshot='snap1').to_account('tenant1')
+    print(f"Cross-tenant:     {stmt}")
+    print()
+
+
+def example_clone_database():
+    print("=" * 60)
+    print("CLONE DATABASE Examples")
+    print("=" * 60)
+
+    stmt = clone_database('dev_db').from_database('prod_db')
+    print(f"Basic:            {stmt}")
+
+    stmt = clone_database('dev_db').if_not_exists().from_database('prod_db')
+    print(f"If not exists:    {stmt}")
+
+    stmt = clone_database('dev_db').from_database('prod_db', snapshot='daily_snap')
+    print(f"With snapshot:    {stmt}")
+
+    stmt = clone_database('dev_db').from_database('prod_db', snapshot='snap1').to_account('acc1')
+    print(f"Cross-tenant:     {stmt}")
+    print()
+
+
+if __name__ == '__main__':
+    example_clone_table()
+    example_clone_database()

{matrixone_python_sdk-0.1.14 → matrixone_python_sdk-0.1.16}/matrixone/__init__.py

@@ -57,6 +57,19 @@ from .restore import RestoreManager
 from .snapshot import Snapshot, SnapshotLevel, SnapshotManager
 from .clone import CloneManager
 from .branch import BranchManager, AsyncBranchManager, DiffOutput, MergeConflictStrategy
+from .branch_builder import (
+    create_table_branch,
+    create_database_branch,
+    delete_table_branch,
+    delete_database_branch,
+    diff_table_branch,
+    merge_table_branch,
+    DiffOutputOption,
+)
+from .clone_builder import (
+    clone_table,
+    clone_database,
+)
 from .stage import Stage, StageManager, AsyncStageManager
 from .cdc import CDCTaskInfo, CDCWatermarkInfo, CDCManager, AsyncCDCManager, build_mysql_uri
 from .ivf_rank import IVFRankMode, IVFRankOptions
@@ -122,6 +135,17 @@ __all__ = [
     "CloneManager",
     "BranchManager",
     "AsyncBranchManager",
+    "DiffOutput",
+    "MergeConflictStrategy",
+    "create_table_branch",
+    "create_database_branch",
+    "delete_table_branch",
+    "delete_database_branch",
+    "diff_table_branch",
+    "merge_table_branch",
+    "DiffOutputOption",
+    "clone_table",
+    "clone_database",
     "SnapshotLevel",
     "MoCtlManager",
     "RestoreManager",

matrixone_python_sdk-0.1.16/matrixone/_utils.py

@@ -0,0 +1,37 @@
+"""Shared internal utilities for MatrixOne SDK modules."""
+
+from typing import Union, Type
+
+try:
+    from sqlalchemy.orm import DeclarativeMeta as _unused  # noqa: F401
+
+    SQLALCHEMY_AVAILABLE = True
+except ImportError:
+    SQLALCHEMY_AVAILABLE = False
+
+
+def get_table_name(table: Union[str, Type]) -> str:
+    """Extract table name from string or ORM model.
+
+    Supports:
+    - "table_name"
+    - "db.table_name"
+    - ORM model with optional __table_args__['schema'] for db.table
+    """
+    if isinstance(table, str):
+        return table
+    if SQLALCHEMY_AVAILABLE and hasattr(table, '__tablename__'):
+        name = table.__tablename__
+        if hasattr(table, '__table_args__'):
+            args = table.__table_args__
+            if isinstance(args, dict) and 'schema' in args:
+                return f"{args['schema']}.{name}"
+        return name
+    raise ValueError(f"Invalid table parameter: {table}. Expected string or ORM model.")
+
+
+def require_non_empty(value: str, param_name: str) -> str:
+    """Validate that a string parameter is non-empty."""
+    if not value:
+        raise ValueError(f"{param_name} must be a non-empty string")
+    return value

{matrixone_python_sdk-0.1.14 → matrixone_python_sdk-0.1.16}/matrixone/async_client.py

@@ -23,11 +23,13 @@ except ImportError:
 
 try:
     from sqlalchemy import text
+    from sqlalchemy.engine import URL
     from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 except ImportError:
     create_async_engine = None
     AsyncEngine = None
     text = None
+    URL = None
 
 from contextlib import asynccontextmanager
 from datetime import datetime
@@ -862,19 +864,21 @@ class AsyncClient(BaseMatrixOneClient):
         if not create_async_engine:
             raise ConnectionError("SQLAlchemy async engine not available. Please install sqlalchemy[asyncio]")
 
-        # Build connection string for async engine
-        connection_string = (
-            f"mysql+aiomysql://{self._connection_params['user']}:"
-            f"{self._connection_params['password']}@"
-            f"{self._connection_params['host']}:"
-            f"{self._connection_params['port']}/"
-            f"{self._connection_params['database'] or ''}"
-            f"?charset={self._connection_params['charset']}"
+        # Build connection URL using SQLAlchemy's URL.create() for proper escaping
+        # of special characters in user/password (e.g., @, #, %, etc.)
+        url = URL.create(
+            drivername="mysql+aiomysql",
+            username=self._connection_params["user"],
+            password=self._connection_params["password"],
+            host=self._connection_params["host"],
+            port=self._connection_params["port"],
+            database=self._connection_params["database"] or None,
+            query={"charset": self._connection_params["charset"]},
         )
 
         # Create async engine with connection pooling
         engine = create_async_engine(
-            connection_string,
+            url,
             pool_size=5,  # Smaller pool size for testing
             max_overflow=10,  # Smaller max overflow
             pool_timeout=30,  # Default pool timeout
@@ -1015,9 +1019,7 @@ class AsyncClient(BaseMatrixOneClient):
 
         return self
 
-    async def _execute_with_logging(
-        self, connection, sql: str, context: str = "Async SQL execution", override_sql_log_mode: str = None
-    ):
+    async def _execute_with_logging(self, connection, sql: str, context: str = "Async SQL execution", log_mode: str = None):
         """
         Execute SQL asynchronously with proper logging through the client's logger.
 
@@ -1029,7 +1031,7 @@ class AsyncClient(BaseMatrixOneClient):
             connection: SQLAlchemy async connection object
             sql: SQL query string
             context: Context description for error logging (default: "Async SQL execution")
-            override_sql_log_mode: Temporarily override sql_log_mode for this query only
+            log_mode: Temporarily override sql_log_mode for this query only
 
         Returns::
 
@@ -1054,26 +1056,24 @@ class AsyncClient(BaseMatrixOneClient):
                 if result.returns_rows:
                     # For SELECT queries, we can't consume the result to count rows
                     # So we just log without row count
-                    self.logger.log_query(
-                        sql, execution_time, None, success=True, override_sql_log_mode=override_sql_log_mode
-                    )
+                    self.logger.log_query(sql, execution_time, None, success=True, log_mode=log_mode)
                 else:
                     # For DML queries (INSERT/UPDATE/DELETE), we can get rowcount
-                    self.logger.log_query(
-                        sql, execution_time, result.rowcount, success=True, override_sql_log_mode=override_sql_log_mode
-                    )
+                    self.logger.log_query(sql, execution_time, result.rowcount, success=True, log_mode=log_mode)
             except Exception:
                 # Fallback: just log the query without row count
-                self.logger.log_query(sql, execution_time, None, success=True, override_sql_log_mode=override_sql_log_mode)
+                self.logger.log_query(sql, execution_time, None, success=True, log_mode=log_mode)
 
             return result
         except Exception as e:
             execution_time = time.time() - start_time
-            self.logger.log_query(sql, execution_time, success=False, override_sql_log_mode=override_sql_log_mode)
+            self.logger.log_query(sql, execution_time, success=False, log_mode=log_mode)
             self.logger.log_error(e, context=context)
-            raise
+            from .client import _classify_db_error
 
-    async def execute(self, sql_or_stmt, params: Optional[Tuple] = None, _log_mode: str = None) -> AsyncResultSet:
+            raise _classify_db_error(e, sql) from None
+
+    async def execute(self, sql_or_stmt, params: Optional[Tuple] = None, log_mode: str = None) -> AsyncResultSet:
         """
         Execute SQL query or SQLAlchemy statement asynchronously without transaction isolation.
 
@@ -1107,7 +1107,7 @@ class AsyncClient(BaseMatrixOneClient):
                 substituted for '?' placeholders in order. Automatically escaped to prevent
                 SQL injection. Ignored for SQLAlchemy statements.
 
-            _log_mode (Optional[str]): Override SQL logging mode for this query only.
+            log_mode (Optional[str]): Override SQL logging mode for this query only.
                 Options: 'off', 'simple', 'full'. If None, uses client's global sql_log_mode
                 setting. Useful for debugging or disabling logs for frequently-executed queries.
 
@@ -1293,13 +1293,13 @@ class AsyncClient(BaseMatrixOneClient):
                 # Disable logging for frequently executed query
                 result = await client.execute(
                     select(User).where(User.id == 1),
-                    _log_mode='off'
+                    log_mode='off'
                 )
 
                 # Force full SQL logging for debugging
                 result = await client.execute(
                     select(User).where(User.name.like('%test%')),
-                    _log_mode='full'
+                    log_mode='full'
                 )
 
                 await client.disconnect()
@@ -1321,7 +1321,7 @@ class AsyncClient(BaseMatrixOneClient):
         2. **Use parameters**: Always use parameter binding to prevent SQL injection
         3. **Session for transactions**: Use client.session() for atomic operations
         4. **Use asyncio.gather()**: For concurrent independent queries
-        5. **Disable logging in production**: Use _log_mode='off' for hot paths
+        5. **Disable logging in production**: Use log_mode='off' for hot paths
         6. **Handle exceptions**: Wrap execute() in try-except for error handling
 
         See Also:
@@ -1342,7 +1342,8 @@ class AsyncClient(BaseMatrixOneClient):
             if not isinstance(sql_or_stmt, str):
                 # SQLAlchemy statement - delegate to session for consistent behavior
                 async with self.session() as session:
-                    result = await session.execute(sql_or_stmt, params)
+                    # Suppress session-level logging; AsyncClient logs below
+                    result = await session.execute(sql_or_stmt, params, log_mode='off')
 
                     # Convert SQLAlchemy result to AsyncResultSet
                     if hasattr(result, 'returns_rows') and result.returns_rows:
@@ -1356,7 +1357,7 @@ class AsyncClient(BaseMatrixOneClient):
                             execution_time,
                             len(rows),
                             success=True,
-                            override_sql_log_mode=_log_mode,
+                            log_mode=log_mode,
                         )
                         return async_result
                     else:
@@ -1368,7 +1369,7 @@ class AsyncClient(BaseMatrixOneClient):
                             execution_time,
                             result.rowcount,
                             success=True,
-                            override_sql_log_mode=_log_mode,
+                            log_mode=log_mode,
                         )
                         return async_result
 
@@ -1394,15 +1395,11 @@ class AsyncClient(BaseMatrixOneClient):
                     rows = result.fetchall()
                     columns = list(result.keys()) if hasattr(result, "keys") else []
                     async_result = AsyncResultSet(columns, rows)
-                    self.logger.log_query(
-                        sql_or_stmt, execution_time, len(rows), success=True, override_sql_log_mode=_log_mode
-                    )
+                    self.logger.log_query(sql_or_stmt, execution_time, len(rows), success=True, log_mode=log_mode)
                     return async_result
                 else:
                     async_result = AsyncResultSet([], [], affected_rows=result.rowcount)
-                    self.logger.log_query(
-                        sql_or_stmt, execution_time, result.rowcount, success=True, override_sql_log_mode=_log_mode
-                    )
+                    self.logger.log_query(sql_or_stmt, execution_time, result.rowcount, success=True, log_mode=log_mode)
                     return async_result
 
         except Exception as e:
@@ -1420,82 +1417,9 @@ class AsyncClient(BaseMatrixOneClient):
 
                 print(f"Warning: Error logging failed: {log_err}", file=sys.stderr)
 
-            # Extract user-friendly error message
-            error_msg = str(e)
+            from .client import _classify_db_error
 
-            # Handle common database errors with helpful messages
-            # Check for "does not exist" first before "syntax error"
-            if (
-                'does not exist' in error_msg.lower()
-                or 'no such table' in error_msg.lower()
-                or 'doesn\'t exist' in error_msg.lower()
-            ):
-                # Table doesn't exist
-                import re
-
-                match = re.search(r"(?:table|database)\s+[\"']?(\w+)[\"']?\s+does not exist", error_msg, re.IGNORECASE)
-                if match:
-                    obj_name = match.group(1)
-                    raise QueryError(
-                        f"Table or database '{obj_name}' does not exist. "
-                        f"Create it first using client.create_table() or CREATE TABLE/DATABASE statement."
-                    ) from None
-                else:
-                    raise QueryError(f"Object not found: {error_msg}") from None
-
-            elif 'already exists' in error_msg.lower() and '1050' in error_msg:
-                # Table already exists
-                import re
-
-                match = re.search(r"table\s+(\w+)\s+already\s+exists", error_msg, re.IGNORECASE)
-                if match:
-                    table_name = match.group(1)
-                    raise QueryError(
-                        f"Table '{table_name}' already exists. "
-                        f"Use DROP TABLE {table_name} or client.drop_table() to remove it first."
-                    ) from None
-                else:
-                    raise QueryError(f"Object already exists: {error_msg}") from None
-
-            elif 'duplicate' in error_msg.lower() and ('1062' in error_msg or '1061' in error_msg):
-                # Duplicate key/entry
-                raise QueryError(
-                    f"Duplicate entry error: {error_msg}. "
-                    f"Check for duplicate primary key or unique constraint violations."
-                ) from None
-
-            elif 'syntax error' in error_msg.lower() or '1064' in error_msg:
-                # SQL syntax error
-                sql_preview = final_sql[:200] + '...' if len(final_sql) > 200 else final_sql
-                raise QueryError(f"SQL syntax error: {error_msg}\n" f"Query: {sql_preview}") from None
-
-            elif 'column' in error_msg.lower() and ('unknown' in error_msg.lower() or 'not found' in error_msg.lower()):
-                # Column doesn't exist
-                raise QueryError(f"Column not found: {error_msg}. " f"Check your column names and table schema.") from None
-
-            elif 'cannot be null' in error_msg.lower() or '1048' in error_msg:
-                # NULL constraint violation
-                raise QueryError(
-                    f"NULL constraint violation: {error_msg}. " f"Some columns require non-NULL values."
-                ) from None
-
-            elif 'not supported' in error_msg.lower() and '20105' in error_msg:
-                # MatrixOne-specific: feature not supported
-                raise QueryError(
-                    f"MatrixOne feature limitation: {error_msg}. "
-                    f"This feature may require additional configuration or is not yet supported."
-                ) from None
-
-            elif 'bind parameter' in error_msg.lower() or 'InvalidRequestError' in error_msg:
-                # SQLAlchemy bind parameter error
-                raise QueryError(
-                    f"Parameter binding error: {error_msg}. "
-                    f"This might be caused by special characters in your data (colons in JSON, etc.)"
-                ) from None
-
-            else:
-                # Generic error - cleaner message without full SQLAlchemy stack
-                raise QueryError(f"Query execution failed: {error_msg}") from None
+            raise _classify_db_error(e, sql_or_stmt) from None
 
     def _substitute_parameters(self, sql: str, params: Optional[Tuple] = None) -> str:
         """