dbtk 0.8.3__tar.gz → 0.8.4__tar.gz

{dbtk-0.8.3 → dbtk-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbtk
-Version: 0.8.3
+Version: 0.8.4
 Summary: Data Benders Toolkit - A lightweight toolkit for data integration, ELT and ETL
 Author: Scott Bailey <scottrbailey@gmail.com>
 License: MIT
@@ -61,9 +61,9 @@ Requires-Dist: usaddress>=0.5.11; python_version >= "3.7" and extra == "all"
 Requires-Dist: usaddress==0.5.10; python_version < "3.7" and extra == "all"
 Requires-Dist: oracledb>=1.0; python_version >= "3.7" and extra == "all"
 Requires-Dist: cx_Oracle>=8.0; python_version < "3.7" and extra == "all"
-Requires-Dist: oracledb>=1.0; python_version >= "3.7" and extra == "all"
 Requires-Dist: psycopg2-binary>=2.9; extra == "all"
 Requires-Dist: pymysql>=1.0; extra == "all"
+Requires-Dist: pyodbc<5.0,>=4.0.21; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov>=2.10; extra == "dev"

{dbtk-0.8.3 → dbtk-0.8.4}/dbtk/__init__.py

@@ -29,7 +29,7 @@ Direct connections:
     cursor = db.cursor()  # Returns Record objects
 """
 
-__version__ = '0.8.3'
+__version__ = '0.8.4'
 __author__ = 'Scott Bailey <scottrbailey@gmail.com>'
 
 from .database import Database

{dbtk-0.8.3 → dbtk-0.8.4}/dbtk/cli.py

@@ -4,6 +4,7 @@ import argparse
 import importlib.util
 import sys
 from .database import _get_all_drivers
+from .record import fixed_record_factory
 from . import config
 
 try:
@@ -51,18 +52,23 @@ def checkup():
             deps.append(dep.split('>=')[0].split('==')[0].split('<')[0].strip())
 
     installed = {_name_cleanup(d.name): d.version for d in distributions()}
-
-    print(f"{'Package':<20} {'Status':<8} {'Version'}")
-    print("-" * 40)
+    package_rec = fixed_record_factory([('Package', 22), ('Status', 8), ('Version', 15)])
+    driver_rec = fixed_record_factory([('DB Driver', 22), ('Priority*', 10),
+                                      ('Status', 9), ('Version', 8), ('Notes', 41)])
+    row = package_rec(*package_rec._fields)
+    print(row.to_line(True))
+    print("-" * row._line_len)
 
     for dep in deps:
         clean = dep.replace('-', '_')
         status = "✓" if _is_installed(clean) else "✗"
         version = installed.get(clean.lower(), '-')
-        print(f"{dep:<20} {status:<8} {version}")
-
-    print("\nDB Drivers           Priority* Status   Version")
-    print("-" * 56)
+        row = package_rec(dep, status, version)
+        print(row.to_line(True))
+    print("")
+    row = driver_rec(*driver_rec._fields)
+    print(row.to_line(True))
+    print("-" * 80)
     all_drivers = _get_all_drivers()
     by_type = {}
 
@@ -80,9 +86,6 @@ def checkup():
         drivers = sorted(by_type[db_type], key=lambda x: x[0])
         print(f"{db_type}")  # ← bold header
         for pri, name, info in drivers:
-            # ── 2-space indent for hierarchy
-            display_name = f"  {name}"  # ← indented
-
             try:
                 # see if driver has 'module' attribute to use instead of name
                 module_name = info.get('module', name)
@@ -90,7 +93,7 @@ def checkup():
                 version = installed.get(_name_cleanup(module_name), '--    ')
                 status = "✓" if spec else "✗"
             except ModuleNotFoundError:
-                version = '--   '
+                version = '--'
                 status = "✗"
             odbc_driver_name = info.get("odbc_driver_name")
             if odbc_driver_name:
@@ -101,8 +104,8 @@ def checkup():
                     note = f'({info.get("note")})'
                 else:
                     note = ''
-
-            print(f"{display_name:<20} {pri:<9} {status:<8} {version} {note}")
+            row = driver_rec(f'  {name}', pri, status, version, note)
+            print(row.to_line(True))
 
     print("\n* Lower priority = preferred")
 

{dbtk-0.8.3 → dbtk-0.8.4}/dbtk/config.py

@@ -208,7 +208,7 @@ class ConfigManager:
     4. ``~/.config/dbtk.yml`` (user config directory)
     5. ``~/.config/dbtk.yaml`` (user config directory)
 
-    If no config is found, creates a sample config at ``~/.config/dbtk.yml``.
+    If no config is found, creates a sample config at ``~/.config/dbtk_sample.yml``.
 
     Parameters
     ----------
@@ -252,7 +252,7 @@ class ConfigManager:
     * Connections require 'type' field (postgres, oracle, mysql, etc.)
     * Encrypted passwords require DBTK_ENCRYPTION_KEY environment variable
     * Environment variables can be used with ${VAR_NAME} syntax
-    * Sample config is created at ~/.config/dbtk.yml on first run if no config exists
+    * Sample config is created at ~/.config/dbtk_sample.yml on first run if no config exists
     """
 
     def __init__(self, config_file: Optional[Union[str, Path]] = None):
@@ -337,6 +337,11 @@ class ConfigManager:
             if not isinstance(config, dict):
                 raise ValueError(f"Invalid config file {self.config_file}.")
 
+            # Normalize empty/null sections to empty dicts
+            for section in ('connections', 'passwords', 'drivers'):
+                if config.get(section) is None:
+                    config[section] = {}
+
             # Validate connections section if it exists
             if 'connections' in config:
                 for name, conn in config.get('connections', {}).items():
@@ -968,15 +973,22 @@ def setup_config() -> None:
             print("Cancelled.")
             return
 
-    # Copy dbtk_sample.yml to target location
+    # Write user config from sample, minus the example connections/passwords
     sample_path = Path(__file__).parent / 'dbtk_sample.yml'
     if not sample_path.exists():
         print(f"⚠ Sample config not found at {sample_path}")
         print("Cannot continue without sample file.")
         return
 
-    shutil.copy(sample_path, config_path)
-    print(f"\n✓ Created config from sample at {config_path}")
+    with open(sample_path) as f:
+        config_data = yaml.safe_load(f) or {}
+    # keep settings but clear out example connections, passwords and drivers sections
+    config_data['connections'] = {}
+    config_data['passwords'] = {}
+    config_data['drivers'] = {}
+    with open(config_path, 'w') as f:
+        yaml.safe_dump(config_data, f, default_flow_style=False, sort_keys=False)
+    print(f"\n✓ Created config at {config_path}")
 
     # Also copy sample to ~/.config for reference
     user_sample_path = Path.home() / '.config' / 'dbtk_sample.yml'
@@ -1065,19 +1077,9 @@ def setup_config() -> None:
     print("Database Connections")
     print("-"*60)
 
-    # Load the config we just created
-    with open(config_path) as f:
-        config_data = yaml.safe_load(f)
-
     if 'connections' not in config_data:
         config_data['connections'] = {}
 
-    print(dedent("""\
-    Warning: The config file created has lots of comments that will be lost if you continue.
-    The YAML format was designed to be readable and it is recommended to just edit in the 
-    text editor of your choice. If you do continue and overwrite the comments, a fully commented
-    sample is also available at ~/.config/dbtk_sample.yml.
-    """))
     add_connection = input("\nAdd a database connection now? [y/N]: ").strip().lower()
     edits = 0
     while add_connection in ('y', 'yes'):
@@ -1170,7 +1172,6 @@ def setup_config() -> None:
         add_connection = input("\nAdd another connection? [y/N]: ").strip().lower()
 
     if edits:
-        # Write updated config file
         with open(config_path, 'w') as f:
             yaml.safe_dump(config_data, f, default_flow_style=False, sort_keys=False)
 

{dbtk-0.8.3 → dbtk-0.8.4}/dbtk/database.py

@@ -22,7 +22,7 @@ def _hide_password(kwargs):
     """Replace password with '********' to be printable"""
     parms = kwargs.copy()
     for key, val in parms.items():
-        if key in ('password', 'PWD', 'passwd'):
+        if key in ('password', 'pwd', 'PWD', 'passwd'):
             parms[key] = '********'
     return parms
 
@@ -133,16 +133,27 @@ DRIVERS = {
         'database_type': 'sqlserver',
         'module': 'pyodbc',
         'priority': 11,
-        'param_map': {'host': 'SERVER', 'database': 'DATABASE', 'user': 'UID', 'password': 'PWD'},
-        'required_params': [{'host', 'database', 'user'}, {'dsn'}],
-        'optional_params': {'password', 'port', 'driver', 'trusted_connection', 'encrypt', 'trustservercertificate'},
+        'param_map': {'host': 'server', 'user': 'uid', 'password': 'pwd'},
+        'required_params': [{'host', 'database', 'user'}, {'host', 'database', 'trusted_connection'}, {'dsn'}],
+        'optional_params': {'password', 'port', 'driver', 'encrypt', 'trustservercertificate'},
+        'connection_method': 'odbc_string',
+        'odbc_driver_name': 'ODBC Driver 18 for SQL Server',
+        'default_port': 1433
+    },
+    'pyodbc_sqlserver_17': {
+        'database_type': 'sqlserver',
+        'module': 'pyodbc',
+        'priority': 12,
+        'param_map': {'host': 'server', 'user': 'uid', 'password': 'pwd'},
+        'required_params': [{'host', 'database', 'user'}, {'host', 'database', 'trusted_connection'}, {'dsn'}],
+        'optional_params': {'password', 'port', 'driver', 'encrypt', 'trustservercertificate'},
         'connection_method': 'odbc_string',
         'odbc_driver_name': 'ODBC Driver 17 for SQL Server',
         'default_port': 1433
     },
     'pymssql': {
         'database_type': 'sqlserver',
-        'priority': 12,
+        'priority': 13,
         'param_map': {},
         'required_params': [{'host', 'database', 'user'}],
         'optional_params': {'password', 'port', 'timeout', 'login_timeout', 'charset', 'as_dict', 'appname'},
@@ -155,7 +166,7 @@ DRIVERS = {
         'database_type': 'postgres',
         'module': 'pyodbc',
         'priority': 14,
-        'param_map': {'host': 'SERVER', 'database': 'DATABASE', 'user': 'UID', 'password': 'PWD'},
+        'param_map': {'host': 'server', 'user': 'uid', 'password': 'pwd'},
         'required_params': [{'host', 'database', 'user'}, {'dsn'}],
         'optional_params': {'password', 'port'},
         'connection_method': 'odbc_string',
@@ -166,7 +177,7 @@ DRIVERS = {
         'database_type': 'mysql',
         'module': 'pyodbc',
         'priority': 16,
-        'param_map': {'host': 'SERVER', 'database': 'DATABASE', 'user': 'UID', 'password': 'PWD'},
+        'param_map': {'host': 'server', 'user': 'uid', 'password': 'pwd'},
         'required_params': [{'host', 'database', 'user'}],
         'optional_params': {'password', 'port'},
         'connection_method': 'odbc_string',
@@ -177,7 +188,7 @@ DRIVERS = {
         'database_type': 'oracle',
         'module': 'pyodbc',
         'priority': 13,
-        'param_map': {'host': 'SERVER', 'database': 'DATABASE', 'user': 'UID', 'password': 'PWD'},
+        'param_map': {'host': 'server', 'user': 'uid', 'password': 'pwd'},
         'required_params': [{'host', 'database', 'user'}],
         'optional_params': {'password', 'port'},
         'connection_method': 'odbc_string',
@@ -201,6 +212,12 @@ DRIVERS = {
 def register_user_drivers(drivers_config: dict) -> None:
     """Register drivers from config file."""
     global _user_drivers
+    for info in drivers_config.values():
+        # lowercase keys for optional_params and param_map
+        if 'optional_params' in info:
+            info['optional_params'] = {p.lower() for p in info['optional_params']}
+        if 'param_map' in info:
+            info['param_map'] = {k.lower(): v.lower()  for k,v in info['param_map'].items()}
     _user_drivers.update(drivers_config)
 
 
@@ -305,6 +322,10 @@ def _validate_connection_params(driver_name: str, config_only: bool = False, **p
     driver_info = DRIVERS[driver_name]
     database_type = driver_info['database_type']
 
+    # Normalize param keys to lowercase so callers can pass TrustServerCertificate,
+    # Port, etc. without being silently ignored.
+    params = {k.lower(): v for k, v in params.items()}
+
     # Initialize with config-only parameters if needed
     validated_params = {}
     if config_only and 'encrypted_password' in params:
@@ -348,6 +369,8 @@ def _validate_connection_params(driver_name: str, config_only: bool = False, **p
         if key in all_valid_params or (config_only and key == 'encrypted_password'):
             mapped_key = param_map.get(key, key)
             validated_params[mapped_key] = value
+        else:
+            logger.warning(f"Unknown parameter '{key}' for driver '{driver_name}' — ignoring")
 
     return validated_params
 
@@ -358,30 +381,20 @@ def _get_connection_string(**kwargs) -> str:
 
 
 def _get_odbc_string(**kwargs) -> str:
-    """Build ODBC connection string"""
-    port = kwargs.pop('port', None)
-    if port and 'SERVER' in kwargs and '\\' not in kwargs['SERVER']:
-        kwargs['SERVER'] += f',{port}'
-    printable = ';'.join([f"{key.upper()}={value}" for key, value in _hide_password(kwargs).items()])
-    logger.debug(f'ODBC connection string: {printable}')
-    return ';'.join([f"{key.upper()}={value}" for key, value in kwargs.items()])
-
-
-def _get_odbc_connection_string(**kwargs) -> str:
     """ Get connection string for ODBC from keyword arguments."""
-    # logger.debug(f'Generating ODBC connection string from: {_hide_password(kwargs)}')
     if 'dsn' in kwargs and kwargs['dsn']:
         # DSN only send DSN and password if present
         conn_str = f"DSN={kwargs['dsn']}"
         printable_conn_str = conn_str
-        if 'PWD' in kwargs:
-            conn_str += f";PWD={kwargs['PWD']}"
-            printable_conn_str += f";PWD=******"
+        if 'pwd' in kwargs:
+            conn_str += f";PWD={kwargs['pwd']}"
+            printable_conn_str += ";PWD=******"
     else:
         odbc_driver_name = kwargs.pop('odbc_driver_name', None)
         if 'port' in kwargs:
-            kwargs['SERVER'] += f',{kwargs.pop("port")}'
-        params = {key.upper(): value for key, value in kwargs.items()}
+            kwargs['server'] += f',{kwargs.pop("port")}'
+        params = {key.upper(): ('yes' if value is True else 'no' if value is False else value)
+                  for key, value in kwargs.items()}
         conn_str = ";".join([f"{key}={value}" for key, value in params.items()])
         printable_conn_str = ";".join([f"{key}={value}" for key, value in _hide_password(params).items()])
         if odbc_driver_name:
@@ -471,7 +484,7 @@ class Database:
     # Attributes stored locally, others delegated to _connection
     _local_attrs = [
         '_connection', 'database_type', 'database_name', 'driver',
-        'connection_name', 'placeholder', '_cursor_settings'
+        'connection_name', 'placeholder', '_cursor_settings', '_dialect'
     ]
 
     def __init__(self, connection, driver,
@@ -516,11 +529,11 @@ class Database:
         self.connection_name = connection_name
 
         if database_name is None:
-            database_name = (connection.get('database') or
-                            connection.get('service_name') or
-                            connection.get('dbname') or
-                            connection.get('db'))
-
+            if hasattr(connection, 'database'):
+                database_name = connection.database
+            elif hasattr(driver, 'SQL_DATABASE_NAME'):
+                # pyodbc probably from DSN
+                database_name = connection.getinfo(driver.SQL_DATABASE_NAME)
         self.database_name = database_name
 
         # Set parameter placeholder based on adapter style
@@ -533,6 +546,9 @@ class Database:
         else:
             self.database_type = 'unknown'
 
+        from .dialects import get_dialect
+        self._dialect = get_dialect(self.database_type)
+
         logger.debug(f"Cursor Database.__init__ cursor_settings: {cursor_settings}")
         if cursor_settings:
             self._cursor_settings = {key: val for key, val in cursor_settings.items()
@@ -540,6 +556,11 @@ class Database:
         else:
             self._cursor_settings = dict()
 
+    @property
+    def dialect(self):
+        """Database dialect instance providing SQL generation and schema introspection."""
+        return self._dialect
+
     def __getattr__(self, key: str) -> Any:
         """Delegate attribute access to underlying connection."""
         if key == '__name__':
@@ -765,7 +786,7 @@ class Database:
                 params['dsn'] = db_driver.makedsn(host, port, service_name=service_name)
             connection = db_driver.connect(**params)
         elif driver_conf['connection_method'] == 'odbc_string':
-            cx_string = _get_odbc_string(DRIVER=driver_conf.get('odbc_driver_name', None), **params)
+            cx_string = _get_odbc_string(odbc_driver_name=driver_conf.get('odbc_driver_name', None), **params)
             connection = db_driver.connect(cx_string)
         else:
             raise ValueError(f"Unknown connection method ({driver_conf['connection_method']}) for driver '{driver_name}'")

{dbtk-0.8.3 → dbtk-0.8.4}/dbtk/dbtk_sample.yml

@@ -21,7 +21,7 @@ settings:
 
 connections:
   # Example connection configurations
-  dev_postgres:
+  sample_postgres:
     driver: psycopg    # Optional, psycopg2 has the highest priority, this will ensure psycopg(3) is used if both are installed
     type: postgres     # type is optional IF you specify a driver
     host: localhost
@@ -35,7 +35,7 @@ connections:
     # password: prompt  # Will prompt for password
     # encrypted_password: gAAAAABh...  # Or use encrypted
 
-  prod_oracle:
+  sample_oracle:
     type: oracle
     host: oracle.company.com
     port: 1521
@@ -43,12 +43,12 @@ connections:
     user: app_user
     encrypted_password: gAAAAABh...
 
-  imdb_odbc_dsn:
+  sample_odbc_dsn:
     driver: pyodbc_postgres
     dsn: IMDB_PG  # user or system DSN
     password: '${IMDB_USER_PASS}'    # Pull from environment variable
 
-  imdb_odbc:
+  sample_odbc:
     driver: pyodbc_postgres
     host: localhost
     port: 5432
@@ -56,7 +56,7 @@ connections:
     user: imdb_user
     encrypted_password: gAAAAABh...
 
-  sqlserver_dev:
+  sample_sqlserver:
     driver: pyodbc_sqlserver
     type: sqlserver
     host: localhost\SQLEXPRESS  # Use instance name; omit port when using instance names
@@ -66,13 +66,13 @@ connections:
     cursor:
       fast_executemany: true  # Recommended for bulk operations; disable if using TEXT/NVARCHAR(MAX)/JSON columns
 
-states_db:
+  sample_sqlite:
     type: sqlite
     database: /data/test_states.db
 
 # Encrypted passwords (optional)
 passwords:
-  openai_key:
+  sample_openai_key:
     description: "OpenAI API key for data processing"
     encrypted_password: gAAAAABh...
 
@@ -80,10 +80,15 @@ passwords:
 drivers:
   firbird:
     database_type: firebird
-    module: firebird.driver # only required if name (firbird) does not mactch module (import) name
+    # only required if name (firebird) does not match module (import) name
+    module: firebird.driver
+    # lowest number with installed library will be used first
     priority: 1
-    param_map: { }  # if driver does not use standard names (user, password, host, port, database) map them here
+    # if driver does not use standard names (user, password, host, port, database) map them here
+    param_map: { }  # {'database': 'db', 'password': 'passwd'}
+    # must have either: host, database and user OR dsn
     required_params: [ { 'host', 'database', 'user' }, { 'dsn' } ]
     optional_params: { 'port', 'password' }
+    # kwargs (most common), odbc_string (all odbc), connection_string (psycopg*), dsn (oracle)
     connection_method: kwargs
     default_port: 3050

dbtk-0.8.4/dbtk/dialects/__init__.py

@@ -0,0 +1,19 @@
+# dbtk/dialects/__init__.py
+from .base import DatabaseDialect
+from .postgres import PostgresDialect
+from .oracle import OracleDialect
+from .mysql import MySQLDialect
+from .sqlserver import SQLServerDialect
+
+_DIALECT_MAP = {
+    'postgres': PostgresDialect,
+    'oracle': OracleDialect,
+    'mysql': MySQLDialect,
+    'sqlserver': SQLServerDialect,
+    'sqlite': DatabaseDialect,  # base class IS the SQLite dialect
+}
+
+
+def get_dialect(database_type: str) -> DatabaseDialect:
+    cls = _DIALECT_MAP.get(database_type, DatabaseDialect)
+    return cls()

dbtk-0.8.4/dbtk/dialects/base.py

@@ -0,0 +1,126 @@
+# dbtk/dialects/base.py
+from textwrap import dedent
+from typing import List, Tuple, Any, Optional
+
+from ..utils import wrap_at_comma
+
+
+class DatabaseDialect:
+    """
+    Base database dialect. Default implementations match PostgreSQL/SQLite behavior.
+
+    Subclass and override to support a different database. Adding support for a new
+    engine means writing one class — no grep-and-branch across the ETL layer.
+
+    For unregistered databases (custom drivers without a matching dialect subclass),
+    dbtk falls back to this base class. The following features work without a dialect:
+
+    - All reads and writes (CSV, Excel, JSON, etc.)
+    - Plain ``SELECT``, ``INSERT``, ``UPDATE``, and ``DELETE`` via ``DataSurge``
+    - ``BulkSurge`` is database-specific and will not work
+
+    Features that require a dialect subclass:
+
+    - ``Table.upsert`` / ``DataSurge.upsert`` — base class generates
+      ``INSERT … ON CONFLICT`` (PostgreSQL/SQLite syntax); will fail on other engines
+    - ``Table.merge`` / ``DataSurge.merge`` — base class generates a SQL Server-style
+      ``MERGE``; will fail on engines that don't support that syntax
+    - ``column_defs_from_db`` — raises ``NotImplementedError``
+    """
+
+    use_upsert = True           # False for MERGE-based dialects (Oracle, SQL Server)
+    temp_table_all_cols = False  # True when temp table must mirror all DB columns (Oracle)
+    temp_table_cleanup_commit = False  # True when cleanup DDL needs an explicit commit (Oracle)
+
+    # ------------------------------------------------------------------
+    # Upsert (INSERT … ON CONFLICT / ON DUPLICATE KEY)
+    # ------------------------------------------------------------------
+
+    def upsert_sql(self, table_name: str, cols_str: str, placeholders_str: str,
+                   key_cols: List[str], update_cols: List[Tuple]) -> str:
+        """INSERT … ON CONFLICT DO UPDATE SET — Postgres/SQLite default."""
+        conflict_cols = ', '.join(key_cols)
+        update_assignments = []
+        for col, ident, bind_name, db_expr in update_cols:
+            if db_expr and '#' in db_expr:
+                assignment = f"{ident} = {db_expr.replace('#', f'EXCLUDED.{ident}')}"
+            elif db_expr:
+                assignment = f"{ident} = {db_expr}"
+            else:
+                assignment = f"{ident} = EXCLUDED.{ident}"
+            update_assignments.append(assignment)
+        update_clause = ', '.join(update_assignments)
+        if len(update_assignments) > 4:
+            update_clause = wrap_at_comma(update_clause)
+        return dedent(f"""\
+        INSERT INTO {table_name} ({cols_str})
+        VALUES ({placeholders_str})
+        ON CONFLICT ({conflict_cols}) DO UPDATE SET {update_clause}""")
+
+    # ------------------------------------------------------------------
+    # Merge (MERGE … USING … ON … WHEN MATCHED / NOT MATCHED)
+    # ------------------------------------------------------------------
+
+    def _merge_source_clause(self, source_cols: str) -> str:
+        """Return the USING subquery string. Override to add a FROM clause (e.g. Oracle's FROM dual)."""
+        return f"SELECT {source_cols}"
+
+    def merge_sql(self, table_name: str, all_cols: List[Tuple],
+                  key_conditions: List[str], update_cols: List[Tuple]) -> str:
+        """Full MERGE statement. SQL Server-style by default (no FROM in USING subquery)."""
+        source_items = [f"{placeholder} AS {ident}" for _, ident, placeholder in all_cols]
+        source_cols = ', '.join(source_items)
+        if len(all_cols) > 4:
+            source_cols = wrap_at_comma(source_cols)
+
+        source_clause = self._merge_source_clause(source_cols)
+
+        update_assignments = [f"t.{ident} = s.{ident}" for _, ident in update_cols]
+        update_set = ', '.join(update_assignments)
+        if len(update_assignments) > 4:
+            update_set = wrap_at_comma(update_set)
+
+        insert_cols = ', '.join(ident for _, ident, _ in all_cols)
+        insert_values = ', '.join(f"s.{ident}" for _, ident, _ in all_cols)
+        if len(all_cols) > 4:
+            insert_cols = wrap_at_comma(insert_cols)
+            insert_values = wrap_at_comma(insert_values)
+
+        return dedent(f"""\
+        MERGE INTO {table_name} t
+        USING ({source_clause}) s
+        ON ({' AND '.join(key_conditions)})
+        WHEN MATCHED THEN
+            UPDATE SET {update_set}
+        WHEN NOT MATCHED THEN
+            INSERT ({insert_cols})
+            VALUES ({insert_values})""")
+
+    # ------------------------------------------------------------------
+    # SQL type mapping (used when generating temp table DDL)
+    # ------------------------------------------------------------------
+
+    def sql_type(self, type_obj: Any, internal_size: Optional[int],
+                 precision: Optional[int], scale: Optional[int]) -> str:
+        """Map a driver type descriptor to a SQL type string. Generic fallback."""
+        return "VARCHAR(255)"
+
+    # ------------------------------------------------------------------
+    # Schema introspection
+    # ------------------------------------------------------------------
+
+    def table_metadata(self, cursor, table_name: str, add_comments: bool) -> dict:
+        """Extract column definitions from the database catalog."""
+        raise NotImplementedError(f"{type(self).__name__} does not support table_metadata")
+
+    # ------------------------------------------------------------------
+    # Temp table hooks (MERGE-based dialects only: Oracle, SQL Server)
+    # ------------------------------------------------------------------
+
+    def create_temp_table_ddl(self, table_name: str, col_info: list) -> Tuple[str, str]:
+        """Return (temp_table_name, CREATE TABLE sql) for the given column info list."""
+        raise NotImplementedError(f"{type(self).__name__} does not use temp-table MERGE")
+
+    def cleanup_temp_table_sql(self, temp_name: str) -> str:
+        """Return SQL to clean up the temp table after a MERGE (TRUNCATE or DROP)."""
+        raise NotImplementedError(f"{type(self).__name__} does not use temp-table MERGE")