ANNOUNCE gnome-db

[Michael Lausch <mla gams co at>]

I'm announcing gnome-db.


It's a database frontend for Gnome based on ODBC. ODBC was choosen
because ODBC drivers exist for almost every database ODBC drivers.

The development language is C, because Gtk is a C toolkit and it
offers a great mechanism for user defined types and a signal
mechanism. Writing C++ wrapers is easy, at least easier then writing C 
wrappers for a C++ library.

It was part of gnome-filer. Since gnome-filer, developed by Michael
Fulbright (msf@redhat.com), is frozen and the development goals are not 
the same (at least for the time being) i decided to seperate gnome-db
from gnome-filer. Care will be taken that the data structures used by
gnome-filer and gnome-db will stay compatible, so that later the two
systems can be merged without great effort.


What's currently implemented:

Database login widget

Database cursor abstraction layer with memory mgmt and signal
mechanism for automatic update of entry fields when new values are
fetched from the database.

the beginnings of a table editor, which enables you to browse the data 
definitions of columns in a table, and wl enable you to create tables, 
and chane tables.

Short description of currently implemented parts:

3) I'm going to implement automaic db update from entry fields and and
GUI updates from database cuors (this case already works). It is
designed with signals and the paradigma is that of a
Model/View/Controler.

You have a db cursor which can execute arbitrary SQL statements. With
the fetch calls to retrieve data from the database. whenever the
cursor does a fetch call, it emits the "new_values" signal. This
signal can be handled by the entry fields in order to update its
content. Problem is: the memory needed for the value from the database
is malloc'ed and needed to be freed somewhen.  The entry fields
themself can't do this, because they don't know if the value isn't
need by any other instance. But thanks to gtk's signal mechanism we
have the ability to have a signal handler run at last which will
simply free all memorty. So if any entity needs the data for a longer
period of time than the signal handling function is running, it has to
make a copy of the data. Most of this mechanism is implemented already
in the gnome-db-cursor.c file.


Implemented are gnome_db_login, gnome_db_cursor_new,
gnome_db_cursor_exec, gnome_db_cursor_fetchone.


The API looks like:

* db = gnome_db_login(gchar* connection_string, gchar* user, gchar* passwd);

   connection_string is a db specific identifier which identifies the
   database for ODBC it's the DSN. I plan to do something like the
   ODBC mgr in windows where you can setup with DB specific tools
   configuration entries which look sonmething like:

[db1]
connection_string = tcp/ip localhost 1313
dblib=/usr/lib/libscllux.so

[db2]
connection_string = postgreshost:2020
dblib=/usr/lib/libpq.so

......

and the connection_string for gnome_db_login ist `db1' or `db2'

* cursor = gnome_db_cursor_new(db, "cursor1");

  returns a cursor with name "cursor1".

* rc = gnome_db_cursor_execute(cursor, <sql string with parameters>,
                               <parameter list>);

  prepares the cursor and executes the statement. <sql string with
  parameters> is the query where variables are indicated with a `?'.
  <parameter list> is a list of values used to substitute the `?'
  variables in the query.

  rc is either:
   0 for success and query is a select stmt.
   > 0 number of affected rows if query is simething like update or
   insert.
   -1 on error

* dbr = gnome_db_cursor_fetchone(cursor);

  returns one dbr (database row) from the cursor's query. It also
  emits the signal `new-values' if new values have been fetched. You
  can bind to this signal to update am entry_field. dbr is passed as
  a parameter to the signal function.

* rc = gnome_db_cursor_close(cursor, <drop everything>)

  closes the cursor. if <drop everything> is TRUE, all db context and
  associated memory is freed for this cursor

* description = gnome_db_cursor_description(cursor);

  returns a GPtrArray* which holds description entries for the
  resulting rows of the SQL statement associated with the cursor.
  Each entry of this aray is a ptr to a struct:
     name of the column
     type of the coumn
     precision, sclane, length, is_nullable, .... and other
     information. 

All gnome_db_... functions emit 2 singals "db-warning" and "db-error" 
if something goes wrong in any of these functions. the defaul handler
just raise a dialog box with the error msg, but it is also possible to 
intercept the signals, handle the error and stop the default handlers
to run. 

What are the next steps:

Short term goals (August)
Use iodbc to connect to different database systems and integrate the
postgesql and MySQL ODBC drivers.

Abstraction of database meta information (tables, columns, events,...)
so that the admin tools can be used without being rewritten for every
database.

Medium term goals (middle of October):
Text based SQL querty tool, utilizing the gnumeric widgets to allow
browsing and editing of dstabase content.

Long term goals (end of the year):
Graphical Query builder like in MS Access (i want to have feedback
about this. Does anyone have a better idea?)

Very long term goals (Unknonwn):
Integration with gnome-filer and scripting support (python and perl
come to my mind) to allow rapid prototyping of applications.



Snapshots are available int the <ftp://ftp.gams.at/pub/gnome>
directory.