xp-framework/rfc — Issue #58: New rdbms exception
Author: thekid
Created: 2011-10-17 15:49:28+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
A new exception will be added to the rdbms package indicating a connection
loss during server query.

Rationale
====
Currently there is no determination which type of error caused an SQLException
during query. Sometimes it's helpful to know if a connection has been closed by
foreign host.

Functionality
====

Changes to existing classes
----
The query() method of the rdbms.DBConnection subclasses will be changed and in cases
where the connection was lost during query a new Exception will be thrown. This
exception extends rdbms.SQLStatementFailedException to avoid bc-breakes.

Example patch excerpt for rdms.mysql:

```php
flags & DB_UNBUFFERED) {
$result= mysql_unbuffered_query($sql, $this->handle, $this->flags & DB_STORE_RESULT);
} else {
$result= mysql_query($sql, $this->handle);
}

if (FALSE === $result) {
switch ($e= mysql_errno($this->handle)) {
case 2013: // Lost connection to MySQL server during query
return throw(new SQLConnectionClosedException(
'Statement failed: '.mysql_error($this->handle),
$sql,
$e
));
break;

default:
return throw(new SQLStatementFailedException(
'Statement failed: '.mysql_error($this->handle),
$sql,
$e
));
}
}
?>
```

New Exceptions
----
A new exception rdbms.SQLConnectionClosedException will be added to the repository. This
class extends rdbms.SQLStatementFailedException.

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
- New class SQLConnectionClosedException
Will be added to uses() in rdbms.DBConnection

Related documents
====
- http://xp-framework.net/downloads/rfc0058.diff
Patch implementing this RFC for rdbms.mysql

- http://xp-framework.net/downloads/rfc0058-sybase.diff
Patch implementing this RFC for rdbms.sybase

- http://xp-framework.net/downloads/disconnect.phps
Test script. Start it, then shut down the RDBMS server while it's
running and look at the exception to derive what criteria signals a
connection loss.

- http://xp-framework.net/downloads/rfc0058-unittests.diff
Patch against net/xp_framework/unittest/rdbms implementing tests for
this new behaviour.