What are common/best practices for frameworks handling standard third-party exceptions?

Question

Amongst other things in my life, I'm writing a framework in PHP to manage a slew of common problems I come up against in every project I tackle. The framework is currently very data-centric, with the largest component (named Data) being part-ORM and part-DDD in it's approach.

The ORM-ness of this component heavily abstracts away queries to the point that the developer doesn't need to know any SQL or even know SQL terminology. The main drive behind this comes from my experience as a DBA/BIDev, where I groaned over many of the poorly constructed queries by SQL amateurs that convoluted things rather than took the simplest most direct approach. As an example, the following code would rSELECT ... FOR UPDATE from the user table where username is 'jennifer':

$userFilter = $userRepository->createBlank();
$userFilter->username()->identifyValue('jennifer');
$userFilter->lockForUpdate();
$user = $userRepository->retrieve($userFilter);

I test my framework against several applications that I'm involved with, meaning I can mock live-fire scenarios to an extent. In recent tests, I came up against the following error:

SQLSTATE[0A000]: Feature not supported: 7 ERROR: FOR UPDATE is not allowed with window functions Failed query is: SELECT * FROM "myView" WHERE "ID"=:fi_ID__ix0 FOR UPDATE;

It turns out that the view myView contains a column that is generated by an OLAP/window function (i.e. ROW_NUMBER() OVER(PARTITION BY...), which means that the view cannot be selected for update. The error was generated by PostgreSQL, is entirely legitimate, and is naturally in response to this invalid operation.

What I'm wondering is, what are the common/accepted ways that frameworks handle third-party problems like this? Throw the error message verbatim and let the developer figure it out, or try to value-add to the message by suggesting common problems or avenues of investigation?

Answer 1

Your framework is an abstraction layer. But all abstractions are leaky. You can't cover all cases, for all known databases, so you finally need to rely on a developer in spite of this situation you are mentioning:

... this comes from my experience as a DBA/BIDev, where I groaned over many of the poorly constructed queries by SQL amateurs that convoluted things...

You can't protect them when something goes wrong. So instead, give them all the necessary information to fix the situation (i.e. the actual exception).

However, the client application should not have to deal with different database exceptions. Your framework should have its own exceptions. The applications will handle anything coming from the data layer using only the exceptions from the framework, without knowing the underlying implementation of the particular database technology.

Your framework exceptions will wrap the original ones. Applications react to your exceptions keeping everything homogeneous across database changes, while at the same time you have everything you need to debug it inside the original exception (you could replace the exceptions that might come from the database with your own but most times it's better to just wrap those of the underlying database to avoid loosing any information when something does go wrong in a way you didn't expect or anticipate).

Answer 2

Throw the error message verbatim and let the developer figure it out, or try to value-add to the message by suggesting common problems or avenues of investigation?

Both options seem fine. I would base my decision on the information given by the library provider.

Some libraries (overall those built for non-commercial purposes) are very "spartan" in the details and documentation. We all have seen (now and then) error messages such as:

Error. Incorrect data

Oh man! What the hell is that supposed to mean? Did I send wrong data? Wrong formats? Wrong ranges? What went wrong ?!?!

If you can hide such abomination, if you can to give more context and feedback, developers will appreciate it. A lot. And so will everyone else involved in the project.

On the other hand, there are libraries (and products) very well documented which developers take care of these details. Your example can be a good one.

PostgreSQL is already giving enough information for developers to research. For example, starting by searching what SQLSTATE[0A000] means. It's an error code and probably it's documented somewhere. So, whoever built the driver for PostgreSQL in PHP, didn't dare to add single coma to the error messages. There's no need! And so does whoever build a framework on top this driver.

It's likely both, error and solution, are going to be documented by those that already suffered it.

What I'm wondering is, what are the common/accepted ways that frameworks handle third-party problems like this?

Each framework looks after its development experience. That's what frameworks are all about. Different frameworks might approach the same issue from different directions.

So, I wouldn't care too much about what other frameworks do. I would focus on the development experience I want to give. How do I want the developers to feel with my framework? If I found other frameworks which development experience and mine are alike, I would take note, but I would not take their approach as the way to go. Just one more approach I could adopt.

You might be interested

• Why do many exception messages not contain useful details?
• How to write a good message exception
• What are developer's problems with helpful error messages? (David Thornley's answer is interesting)
• Who should read Exception.Message if at all?

Related questions

• Search is:question [exception] message