CRE-2025-0030

SQLAlchemy create_engine fails when password contains special characters like @Medium

Impact: 6/10

Mitigation: 2/10

CRE-2025-0030View on GitHub

SqlalchemyConfigurationPasswordUriEscapingConnectionKnown IssuePublic

Description

SQLAlchemy applications using `create_engine()` may fail to connect to a database if the username or password contains special characters (e.g., `@`, `:`, `/`, `#`). These characters must be URL-encoded when included in the database connection string. Failure to encode them leads to parsing errors or incorrect credential usage.

Cause

Special characters in database credentials (such as `@`) conflict with reserved URL characters used to delimit user info, host, and port. If unencoded, SQLAlchemy misinterprets the connection string, leading to failed authentication or malformed URIs.

Mitigation

• URL-encode special characters in usernames and passwords when constructing the connection string.
• For example, replace `@` with `%40`, `:` with `%3A`, `/` with `%2F`, etc.
• Alternatively, use the dictionary-style `create_engine(URL.create(...))` approach to avoid manual string encoding.
• See official docs: https://docs.sqlalchemy.org/en/20/core/engines.html#escaping-special-characters-such-as-signs-in-passwords

References

• https://github.com/sqlalchemy/sqlalchemy/issues?q=label%3A%22%40+%28or+other+chars%29+in+password%22+
• https://docs.sqlalchemy.org/en/20/core/engines.html#escaping-special-characters-such-as-signs-in-passwords