dblift 3.3.0__tar.gz → 3.3.2__tar.gz

{dblift-3.3.0 → dblift-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dblift
-Version: 3.3.0
+Version: 3.3.2
 Summary: A database migration tool that supports multiple databases with native Python drivers
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers

{dblift-3.3.0 → dblift-3.3.2}/cli/db_utils.py

@@ -5,7 +5,7 @@ import os
 import pprint
 import traceback
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 from api._cli_support import (
     ProviderRegistry,
@@ -14,6 +14,8 @@ from api._cli_support import (
 from cli._output import CommandOutput, from_args
 from config.dblift_config import load_config
 from core.logger import DbliftLogger, LogFormat
+from core.utils.url_masking import mask_database_url
+from db.error import format_connection_error
 
 
 def _to_python(obj: Any) -> Any:
@@ -317,7 +319,7 @@ def check_connection(args: argparse.Namespace) -> int:
         try:
             provider.create_connection()
         except Exception as connection_error:
-            friendly = _format_connection_error(connection_error)
+            friendly = _format_connection_error(connection_error, db_type)
             out.error(friendly)
             results["error"] = friendly
             print_connection_results(results, out)
@@ -332,7 +334,9 @@ def check_connection(args: argparse.Namespace) -> int:
 
             # Update results atomically once all operations succeed
             results["success"] = True
-            results["connection_info"]["database_url"] = database_url
+            results["connection_info"]["database_url"] = (
+                mask_database_url(database_url) if database_url else database_url
+            )
             results["connection_info"]["db_type"] = db_type
             schema = getattr(config.database, "schema", None)
             if schema:
@@ -353,76 +357,11 @@ def check_connection(args: argparse.Namespace) -> int:
         return 1
 
 
-def _format_connection_error(error: Exception) -> str:
-    """Map common database connection errors to a one-line user-facing message.
-
-    Before falling back to substring matching, consult SQLState when available:
-    the 5-character code is set by many drivers and is identical across locales.
-    The substring fallback remains for wrappers and drivers that do not populate
-    SQLState.
-
-    SQLState references:
-        08001 ``sqlclient_unable_to_establish_sqlconnection``
-        08006 ``connection_failure``
-        08S01 ``communication_link_failure`` (MS / TDS)
-        28000 / 28P01 ``invalid_authorization_specification``
-        3D000 ``invalid_catalog_name``
-        08004 ``sqlserver_rejected_establishment_of_sqlconnection``
-    """
-    message = str(error)
-    lowered = message.lower()
-    # SQL Server can report login failures with SQLState 08001, so inspect
-    # explicit auth markers before classifying broad connection SQLStates.
-    if _looks_like_auth_error(lowered):
-        return "Connection failed: invalid credentials"
-
-    sqlstate = _extract_sqlstate(error)
-    if sqlstate in ("08001", "08006", "08S01"):
-        return "Connection failed: host unreachable or connection timed out"
-    if sqlstate in ("28000", "28P01"):
-        return "Connection failed: invalid credentials"
-    if sqlstate in ("3D000", "08004"):
-        return "Connection failed: database not found or connection rejected"
-
-    if "refused" in lowered or "timed out" in lowered or "timeout" in lowered:
-        return "Connection failed: host unreachable"
-    if _looks_like_auth_error(lowered):
-        return "Connection failed: invalid credentials"
-    if "unknown host" in lowered or "name or service not known" in lowered:
-        return "Connection failed: host not found"
-    return f"Connection failed: {message}"
-
-
-def _looks_like_auth_error(lowered_message: str) -> bool:
-    """Return True when an error message clearly describes an auth failure."""
-    auth_markers = (
-        "authentication",
-        "login failed",
-        "password",
-        "error 18456",
-        "18456",
-    )
-    return any(marker in lowered_message for marker in auth_markers)
-
-
-def _extract_sqlstate(error: Exception) -> Optional[str]:
-    """Return the 5-character SQLState of ``error``, or None.
-
-    Some driver exceptions expose ``getSQLState()``. ``sqlstate`` is also
-    sometimes attached as a plain attribute — check both.
-    """
-    get_ss = getattr(error, "getSQLState", None)
-    if callable(get_ss):
-        try:
-            value = get_ss()
-        except Exception:
-            value = None
-        if value:
-            return str(value).strip() or None
-    attr = getattr(error, "sqlstate", None) or getattr(error, "SQLState", None)
-    if attr:
-        return str(attr).strip() or None
-    return None
+# Re-exported so ``db check-connection`` and every other command's own
+# connection-establishment step (``BaseCommand._ensure_connected``) format
+# connection failures identically. See ``db.error.format_connection_error``
+# for the SQLState references and auth-classification rationale.
+_format_connection_error = format_connection_error
 
 
 def print_connection_results(results: Dict[str, Any], out: CommandOutput) -> None:

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/base_command.py

@@ -546,11 +546,25 @@ class BaseCommand:
         Providers may expose ``_ensure_connection`` (connect-if-closed).
         Other providers and stubs fall back to ``connect()`` only
         when ``is_connected()`` reports False, to avoid duplicate connections.
+
+        A failed connection attempt is re-raised through
+        ``db.error.format_connection_error`` — the same formatter
+        ``db check-connection`` uses — so every command reports connection
+        failures with the identical friendly one-liner instead of a raw
+        driver/SQLAlchemy exception.
         """
-        if ensure_provider_connection(self.provider):
-            return
-        if not self.provider.is_connected():
-            self.provider.connect()
+        try:
+            if ensure_provider_connection(self.provider):
+                return
+            if not self.provider.is_connected():
+                self.provider.connect()
+        except Exception as exc:
+            from db.error import format_connection_error
+
+            db_type = getattr(self.provider, "canonical_dialect_key", "") or getattr(
+                getattr(self.config, "database", None), "type", ""
+            )
+            raise ConnectionError(format_connection_error(exc, str(db_type or ""))) from exc
 
     def _run_preflight(
         self,

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/baseline_command.py

@@ -27,6 +27,19 @@ class BaselineCommand(BaseCommand):
 
         try:
             if dry_run:
+                # Don't create the schema/history table as a side effect of dry-run.
+                # If it already exists, run the same "history already has rows"
+                # precondition the real run would hit, so dry-run can't report
+                # false success for a baseline that would actually fail.
+                self._ensure_connected()
+                if self.history_manager.has_history_table:
+                    existing = self.history_manager.get_applied_migration_records()
+                    if existing:
+                        raise RuntimeError(
+                            f"Schema {result.target_schema} already contains a migration "
+                            f"history table with {len(existing)} migration(s). Baseline "
+                            "cannot be applied to a schema with existing migrations."
+                        )
                 result.baseline_version = baseline_version
                 result.message = f"Dry run: baseline {baseline_version} would be created"
                 self._log_command_header_update(
@@ -35,7 +48,8 @@ class BaselineCommand(BaseCommand):
                 self._log_command_completion("baseline", result)
                 return result
 
-            # Ensure schema and history table exist before baselining (this establishes the connection)
+            # Ensure schema and history table exist before baselining (this establishes the
+            # connection).
             self.history_manager.create_schema_and_history_table(create_schema=True)
 
             # Log command execution with connection info (after connection is established)

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/import_flyway_command.py

@@ -5,6 +5,7 @@ from typing import Any, Dict, List
 
 from core.logger.results import OperationResult
 from core.migration.commands.base_command import BaseCommand
+from db.object_naming import get_normalized_object_name
 from db.provider_registry import ProviderRegistry
 
 
@@ -30,7 +31,17 @@ class ImportFlywayCommand(BaseCommand):
         """
         result = OperationResult()
         result.target_schema = self.config.database.schema
-        source_table = (flyway_table or "flyway_schema_history").strip()
+        default_source_table = "flyway_schema_history"
+        source_table = (flyway_table or default_source_table).strip()
+        db_type = str(getattr(self.config.database, "type", "") or "").lower()
+        if (
+            source_table == default_source_table
+            and ProviderRegistry.get_quirks(db_type).flyway_source_table_case_sensitive
+        ):
+            # No explicit --flyway-table override: normalize the default name to
+            # the dialect's unquoted-identifier case so it matches a real Flyway
+            # installation's table (e.g. Oracle/DB2 fold unquoted DDL to uppercase).
+            source_table = get_normalized_object_name(source_table, db_type)
         configured_target = getattr(self.config, "history_table", None)
         target_table = (
             configured_target.strip()
@@ -38,12 +49,20 @@ class ImportFlywayCommand(BaseCommand):
             else "dblift_schema_history"
         )
 
+        # Ensure the provider has a live connection before reading connection
+        # metadata or querying the Flyway table — dry-run skips
+        # create_schema_and_history_table below, which would otherwise be the
+        # only thing establishing the connection for providers that need it.
+        self._ensure_connected()
+
         # Populate database connection information
         self._populate_database_info(result)
 
         try:
-            # Ensure schema and history table exist (this establishes the connection)
-            self.history_manager.create_schema_and_history_table(create_schema=False)
+            # Ensure schema and history table exist. Skipped in dry-run so no
+            # table is created as a side effect.
+            if not dry_run:
+                self.history_manager.create_schema_and_history_table(create_schema=False)
 
             # Log command execution with connection info (after connection is established)
             self._log_command_header_update("import-flyway", dry_run=dry_run)

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/info_command.py

@@ -41,6 +41,13 @@ def _migration_type_name(migration_type: object) -> str:
     return str(migration_type or "").upper()
 
 
+def _normalize_filter(value: Optional[str]) -> Optional[List[str]]:
+    """Split a comma-separated CLI filter value into a clean list."""
+    if value is None:
+        return None
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
 class InfoCommand(BaseCommand):
     """Handles the 'info' command execution."""
 
@@ -50,12 +57,21 @@ class InfoCommand(BaseCommand):
         recursive: bool = True,
         additional_dirs: Optional[List[Path]] = None,
         dir_recursive_map: Optional[Dict[Path, bool]] = None,
+        tags: Optional[str] = None,
+        exclude_tags: Optional[str] = None,
+        versions: Optional[str] = None,
+        exclude_versions: Optional[str] = None,
         display_human: bool = True,
     ) -> InfoResult:
         """Get information about migrations using migration rules for state determination."""
         result = InfoResult()
         result.target_schema = self.config.database.schema
 
+        normalized_tags = _normalize_filter(tags)
+        normalized_exclude_tags = _normalize_filter(exclude_tags)
+        normalized_versions = _normalize_filter(versions)
+        normalized_exclude_versions = _normalize_filter(exclude_versions)
+
         def _body() -> None:
             # Use MigrationStateManager to get centralized migration state
             try:
@@ -122,10 +138,10 @@ class InfoCommand(BaseCommand):
                     all_applied_migrations=all_applied_migrations,
                     scripts_dir=scripts_dir,
                     target_version=None,
-                    tags=None,
-                    exclude_tags=None,
-                    versions=None,
-                    exclude_versions=None,
+                    tags=normalized_tags,
+                    exclude_tags=normalized_exclude_tags,
+                    versions=normalized_versions,
+                    exclude_versions=normalized_exclude_versions,
                 )
 
             # Use the same data processing pipeline as the console output
@@ -135,10 +151,10 @@ class InfoCommand(BaseCommand):
                 all_applied_migrations=all_applied_migrations,
                 scripts_dir=scripts_dir,
                 target_version=None,
-                tags=None,
-                exclude_tags=None,
-                versions=None,
-                exclude_versions=None,
+                tags=normalized_tags,
+                exclude_tags=normalized_exclude_tags,
+                versions=normalized_versions,
+                exclude_versions=normalized_exclude_versions,
             )
 
             # Convert the UI data to MigrationInfo objects for the HTML formatter

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/migrate_command.py

