Configuring

Depending on the use you're going to get out of Libgda, you may have to dig deep into its internals, but don't be afraid, things have been implemented to be easy to use.

Configuration for development

If you want to develop applications using Libgda, you should install the libgda-dev[el] package if you do a RPM or Debian-based installation. If you compiled the source code, development files are installed in your system.

The only step you need to do to make sure everything is well installed, is to check that Libgda libraries and binaries are seen by your system. That is, make sure that the Libgda bin/ directory is in your PATH environment variable, as well as the lib/ in your LD_LIBRARY_PATH (or /etc/ld.so.conf file).

Programs which need to use Libgda's features need to include headers files, which are:

#include <libgda/libgda.h>
#include <sql-parser/gda-sql-parser.h>
      
and to use reports:
#include <libgda/libgda.h>
#include <libgda-report/libgda-report.h>
      
and to use virtual connections:
#include <libgda/libgda.h>
#include <virtual/libgda-virtual.h>
      

Configuration for accessing a database

To access a database, it must have a database provider (if Libgda does not support the type of database to access, make a bug report in bugzilla), and that database provider must be compiled an installed: the gda-list-config-4.0 or gda-sql-4.0 -L commands will show a list of the installed and configured database providers.

Any connection to a database can be done either using a pre-defined data source, or using a connection string: using a data source (DSN) allows one to name connections and define them once, whereas using connection strings allows programs to be more independent of any Libgda configuration. Anyway, defining a DSN involves defining the same parameters as for a connection string.

A connection string is a semi-colon delimited list of named parameters (as <param1_name>=<param1_value>;<param2_name>=<param2_value>...), the parameters being specific to each database provider (the two commands mentioned above also list all the parameters for each provider).

DSNs can be configured on a per-user basis or on a system-wide basis. Each user's own DSN definitions are stored in the $HOME/.local/share/libgda/config file (which is created the first time Libgda is used within an application. System wide DSN are defined in the <prefix>/etc/libgda/config. Rather than editing that file manually, it is possible to use the gnome-database-properties-4.0 from the Libgnomedb library. Note: if the $HOME/.libgda/config already exists from a previous use of Libgda, then that file is used instead of $HOME/.local/share/libgda/config.

Provider's specific information

This section provides information specific to each of the available Libgda providers.

Default provider

The GDA default provider (based on an SQLite database file) is always installed with Libgda, which means that a default database system is always available. Specifically the first time you use Libgda, a test database is copied into $HOME/.local/share/libgda/config (or $HOME/.libgda if it exists and $HOME/.local/share/libgda/config does not) named "SalesTest".

ODBC Provider

The ODBC provider is a special case, since ODBC is itself a data access layer, the same as Libgda. So, in the case of the GDA ODBC provider, the DSN string is completely up to the ODBC driver manager. That is, the GDA ODBC provider does not parse it all, nor does it try to understand what it means; it simply passes it over to the ODBC library.

So, if you want to use Libgda with ODBC, you should first know how to set up an ODBC data source, and then just specify the DSN string you would pass to the ODBC library in the DSN string of the GDA data sources.

There is a project called unixODBC, which provides some graphical tools to help you in setting up ODBC data sources. You may find it interesting to give it a try.

Common to all provider

Each provider exports a list of the arguments it requires in its connection string which is used internally by Libgda to establish each connection. If you don't use a GUI which proposes you valid choices (such as GNOME-DB), you can get that list in each file named <provider_name>_specs_dsn.xml installed in the $PREFIX/share/libgda directory. This file is easy to parse and read.