Configuring: GNOME Data Access 5 manual

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-5.0 or gda-sql-5.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 gda-control-center-5.0 tool (part of Libgda). 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.

SQLite provider

The SQLite provider is always installed (it is required by Libgda's internally) 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".

Connection information for each database 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. To obtain the required information to open a connection using a provider, use the Gda SQL console tool with the -L <provider name> option. For example for PostgreSQL (strings truncated for better readability):

$ gda-sql -L PostgreSQL
                   Provider 'PostgreSQL' description
Attribute      | Value                                                   
---------------+-------------------------------------------------------------
Provider       | PostgreSQL                                              
Description    | Provider for PostgreSQL databases                       
DSN parameters | DB_NAME: The name of a database to connect to (string),     
                 SEARCHPATH: Search path among database's schemas ('search_path' variable) (string),
                 HOST: Host on which the database server is running (for servers running on unix domain sockets, enter the socket's path (usually /tmp), or leave this field empty).
                 PORT: Database server port (for servers running on unix domain sockets, enter the socket's file name extension (usually 5432), or leave this field empty).
                 OPTIONS: Extra connection options (string),                 
                 USE_SSL: Whether or not to use SSL to establish the connection (boolean),
Authentication | USERNAME (string),                                                         
                 PASSWORD (string)
File           | /local/lib/libgda-4.0/providers/libgda-postgres.so
(5 rows)