@@ -580,9 +580,14 @@ class MigrateCommand(BaseCommand):
         dir_recursive_map: Optional[Dict[Path, bool]],
     ) -> None:
         """Update final schema version after migrations are applied."""
-        # Rebuild state to get accurate applied migrations after migration
+        # Rebuild state to get accurate applied migrations after migration.
+        # scripts_dir=None so build_state skips pending-migration computation
+        # (only applied_objects is needed here) — this run's tag/version
+        # exclusion filters aren't available at this point, so recomputing
+        # pending here would misreport excluded, never-applied scripts as
+        # out-of-order.
         migration_state_after = self.state_manager.build_state(
-            scripts_dir,
+            None,
             recursive=use_recursive,
             additional_dirs=use_additional_dirs,
             dir_recursive_map=dir_recursive_map,

{dblift-3.3.0 → dblift-3.3.2}/core/migration/commands/validate_command.py

@@ -36,22 +36,35 @@ class ValidateCommand(BaseCommand):
         self._populate_database_info(result)
 
         try:
-            # Validate command may not need connection, but try to establish it for header info
+            # Ensure the schema history table exists before validating. A
+            # failure here (e.g. missing DB privileges) is a real command
+            # failure, not something to swallow: validating scripts against
+            # a history table that couldn't be created would report success
+            # while the schema was left in an unusable state.
             try:
                 self.history_manager.create_schema_and_history_table(create_schema=False)
-                # Log command execution with connection info (after connection is established)
-                self._log_command_header_update(
-                    "validate",
-                    target_version=target_version,
-                    tags=tags,
-                    exclude_tags=exclude_tags,
-                    versions=versions,
-                    exclude_versions=exclude_versions,
-                )
             except Exception as e:
-                # If connection fails, still log without connection info
-                self.log.debug(f"Could not establish connection for validate header: {e}")
-                self.log.info("Command: validate")
+                from core.migration.sql.sql_execution_service import _format_execution_error
+
+                try:
+                    formatted = _format_execution_error(e)
+                except Exception:
+                    formatted = ""
+                error_msg = f"Could not create schema history table: {formatted or str(e)}"
+                self.log.error(error_msg)
+                result.set_error(error_msg)
+                self._log_command_completion("validate", result)
+                return result
+
+            # Log command execution with connection info (after connection is established)
+            self._log_command_header_update(
+                "validate",
+                target_version=target_version,
+                tags=tags,
+                exclude_tags=exclude_tags,
+                versions=versions,
+                exclude_versions=exclude_versions,
+            )
 
             validation_result = self.validator.validate_migrations(
                 scripts_dir,

{dblift-3.3.0 → dblift-3.3.2}/core/migration/executor/execution_engine.py

@@ -38,18 +38,33 @@ from db.provider_registry import ProviderRegistry
 from db.value_utils import to_python_string
 
 _DRIVER_EXCEPTION_PREFIX_RE = re.compile(
-    r"^(?:[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+Exception:\s*)+" r"(?:ERROR:\s*)?",
+    r"^(?:"
+    r"[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+Exception:\s*"  # Java/JDBC: dotted.path.Exception:
+    r"|"
+    r"\([a-z_][a-z0-9_]*(?:\.[a-z0-9_]+)+\)\s*"  # SQLAlchemy: (dotted.path.ExceptionClass)
+    r")+"
+    r"(?:ERROR:\s*)?",
     re.IGNORECASE,
 )
+# SQLAlchemy appends a doc-link pointer for every wrapped DBAPI error, e.g.
+# '(Background on this error at: https://sqlalche.me/e/20/e3q8)'.
+_SQLALCHEMY_DOC_LINK_RE = re.compile(
+    r"\s*\(Background on this error at:.*\)\s*\Z", re.IGNORECASE | re.DOTALL
+)
 
 
 def _strip_driver_exception_prefix(msg: str) -> str:
-    """Strip verbose driver exception class prefixes from error strings.
+    """Strip verbose driver/SQLAlchemy exception wrapping from error strings.
 
     e.g. 'org.postgresql.util.PSQLException: ERROR: column "x" already exists'
          → 'column "x" already exists'
+    e.g. '(_duckdb.IOException) IO Error: Cannot open file "x": No such file or directory
+         (Background on this error at: https://sqlalche.me/e/20/e3q8)'
+         → 'IO Error: Cannot open file "x": No such file or directory'
     """
-    return _DRIVER_EXCEPTION_PREFIX_RE.sub("", str(msg)).strip()
+    text = _DRIVER_EXCEPTION_PREFIX_RE.sub("", str(msg)).strip()
+    text = _SQLALCHEMY_DOC_LINK_RE.sub("", text).strip()
+    return text
 
 
 def _is_ddl_statement_for_success_log(statement: str) -> bool:

{dblift-3.3.0 → dblift-3.3.2}/core/migration/executor/migration_executor.py

@@ -360,6 +360,10 @@ class MigrationExecutor:
             recursive=recursive,
             additional_dirs=additional_dirs,
             dir_recursive_map=dir_recursive_map,
+            tags=tags,
+            exclude_tags=exclude_tags,
+            versions=versions,
+            exclude_versions=exclude_versions,
             display_human=display_human,
         )
 

{dblift-3.3.0 → dblift-3.3.2}/core/migration/executors/python_executor.py

@@ -71,9 +71,11 @@ class MigrationContext:
             context.execute("INSERT INTO t VALUES (1)")
             context.log.info("Row inserted")
 
-    To support undo, add an ``undo`` function with the same signature::
+    A ``U<version>__*.py`` undo script also defines a top-level ``migrate``
+    function — the same entry point as any other migration — describing the
+    action to perform when undoing::
 
-        def undo(context: MigrationContext) -> None:
+        def migrate(context: MigrationContext) -> None:
             context.execute("DELETE FROM t WHERE id = 1")
 
     Public interface:

{dblift-3.3.0 → dblift-3.3.2}/core/seams/sql_generators.py

@@ -22,8 +22,13 @@ def attach_registered_sql_generators() -> None:
     """Run every registered SQL generator registrar."""
     global _bootstrapped
     if not _bootstrapped and not _registrars:
-        _bootstrapped = True
         load_feature_extensions()
+        # Latch only if load_feature_extensions() actually populated
+        # _registrars -- same latch bug as AlterGeneratorFactory._ensure_populated
+        # and feature_loading.load_feature_extensions: an empty result can be
+        # the documented race (a paid package's entry point not yet visible),
+        # so it must not be latched permanently and must retry on a later call.
+        _bootstrapped = bool(_registrars)
 
     for registrar in _registrars:
         try:

{dblift-3.3.0 → dblift-3.3.2}/core/sql_validator/_checksum_validator.py

@@ -68,15 +68,24 @@ def validate_checksums(
     result: "ValidationResult",
     issues: List[str],
     strict_mode: bool = False,
+    all_scripts: Optional[List[Migration]] = None,
 ) -> None:
     """Validate checksums of executed migrations.
 
     Compares each applied migration's stored checksum against the current
     file's checksum, flagging drift either as an error (versioned scripts)
     or a recorded reapply (repeatable scripts).
+
+    ``scripts`` may be scoped by ``--tags``/``--versions`` filters; ``all_scripts``,
+    when provided, is the full unfiltered set of on-disk scripts and is used only to
+    decide whether an applied migration is genuinely missing from the migration
+    directory (as opposed to merely filtered out of the current run's scope).
     """
     checksum_mismatches = []
     script_names = [s.script_name for s in scripts]
+    full_script_names = (
+        [s.script_name for s in all_scripts] if all_scripts is not None else script_names
+    )
 
     for applied in applied_migrations:
         script_name = getattr(applied, "script_name", None)
@@ -98,7 +107,7 @@ def validate_checksums(
         if migration_type == MigrationType.BASELINE:
             continue
 
-        if script_name not in script_names:
+        if script_name not in full_script_names:
             if migration_type != MigrationType.BASELINE and str(version_val).lower() != "baseline":
                 # Check if this script has been marked as deleted
                 is_deleted = any(
@@ -144,6 +153,12 @@ def validate_checksums(
                         "marked as deleted - OK"
                     )
             continue
+        if script_name not in script_names:
+            # Present on disk but filtered out of scope by --tags/--versions - not missing.
+            mv.log.debug(
+                f"Migration '{script_name}' is out of scope for this run's filters - skipping"
+            )
+            continue
         if migration_type == MigrationType.BASELINE:
             mv.log.debug(f"Skipping checksum verification for {script_name} (baseline)")
             continue

{dblift-3.3.0 → dblift-3.3.2}/core/sql_validator/migration_validator.py

@@ -425,6 +425,11 @@ class MigrationValidator:
             # Handle baseline filtering
             valid_scripts = self._handle_baseline_filtering(valid_scripts)
 
+            # Full set of on-disk scripts before tag/version scoping, used to tell a
+            # genuinely missing migration apart from one merely out of the current
+            # --tags/--versions filter scope.
+            all_valid_scripts = valid_scripts
+
             valid_scripts = self._apply_filters(
                 valid_scripts,
                 target_version=target_version,
@@ -485,6 +490,7 @@ class MigrationValidator:
                         validation_result,
                         issues,
                         strict_mode,
+                        all_valid_scripts,
                     )
                     if issues:
                         validation_result.success = False
@@ -593,6 +599,7 @@ class MigrationValidator:
                     validation_result,
                     issues,
                     strict_mode,
+                    all_valid_scripts,
                 )
                 self.log.debug(
                     f"[DEBUG] validate_migrations: after _validate_checksums: success={validation_result.success}, error='{validation_result.error_message}', issues={issues}"
@@ -744,6 +751,7 @@ class MigrationValidator:
         result: ValidationResult,
         issues: List[str],
         strict_mode: bool = False,
+        all_scripts: Optional[List[Migration]] = None,
     ) -> None:
         """Delegate to :func:`core.sql_validator._checksum_validator.validate_checksums`.
 
@@ -752,7 +760,7 @@ class MigrationValidator:
         """
         from core.sql_validator._checksum_validator import validate_checksums as _impl
 
-        _impl(self, scripts, applied_migrations, result, issues, strict_mode)
+        _impl(self, scripts, applied_migrations, result, issues, strict_mode, all_scripts)
 
     def _check_repeatable_migrations(
         self,

{dblift-3.3.0 → dblift-3.3.2}/db/error.py

@@ -143,6 +143,99 @@ class DatabaseErrorClassifier:
         return category in _RETRYABLE_CATEGORIES and retry_count < max_retries
 
 
+def format_connection_error(error: Exception, db_type: str = "") -> str:
+    """Map common database connection errors to a one-line user-facing message.
+
+    Shared by ``db check-connection`` and every other command's own
+    connection-establishment step (see ``BaseCommand._ensure_connected``), so a
+    connection failure is reported identically no matter which command
+    triggered it.
+
+    Before falling back to substring matching, consult SQLState when available:
+    the 5-character code is set by many drivers and is identical across locales.
+    Auth-error detection also consults ``DatabaseErrorClassifier`` (dialect
+    quirks ``error_patterns()`` + the generic patterns above), so vendor codes
+    such as Oracle's ORA-01017 are recognized without hardcoding vendor-specific
+    substrings here. The substring fallback remains for wrappers and drivers
+    that do not populate SQLState or match a quirks pattern.
+
+    SQLState references:
+        08001 ``sqlclient_unable_to_establish_sqlconnection``
+        08006 ``connection_failure``
+        08S01 ``communication_link_failure`` (MS / TDS)
+        28000 / 28P01 ``invalid_authorization_specification``
+        3D000 ``invalid_catalog_name``
+        08004 ``sqlserver_rejected_establishment_of_sqlconnection``
+    """
+    from core.migration.executor.execution_engine import _strip_driver_exception_prefix
+
+    message = _strip_driver_exception_prefix(str(error))
+    lowered = message.lower()
+    # SQL Server can report login failures with SQLState 08001, so inspect
+    # explicit auth markers before classifying broad connection SQLStates.
+    if _is_auth_error(error, lowered, db_type):
+        return "Connection failed: invalid credentials"
+
+    sqlstate = _extract_sqlstate(error)
+    if sqlstate in ("08001", "08006", "08S01"):
+        return "Connection failed: host unreachable or connection timed out"
+    if sqlstate in ("28000", "28P01"):
+        return "Connection failed: invalid credentials"
+    if sqlstate in ("3D000", "08004"):
+        return "Connection failed: database not found or connection rejected"
+
+    if "refused" in lowered or "timed out" in lowered or "timeout" in lowered:
+        return "Connection failed: host unreachable"
+    if "unknown host" in lowered or "name or service not known" in lowered:
+        return "Connection failed: host not found"
+    return f"Connection failed: {message}"
+
+
+def _is_auth_error(error: Exception, lowered_message: str, db_type: str) -> bool:
+    """Return True when *error* clearly describes an auth failure.
+
+    Checks cheap substring markers first, then falls back to the dialect's
+    quirks-based ``DatabaseErrorClassifier`` so vendor error codes (e.g.
+    Oracle's ORA-01017) are recognized generically across every dialect that
+    declares ``error_patterns()``, not just the ones with a hardcoded marker
+    below.
+    """
+    auth_markers = (
+        "authentication",
+        "login failed",
+        "password",
+        "error 18456",
+        "18456",
+    )
+    if any(marker in lowered_message for marker in auth_markers):
+        return True
+    try:
+        category = DatabaseErrorClassifier(db_type).categorize_error(error)
+    except Exception:
+        return False
+    return category in (ErrorCategory.AUTHENTICATION, ErrorCategory.AUTHORIZATION)
+
+
+def _extract_sqlstate(error: Exception) -> Optional[str]:
+    """Return the 5-character SQLState of *error*, or None.
+
+    Some driver exceptions expose ``getSQLState()``. ``sqlstate`` is also
+    sometimes attached as a plain attribute — check both.
+    """
+    get_ss = getattr(error, "getSQLState", None)
+    if callable(get_ss):
+        try:
+            value = get_ss()
+        except Exception:
+            value = None
+        if value:
+            return str(value).strip() or None
+    attr = getattr(error, "sqlstate", None) or getattr(error, "SQLState", None)
+    if attr:
+        return str(attr).strip() or None
+    return None
+
+
 class RetryManager:
     """Executes operations with exponential-backoff retry on transient errors."""