apr_dbd API ideas

[Edward Rudd <ed...@omegaware.com>]

I'm finally starting to hack away at Nick's new DBD API for APR, and have
noticed a few things about the API, which I have talked with Nick about on
IRC. And would like the thoughts of others.

One is a capabilities function in the driver API, to provide a way for the
application to figure out what features the driver does and does not
support. (ie. Transactions, Prepared Queries, etc..).

nick's quick prototype idea was
 apr_dbd_capabilities(driver, APR_DBD_HAS_TRANSACTION);

The other thing I noticed was the lack of standardized return codes from
the functions.  Most of the function return error codes from the DB layer.
It would be better to create a set of standard error return codes and map
them into the APR error space for DBD, so each driver will return a
standard set of errors to the application. This list of errors, however,
will have to be thought out well though.  As I know that the libdbi error
set is very limited to be useful.

Right now I am hacking with the autoconf to get the DBD drivers to link as
optional shared objects.

Regards,
Edward Rudd

Re: apr_dbd API ideas

[Graham Leggett <mi...@sharp.fm>]

Nick Kew said:

>> The other thing I noticed was the lack of standardized return codes from
>> the functions.
>
> Again, agreed.  I'm not quite sure what the procedure is for introducing
> new APR error codes, but ideally we should do that.

I ran into the same problem with this in APR-util and the LDAP bindings.

What I eventually did was define a return code structure that got passed
back to the caller, with the standard APR codes (I basically used
APR_SUCCESS and APR_EGENERAL).

The structure contained the raw error code of the backend (in this case
the LDAP toolkit in use), a human readable string msg representing the
error code (the LDAP API provides this), as well as a human readable
string reason with some added details of what the API was trying to do
when the error occurred.

The point behind the exercise was to prevent the calling application
having to work all of this out itself (translated as: the calling
application is very unlikely to go to the trouble to work all of this out
itself leaving the end user trying to figure out what a meaningless number
means).

The struct looks like this:

/**
 * This structure allows the C LDAP API error codes to be returned
 * along with plain text error messages that explain to us mere mortals
 * what really happened.
 */
typedef struct apr_ldap_err_t {
    const char *reason; // APR generated explanation
    const char *msg; // toolkit specific error maps to rc
    int rc;
} apr_ldap_err_t;

Regards,
Graham
--

Re: apr_dbd API ideas

[Edward Rudd <ed...@omegaware.com>]

On Tue, 22 Feb 2005 10:56:24 +0000, Nick Kew wrote:

> 
> One more point here: for DSO loading of drivers, we could perhaps use
> a "magic" versioning number.  Making that APR-wide would make sense,
> preparing the ground for possible APR module support in other areas.
> Any thoughts?

Well, my hacking of the python and autofoo thus far is adding a mostly
generic method of handling DSO building of objects. I hope to post the
initial workings of this in a an hour or so.

Re: apr_dbd API ideas

[Nick Kew <ni...@webthing.com>]

Edward Rudd wrote:
> I'm finally starting to hack away at Nick's new DBD API for APR, and have
> noticed a few things about the API, which I have talked with Nick about on
> IRC. And would like the thoughts of others.
> 
> One is a capabilities function in the driver API, to provide a way for the
> application to figure out what features the driver does and does not
> support. (ie. Transactions, Prepared Queries, etc..).

Agreed.

I made a conscious decision not to add that to the API before it went
under SVN: basically once it had reached "works well for me" and was a
candidate for inclusion, keeping it stable became the priority.  That
no longer applies:-)

> The other thing I noticed was the lack of standardized return codes from
> the functions.

Again, agreed.  I'm not quite sure what the procedure is for introducing
new APR error codes, but ideally we should do that.

> Right now I am hacking with the autoconf to get the DBD drivers to link as
> optional shared objects.

That really is great!  I've been struggling with TFM autoconf myself,
and the best I've done so far is more-or-less verbatim copying of
existing code.  Clues especially welcome in this area:-)

One more point here: for DSO loading of drivers, we could perhaps use
a "magic" versioning number.  Making that APR-wide would make sense,
preparing the ground for possible APR module support in other areas.
Any thoughts?

-- 
Nick Kew

Re: apr_dbd API ideas

[Mads Toftum <ma...@toftum.dk>]

On Mon, Feb 21, 2005 at 09:17:03PM -0500, Garrett Rooney wrote:
> I agree, it would be good to do something about that.  You might want to 
> look at how the ldap API handles this kind of thing.  If I recall 
> correctly they've got some sort of error object they return which in our 
> case could contain both underlying database error codes, a standardized 
> APR error code, etc.
> 
Something like that would certainly be preferable - in the general case
standard error messages might be fine, but we'd be missing a lot
of useful info if there was no way to access the raw error.

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall

Re: apr_dbd API ideas

[Garrett Rooney <ro...@electricjellyfish.net>]

Edward Rudd wrote:
> I'm finally starting to hack away at Nick's new DBD API for APR, and have
> noticed a few things about the API, which I have talked with Nick about on
> IRC. And would like the thoughts of others.
> 
> One is a capabilities function in the driver API, to provide a way for the
> application to figure out what features the driver does and does not
> support. (ie. Transactions, Prepared Queries, etc..).
> 
> nick's quick prototype idea was
>  apr_dbd_capabilities(driver, APR_DBD_HAS_TRANSACTION);
> 
> The other thing I noticed was the lack of standardized return codes from
> the functions.  Most of the function return error codes from the DB layer.
> It would be better to create a set of standard error return codes and map
> them into the APR error space for DBD, so each driver will return a
> standard set of errors to the application. This list of errors, however,
> will have to be thought out well though.  As I know that the libdbi error
> set is very limited to be useful.

I agree, it would be good to do something about that.  You might want to 
look at how the ldap API handles this kind of thing.  If I recall 
correctly they've got some sort of error object they return which in our 
case could contain both underlying database error codes, a standardized 
APR error code, etc.

> Right now I am hacking with the autoconf to get the DBD drivers to link as
> optional shared objects.

Excellent!

-garrett