SQLAlchemy ↔ PostgreSQL SSL Mode: What Exception Is Raised When Verification Fails?

Direct Answer

When sslmode='verify-full' fails because the server certificate cannot be verified, SQLAlchemy raises sqlalchemy.exc.OperationalError (a subclass of DBAPIError). The original psycopg2.OperationalError is preserved in the .orig attribute of that exception.

Confirmed Behavior

• Exception type: sqlalchemy.exc.OperationalError
• Wrapped driver exception: psycopg2.OperationalError (accessible via e.orig)
• Message content: Includes the driver's original text, e.g. (psycopg2.OperationalError) SSL error: certificate verify failed followed by the OpenSSL reason code.
• pgcode: e.orig.pgcode == '08006' (connection_failure)

Why This Happens

SQLAlchemy does not perform TLS validation itself. It passes sslmode and related parameters directly to psycopg2.connect(). When the handshake fails, psycopg2 raises its own OperationalError; SQLAlchemy catches it and re-raises a wrapped sqlalchemy.exc.OperationalError so that application code can use the driver-agnostic hierarchy (DBAPIError → OperationalError).

Cross-Driver Handling Strategy

SQLAlchemy's documented approach is to catch sqlalchemy.exc.DBAPIError (or its subclasses) and inspect .orig for driver-specific details. There is no built-in utility that maps SSL errors across drivers into a single custom exception. A typical helper looks like:

from sqlalchemy.exc import DBAPIError

def is_ssl_verification_failure(exc: DBAPIError) -> bool:
    orig = exc.orig
    # psycopg2
    if hasattr(orig, 'pgcode') and orig.pgcode == '08006':
        return 'certificate verify failed' in str(orig).lower()
    # asyncpg, pg8000, etc. — add driver-specific checks here
    return False

Verification Steps (If You Need to Confirm in Your Environment)

1. Create a PostgreSQL server with a self-signed certificate not in your client CA bundle.
2. Configure the engine: create_engine('postgresql+psycopg2://...', connect_args={'sslmode': 'verify-full', 'sslrootcert': '/path/to/wrong-ca.pem'})
3. Call engine.connect() inside a try/except sqlalchemy.exc.OperationalError as e: block.
4. Print type(e.orig) and e.orig to confirm the wrapped exception and message.

One Diagnostic Detail That Changes the Recommendation

Are you using the synchronous psycopg2 driver, or an async driver such as asyncpg? With asyncpg, sslmode is not a native parameter; SSL is configured via an SSLContext passed in connect_args, and the wrapped exception will be sqlalchemy.exc.OperationalError with .orig as an asyncpg exception type (e.g., CannotConnectNowError). The wrapping pattern is the same, but the driver-specific checks differ.