Repository navigation
connect does not honor timeout parameter #725
Copy link
Copy link
Closed
Labels
FIXEDarea: api-compliancePython API behavior and typing: DB-API 2.0, exceptions, type stubs, new APIs.Python API behavior and typing: DB-API 2.0, exceptions, type stubs, new APIs.bugSomething isn't workingSomething isn't workinginADOtriage doneIssues that are triaged by dev team and are in investigation.Issues that are triaged by dev team and are in investigation.
Description
Describe the bug
The docstring on db_connection.connect says: timeout (int): The timeout for the connection attempt, in seconds.. However, it gets mixed up down the line with the query timeout.
sqlstate = 'HYT00'
ddbc_error = '[Microsoft][ODBC Driver 18 for SQL Server]Query timeout expired'
def raise_exception(sqlstate: str, ddbc_error: str) -> None:
"""
Raise a custom exception based on the given SQLSTATE code.
This function raises a custom exception based on the provided SQLSTATE code.
If the code is not found in the mapping, a generic DatabaseError is raised.
Args:
sqlstate (str): The SQLSTATE code to map to a custom exception.
ddbc_error (str): The DDBC error message.
Raises:
DatabaseError: If the SQLSTATE code is not found in the mapping.
"""
exception_class = sqlstate_to_exception(sqlstate, ddbc_error)
if exception_class:
logger.error(f"Raising exception: {exception_class}")
> raise exception_class
E mssql_python.exceptions.OperationalError: Driver Error: Timeout expired; DDBC Error: [Microsoft]Query timeout expired
To reproduce
I used the following test case to reproduce the issue
async def test_connection_timeout_repurposes_to_query_timeout(connection_string):
conn = mssql_python.connect(connection_string, timeout=3)
cursor = conn.cursor()
cursor.execute("WAITFOR DELAY '00:00:10'; SELECT 1") # times out after ~3s
val = cursor.fetchval()
assert 1 == valExpected behavior
connect(timeout=3) should make the connection attempt time out after 3s.
Further technical details
Python version: 3.13
SQL Server version: Azure SQL Server
Operating system: Windows 11
Additional context
Discovered by Claude as I was migrating from pyodbc/aiodbc to mssql-python, I did A/B tests and can confirm that I believe it's an "unintended" bug in the library, hopefully I did by due diligence correctly!
Some more context from Claude
In connection.py, timeout is documented twice as a login timeout — "Login timeout in seconds. 0 means no timeout." (line 295) and "The timeout for the connection attempt, in seconds" in connect(). Its complete set of uses:
631: self._timeout = timeout # stored
928: return self._timeout # property documented as "the current query timeout"
950: self._timeout = value # setter: "Set the query timeout for all operations"
1464: cursor = Cursor(self, timeout=self._timeout)
It is never passed to SQL_ATTR_LOGIN_TIMEOUT. It silently becomes the query timeout. The same file's own example (line 354) shows attrs_before={ms.SQL_ATTR_LOGIN_TIMEOUT: 30} as the way to set a login timeout — so the mechanism is known, the parameter is just mis-wired.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
FIXEDarea: api-compliancePython API behavior and typing: DB-API 2.0, exceptions, type stubs, new APIs.Python API behavior and typing: DB-API 2.0, exceptions, type stubs, new APIs.bugSomething isn't workingSomething isn't workinginADOtriage doneIssues that are triaged by dev team and are in investigation.Issues that are triaged by dev team and are in investigation.
Activity
github-actions commentedon Aug 20, 2026
Hi Alexandre Arpin (@AlexandreArpin), thank you for opening this issue!
Our team will review it shortly. We aim to triage all new issues within 24-48 hours and get back to you.
If you have additional information to share, please feel free to update the issue.
Thank you for your patience!
jahnvi480 commentedon Aug 24, 2026
Alexandre Arpin (@AlexandreArpin) Thanks for reporting this issue. I'll have a look at it and if it is a real bug will try to help you out soon.
FIX: route connect(timeout=) to SQL_ATTR_LOGIN_TIMEOUT (GH-725)
FIX: address PR #728 review for GH-725 login-timeout fix
FIX: harden GH-725 login-timeout test and clarify timeout UX (AB#47540)
FIX: suppress DevSkim DS162092 false positive in login-timeout test (…
FIX: tighten and de-duplicate GH-725 timeout tests per review (AB#47540)
FIX: connect(timeout=) sets login timeout, not query timeout (GH-725) (…
jahnvi480 commentedon Aug 27, 2026
Alexandre Arpin (@AlexandreArpin) The fix has been pushed to main branch and it will be available in our today's release.
Claosing the issue. Thank you for helping us make our driver better!