Repository navigation
2.0.3: Cursor, Statement, and Connection finalizers raise unraisable DatabaseError after connection loss #75
Description
Description
When a Firebird connection is interrupted or times out while a cursor is streaming records, firebird-driver 2.0.3 correctly raises a DatabaseError for the original connection failure.
My application catches that exception and explicitly attempts to close the cursor, roll back the transaction, close the transaction manager, and close the connection.
However, if one or more of these cleanup operations fail because the connection is already unavailable, the affected driver objects remain in a partially open state. When they are subsequently garbage-collected, their __del__() methods attempt the same cleanup again and raise additional DatabaseError exceptions.
Because these exceptions occur inside object finalizers, they cannot be caught by my application's normal try/except blocks. Python reports them through sys.unraisablehook as:
Exception ignored in: <function Cursor.__del__ ...>
Exception ignored in: <function Statement.__del__ ...>
Exception ignored in: <function Connection.__del__ ...>
This still occurs with firebird-driver 2.0.3.
Environment
- Operating system: Windows 11
- Python: 3.12.10
- firebird-driver: 2.0.3
- Firebird server: 3.0.x
- Multiprocessing start method:
spawn - Connection failure type: connection timeout or interrupted network connection
- Observed SQLSTATE:
08006 - Observed SQLCODE:
-902 - Observed GDS codes:
335544726, error reading data from the connection335544727, error writing data to the connection
Observed behavior
The original connection failure is caught normally:
Firebird database error while streaming table 'xxxxx':
Error reading data from the connection.;
SQLSTATE='08006';
SQLCODE=-902;
GDS=(335544726,)
Explicit cursor cleanup then also fails and is caught by the application:
Failed to close the Firebird streaming cursor:
Error writing data to the connection.;
SQLSTATE='08006';
SQLCODE=-902;
GDS=(335544727,)
After the application has caught both errors, garbage collection produces additional tracebacks:
Exception ignored in: <function Cursor.__del__ at 0x...>
Traceback (most recent call last):
File "...firebird\driver\core.py", line 3363, in __del__
self.close()
File "...firebird\driver\core.py", line 4111, in close
self._stmt.free()
File "...firebird\driver\core.py", line 3043, in free
self._istmt.free()
File "...firebird\driver\interfaces.py", line 830, in free
self._check()
File "...firebird\driver\interfaces.py", line 141, in _check
raise self.__report(DatabaseError, self.status.get_errors())
firebird.driver.types.DatabaseError:
Error writing data to the connection.
The same behavior occurs for the connection:
Exception ignored in: <function Connection.__del__ at 0x...>
Traceback (most recent call last):
File "...firebird\driver\core.py", line 1800, in __del__
self._close()
File "...firebird\driver\core.py", line 1832, in _close
self.main_transaction._finish(DefaultAction.ROLLBACK)
File "...firebird\driver\core.py", line 2632, in _finish
self.rollback()
File "...firebird\driver\core.py", line 2716, in rollback
self._tra.rollback()
File "...firebird\driver\interfaces.py", line 466, in rollback
self._check()
File "...firebird\driver\interfaces.py", line 141, in _check
raise self.__report(DatabaseError, self.status.get_errors())
firebird.driver.types.DatabaseError:
connection shutdown
A statement finalizer produces another traceback:
Exception ignored in: <function Statement.__del__ at 0x...>
Traceback (most recent call last):
File "...firebird\driver\core.py", line 3024, in __del__
self.free()
File "...firebird\driver\core.py", line 3043, in free
self._istmt.free()
File "...firebird\driver\interfaces.py", line 830, in free
self._check()
File "...firebird\driver\interfaces.py", line 141, in _check
raise self.__report(DatabaseError, self.status.get_errors())
firebird.driver.types.DatabaseError:
connection shutdown
Depending on which driver objects remain alive, the same issue may also affect TransactionManager.__del__().
Activity
pcisar commentedon Oct 7, 2026
__del__finalizers are very tricky beasts. I did my best to prevent such situations, but it's a "whack-a-mole" all around as systems keep inventing new ways how to break. When designing the new driver, I faced a major dilemma regarding whether to implement them, as I knew it was technically impossible to guarantee that Firebird API calls would not fail catastrophically in the event of a severe system disruption.The Firebird API requires everything to be properly terminated during normal operation in order to release server resources. However, it does not strictly enforce this if the system simply "quietly disappears"; the server will eventually detect this and release the resources itself.
Consequently, failing to close the connection during an application crash or a normal shutdown is essentially harmless for Firebird; thus, a finalizer is not strictly necessary.
However, failing to properly release resources during routine operation is a serious issue, as it can overwhelm the server. For this reason, the driver provides a context manager for every object that holds server-side resources. I considered having the finalizer simply emit a warning instead of releasing the resources—since such a failure essentially represents a programming error—but I was advised that there are special cases where a context manager cannot be used and proper resource release might be overlooked for other reasons. So, I ultimately implemented finalizers. I regret that decision to this day.
I will certainly fix any error related to finalizers that originates primarily on the Python side. However, I certainly cannot handle every scenario where the connection to the Firebird API or server breaks down in a way that is simply impossible to predict or manage at the driver level. I realize that the consequences in such cases range from unpleasant to fatal. Frankly, I do not know how to handle such situations within the driver other than by having the user disable the finalizers of the affected objects.
So, I could add
boolpropertyfinalizewithTruedefault to affected classes that would trun__del__to NOOP whenFalse. Setting it could even propagate to all managed objects (i.e. Connection -> Transactions -> Statements.Would that be an acceptable solution to your problem?
HNJAMeindersma commentedon Oct 28, 2026
For me it's not about the server side or releasing open connection/resources on the server. I'm sure that these will be released after a certain timeout. It's about the python client side. When, for example, a connection loss happends, I expect the driver to report on this through raising an exception and then clean itself up somewhat "nicely" (on the client side only).
If I compare connection loss behaviour to the PostgreSQL python client (
psycopg) then that seems to go allot more cleanly.Since I'm a user of your module and do not know the inner workings of it, it is hard to tell how an acceptable solution would be designed. I can only tell what would be expected or desireable behaviour.
My assumption would be that any
__del__or garbage collection will not also trigger its own exceptions when another has already been raised by a, for example, connection loss. It should still clean itself up, but without trying to do so with a connection towards the server.Fix for #75
pcisar commentedon Oct 29, 2026
Could you please check the fix?
HNJAMeindersma commentedon Oct 30, 2026
firebird-base: 2.0.4
firebird-driver: 2.0.3
firebird-base: 2.0.4
firebird-driver: 2.1.0
firebird-base: 2.0.4
firebird-driver: 2.1.1.dev0
Tested it using a firewall block rule on the local network side after my process hit ~20.000 rows. On version 2.1.1.dev0 no additional uncatched exceptions are raised. All WARNING and ERROR logger messages come from my code and are supposted to be there in this form. I'm happy with your changes/fix!
pcisar commentedon Oct 30, 2026
See version 2.1.1