Skip to content


DBAL-765: [GH-494] Refactor, consolidate and extend driver exception conversion #1994

doctrinebot opened this Issue · 2 comments

2 participants


Jira issue originally created by user @doctrinebot:

This issue is created automatically through a Github pull request on behalf of deeky666:

Url: #494


This PR aims to have are more solid, abstracted and flexible driver exception conversion API as introduced in PR #364.
It removes the DBALExcpetion::ERROR_* constants in favour of returning the appropriate DBAL driver exception directly in the driver. Those constants are of no meaning anymore, as these exceptions get converted into dedicated exception instances anyways. This also allows custom driver implementations to handle their driver exception conversion manually and introducing custom driver exception classes. Moreover it saves one additional conversion step in DBALException.
A new DriverException interface has been introduced for driver exception to return the error code, SQLSTATE and message. This is an approach to have a uniform driver API just like Driver, Connection and Statement. This also offers some other opportunities.
Complementary the AbstractDriverException and PDOException classes have been introduced to provide the basic implementation and behaviour for driver exceptions.
PDOConnection and PDOStatement now wrap all method calls into try catch blocks, catch \PDOException and wrap it into DBAL's PDOException to provide DBAL's DriverException interface.
The API of the ExceptionConverterDriver has been changed to take the DBAL generated exception message and a DriverException instance to evaluate the driver specific error code and SQLSTATE in order to return the appropriate standardized DBAL driver exception instance.
The following DBAL driver exception class changes have been made:

  • Introduce a base DriverExcpetion class for all DBAL driver exceptions.
  • Introduce a ConnectionException class for all errors related to connection attempts (an abstraction just like the vendors do)
  • Introduce a ServerException class for all error related to operations made on the server (after the connection has succeeded, an abstraction just like the vendors do)
  • Introduce a DatabaseObjectNotFoundException class as a base class for referenced database objects like schemas, table, constraints, indexes etc. that do not exists in the database (useful also for SQL Server which cannot distinguish between unknown tables, sequences, indexes etc.).
  • Introduce a DatabaseObjectExistsException class as a base class for referenced database objects like schemas, table, constraints, indexes etc. that do already exists in the database (useful also for SQL Server which cannot distinguish between already existing tables, sequences, indexes etc.).
  • Introduce a ConstraintViolationException class as a base class for all constraint violations like foreign key constraints, unique constraints, not null constraints, check constraints etc. (useful also if you only want to determine whether a data intergrity problem was found)
  • Remove AccessDeniedException in favour of ConnectionException. The term "access denied" should be reserved for insufficient privileges on a database operation IMO. This exception until now also refered to network errors, unknown hosts etc. errors during a connection attempt. So IMO the term is misleading and should be changed to a more general connection error exception.
  • Rename NotNullableException to NotNullConstraintViolationException as it is a constraint in general and should also be named as such.
  • Renamed DuplicateKeyException to UniqueConstraintViolationException as it is a constraint and should also be named as such.
  • Removed FailedToOpenException and mapped it to ConnectionException as it is a SQLite specific exception and should be treated in a more general/abstracted sense.
  • Map ReadOnlyException to ServerException as it can only occurr if the connection has been established already. It was a connection error before.

There are a lot of changes that have been made but I think they are reasonable and important to have a better abstracted exception API. Also I would like to introduce a Configuration option for custom driver exception conversion which is only possible with this approach.

I hope you will like it, otherwise blame me to death! ;)


Comment created by @doctrinebot:

A related Github Pull-Request [GH-494] was closed:


Issue was closed with resolution "Fixed"

@doctrinebot doctrinebot added the Bug label
@beberlei beberlei was assigned by doctrinebot
@doctrinebot doctrinebot added this to the 2.5 milestone
@doctrinebot doctrinebot closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.