A small tutorial on the gda-srv lib

[Vivien Malerba <malerba linuxave net>]

Hi all!

>From my experience with the gda-srv lib, I've written a small tutorial on what
needs to be done to write a new provider. It is with this mail.

Maybe, after correcting some stupid things, Rodrigo could put it on the WWW
site, no?

Cheers,

Vivien
0 - Foreword

I wrote this brief documentation to help programmers write providers for their favorite DBMS if it does not exist. It is a summary of what I've learned from my experience of writing the Postgres provider using the Gda-Srv library. It may contain some errors or inaccuracies. If that is the case, please tell me (at malerba@linuxave.net).

What I call a provider for a DBMS is the gnome-db program that needs to be written to be the layer between gnome-db and the DBMS (it is a client of the DBMS).

1 - Architecture
1.1 - Purpose of the Gda-Srv library

The purpose of this library is to hide all the CORBA stuff from the provider's programmer and avoid duplication of work which leads to a code much more easy to debug. That lib stands at the same level as the Gda-Clnt lib from the CORBA point of view.

The Gda-Srv Library imposes a framework on the way the provider needs to be implemented, but allows for specific customization.


1.2 - Objects in the library

All the objects here are the mirror objects from the Gda-Clnt library from the server side of the gnome-db CORBA framework.

These objects are:
* the Gda_ServerConnection object: this is the main object and handles everything regarding a connection to the DBMS (given the DB name, user name, password, etc). Usually the client will use only one of this kind of object.

* the Gda_ServerCommand object: this object is used to prepare a query to be executed.

* the Gda_ServerRecordset object: every time a command is executed, an object of this type is returned, and can then be examined to see what the results of the command were. Under gnome-db, the recordset is examined in a sequential way, row after row (for some DBMS it is the way query results are handled while for others there is a possible random access).

* the Gda_ServerField object: for every column, an object of this kind is used. It describes the column name, the data type, and a contents. Each Gda_ServerField object will be initialized when the recordset is created, and a new value will be stored in it every time a new row is examined. The Gda-Srv will then use these objects to send the contents to the client CORBA side.

1.3 - How a query is processed

When a client makes a query, what happens in the server side is:
1- a Gda_ServerConnection is created
2- the connection is opened
3- a Gda_ServerCommand is created
4- the actual command is set in the Gda_ServerCommand object
5- the command is executed, and if no error occurs, a Gda_ServerRecordset is created and returned
6- the Gda_ServerCommand can safely be destroyed (???????)
7- the first row of the recordset can be examined, then the 2nd, etc
8- the Gda_ServerRecordset is destroyed
9- the connection can be closed, and the Gda_ServerConnection can be destroyed.

1.4 - Actual DBMS customization work

All the steps described above are imposed by the gnome-db framework. The work of writing a provider for a specific DBMS is in writing the specific parts of the operations described above. 

As the C library for a DBMS uses some specific structures (to handle connection references, etc, it is possible to attach some information to the Gda-Srv objects. So usually the provider's programmer defines the following structures (here I DBMS for the actual DBMS name like for example MYSQL or POSTGRES):
* a connection structure usually named DBMS_Connection
* a command structure usually named DBMS_Command
* a recordset structure usually named DBMS_Recordset


2 - Actual DBMS implementation

In this chapter are some recommandations on how to handle some specific items for each DBMS.

2.2 - Data types handling

Gnome-db has some defined data types, covering all the usual data types (strings, numbers, dates, binary, etc). However, because each DBMS has some more specific data types (like for example arrays, IP adresses), and it is sometimes possible to create some user defined data types, not all the data types can be known by gnome-db.

So, for the most common ones where a gnome-db data type exists, it will be used, and otherwise the Gda_TypeUnknown will be used (and then is it up to the application programmer using gnome-db to take good care of that information).

2.3 - Schemas requests

Under gnome-db, the client application cannot know the DBMS to which it is connected, but as it can know if the DBMS supports some features and what are the tables, sequences, indexes, etc in the DB.

One of the most time consuming jobs is to write the fuctions to return answers to all these client requests.

2.4 - Functions to implement

The basic work to do is implement a set of functions necessary for the Gda-Srv to manipulate the provider. When a provider wants to start, it has to give pointers to these fuctions in a structure (see the main-DBMS.c file for this).

The other sets of functions to implement are schemas requests functions. Among the functions that you MUST implement is a function to request schemas. This function calls different functions depending on the actual requested schema. 

3 - Files & example
3.1 - Headers

Usually a provider has oly one header (gda-DBMS.h) which contains all the structures definitions, and the main functions declarations. This header needs to include the gda-serv.h files and ?????

The provider may need to use the common elements of the Gda-Common library (for XML stuff, etc when completed).

3.2 - .c files

Usually there is one .c file for the implementation of the different DBMS structures mentionned above, and of the main functions.

3.3 - Sample implementations

As of this writing, AFAIK, you can have a look at the MySql and Postgres providers (the Postgres implementation also uses a feature to make queries results out of the box, not something actually returned by the Postgres backend).