New rdbms exception

[thekid]

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
  if ($this->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.

[thekid]

Need to test this for Sybase and PostgreSQL, too.

friebe, Mon, 12 Jun 2006 11:02:08 +0200

[thekid]

Maybe ConnectionClosedException should be SQLConnectionClosedException? - just to be consistent with the rest of the SQL* exceptions...

friebe, Mon, 12 Jun 2006 11:24:55 +0200

[thekid]

Discussion with RFC author - SQLConnectionClosedException is OK.

friebe, Mon, 12 Jun 2006 11:48:38 +0200