Re: [gnome-db] prepare_create_database() and perform_create_database()

["Vivien Malerba" <vmalerba gmail com>]

On 11/7/06, Murray Cumming <murrayc murrayc com> wrote:
> Looking again, this is obviously even more complicated than I thought,
> but I can't find any example for this, and the documentation does not
> suggest what should be done.
>
> On Tue, 2006-11-07 at 20:19 +0100, Murray Cumming wrote:
> > I think I've asked about this before, but I'm still confused.
> >
> > I don't understand why this is necessary:
> > GdaServerOperation* operation =
> > gda_client_prepare_create_database(client);
> > gda_client_perform_create_database(client, database_name, operation);
> >
> > instead of just
> >
> > gda_client_create_database(client, database_name, operation);
> >
> > (There was a gda_connection_create_database in the previous API).
> >
> > The ServerOperation thing seems like an implementation detail that I
> > shouldn't have to care about.
> >

The GdaServerOperation object holds the specifications of each DBMS to
perform an action (create a database, an user, etc): you can see it as
a formalization of the features a DBMS offers for an action.

The reason we need such an object is because each DBMS has
differencies in term of parameters for an action, and the rendered SQL
is also very different. So instead of trying to render SQL in the
generic part of libgda, we ask each provider what named parameters it
needs/can have for an action, and the let it render the SQL (an do the
action) itself once we have filled in the parameters.

Now for all the possible operations, Libgda's documentation (section
DDL queries) mentions some named parameters which will always be
present: for example for the CREATE DATABASE operation, here is the
list (badly indented...) where "path" is a parameter name:
Path 	            Type 	         Required? 	Description
/DB_DEF_P 	PARAMLIST 	Yes 	Database's description
/DB_DEF_P/DB_NAME 	PARAM 	Yes 	Database name (string)
/DB_DEF_P/DB_CSET 	PARAM 	  	Character set (string)
/DB_DEF_P/DB_OWNER 	PARAM 	  	Database owner (string)
/DB_DEF_P/DB_TABLESPACE 	PARAM 	  	Tablespace the database is in (string)

If we had kept the previous single one call API, then it would not
have been possible to exploit _all_ the features of each DBMS; this
approach allows that and at the same time ise still quite easy to use
(even though it is a bit more complicated than a single API call).

Please have a look at the Libgda's doc about DDL queries and at the
GnomeDbServerOperation widget which displays a widget where all the
parameters can be entered for a GdaServerOperation object. Of course
if the documentation is not complete enough, it can be improved...

An example of how to use the concept can be found in the
testing/test-dyn-widgets.c file of libgnomedb starting line 2551.

Cheers,

Vivien