## 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).

You have to include a headers file, and it is:

    #include <libgda/libgda.h>

### Configuration for accessing a database

If you want to access a data source through a GDA provider, you must first of all have access to this provider, and most importantly, this provider should have access to its specific data source. So, first have your database up and running. For this, you'll have to check your specific data source documentation, or see the libgda providers' specific documentation.

Once you've got your GDA provider installed, whether on your machine or on another one on the network, you must configure your local system to have access to it. If you're on a local installation, once you have installed the GDA provider (by compiling it or by installing its RPM or Debian package), the provider is visible in your machine. This is because the provider installs itself in a well known location that makes libgda itself know about the new provider.

Then, the next step is to configure the data sources you want available on your system. For doing this, you should, as for now, use GNOME-DB, which is a front-end to libgda for the GNOME project. [1]

Command-line tools will be provided in libgda for doing so in a not-too-distant future, so you may want to know what information you need to setup a data source.

One of the problem GDA solves is the naming of data sources. Every database system has it's own way of defining names for it's databases. For example MySQL uses the hostname, port number, and the name of the database. Other databases, like Solid use the hostname and port number only. There is no support for multiple databases per server. Because the client does not need all these details, the libgda configuration defines all the properties of such a data source, so that the correct data base server can be contacted. This information is accessed by the client library and sent to the provider, which in turn will parse the string to decide which database must be connected to. The data stored for each data source is as follows:

    	      [sales]
    	      Provider=MySQL
                  DSN=DATABASE=test;HOST=localhost;PORT=1111
    	      Description=MySQL Test Database in native mode
    	      Username=username
    	      Password=password

| The provider for this database is the gda-mysql provider. The value of this entry is used as the object ID for the plug-in activation.
| This is the most important entry. The value of this entry is the string sent to the provider so that it knows which datasource to access. How this entry is interpreted by the providers is described in the provider section. There are, though, a set of default properties that can be used for the connection string for all providers. Those are: USERNAME: user name to be used for authentication. PASSWORD: password to be used for authentication.
| The value of this entry is a short description of the datasource. It is here for convenience only and it is not used for any purpose.
| The user name to be used when connecting to the database.
| The password to be used when connecting to the database. This is stored in plain text, so be sure you restrict access to the configuration files to any "dangerous" users.

For each user, libgda has two possible configuration files: one local to the user which is stored in `~/.libgda/config` and one which is for all the users on the system which is `<prefix>/etc/libgda/config` where <prefix> is where the libgda library has been installed.

It is not recommended to modify configuration files by hand (instead use the gnome-database-properties application from the GNOME-DB library. For our example, a configuarion file is:

    <?xml version="1.0"?>
    <libgda-config>
      <section path="/apps/libgda/Datasources/sales">
        <entry name="DSN" type="string" value="PORT=1111;DATABASE=test;HOST=localhost"/>
        <entry name="Description" type="string" value="MySQL Test Database in native mode"/>
        <entry name="Password" type="string" value="password"/>
        <entry name="Provider" type="string" value="MySQL"/>
        <entry name="Username" type="string" value="username"/>
      </section>
    </libgda-config>

#### Managing data sources with API functions

##### Create data sources

To create a data source you must use the function gda-config-save-data-source ()

Here you see how to create a data source named foo_ds. If you do not need to give an username or password to enter the database, you could put NULL.

                gda_config_save_data_source ("foo_ds", "PostgreSQL", "DATABASE=foo_db",
                                             "description of foo_ds", "foo_username", "foo_password");
                gda_config_save_data_source ("other_foo_ds", "MySQL", "DATABASE=other_foo_db,HOST=db.foo.com",
                                             "description of other_foo_ds", "foo", NULL);

For more details about provider specific information see in the section about providers specific information.

There was a little bug[2], and it is that gda_config_save_data_source() does not create the configuration directory `~/.libgda`, so you have to do it.

There is no problem about calling several times to this function because if you save an existing data source, it is replaced.

##### Removing data sources

To remove a data source you must use the function gda-config-remove-data-source ()

Here you see how to remove a data source named foo_ds.

                gda_config_remove_data_source("foo_ds");

##### Listing available data sources

To list available data sources you must use the function gda_config_get_data_source_list ()

Here you see a function which lists the available data sources.

                  void
                  list_datasources (void)
                  {
                    GList *ds_list;
                    GList *node;
                    GdaDataSourceInfo *info;

                    ds_list = gda_config_get_data_source_list ();

                    g_print ("\n");
                    for (node = g_list_first (ds_list); node != NULL; node = g_list_next (node))
                      {
                        info = (GdaDataSourceInfo *) node->data;

                        g_print
                          ("NAME: %s PROVIDER: %s CNC: %s DESC: %s USER: %s PASSWORD: %s\n",
                           info->name, info->provider, info->cnc_string, info->description,
                           info->username, info->password);

                      }
                    g_print ("\n");

                    gda_config_free_data_source_list (ds_list);

                  }

| Our function.
| Note that you must free the list when you finish using it.

##### Listing available providers

To list the available providers you must use the function gda_config_get_provider_list ()

Here you see a function which lists available providers.

                  void
                  list_providers (void)
                  {
                    GList *prov_list;
                    GList *node;
                    GdaProviderInfo *info;

                    prov_list = gda_config_get_provider_list ();

                    for (node = g_list_first (prov_list); node != NULL;
                         node = g_list_next (node))
                      {
                        info = (GdaProviderInfo *) node->data;

                        g_print ("ID: %s\n", info->id);

                      }

                    gda_config_free_provider_list (prov_list);

                  }

| Our function.
| Note that you must free the list when you finish using it.

### Provider's specific information

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

#### Default provider

The GDA default provider is always installed with libgda, which means that you've got always a default database system available for you. To connect to a default provider's database, you only need to specify, in the DSN string, a string of the form "URI=/path/to/the/database/file". When you first connect to the new data source, the GDA default provider will create the database, in the path you specified in the DSN string, if it does not exist. This default provider uses XML as the format for that file.

#### 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.

#### PostgreSQL Provider

To use the GDA PostgreSQL provider, you'll need the gda-postgres package.

The PostgreSQL provider accepts the following arguments in the GDA data source's DSN string:

- HOST: name of the host where the database server is running. If it begins with a slash then the protocol used is Unix-domain instead of TCP/IP and its value is the name of the directory where the file is stored. By default: /tmp.

- HOSTADDR: IP of the host where the database server is running (avoids DNS lookup). If this option has a value, TCP/IP communications is used. If neither a host name or host address is specified, the connection will be established using a local Unix domain socket.

- PORT: Port number or socket filename extension for Unix-domain connections.

- DATABASE: name of the database you want to access. This one is called 'dbname' in the PostgreSQL documentation.

- USER: user name to connect as.

- PASSWORD: password if the connection requires it.

- OPTIONS: trace/debug options to be sent to the server.

- TTY: a file or tty for optional debug output from the back-end.

- REQUIRESSL: set to '1' to force SSL connection to the back-end. Set to '0' to negotiate with server.

The description of the parameters is almost copied from the PostgreSQL documentation. Refer to it for details on how some environment variables can also set these parameters.

#### MySQL Provider

To configure a data source to access a MySQL database, you'll need to install the GDA MySQL provider (package `gda-mysql`).

It accepts the following arguments in the DSN string:

- HOST: name of the host where the database server is running.

- PORT: port number for connecting to the database server.

- UNIX_SOCKET: socket file for connecting to the database server (should not be defined with HOST and/or PORT).

- DATABASE: name of the database you want to access.

- USER: employ the specified user name for logging in to the server.

- PASSWORD: employ the specified password when connecting to the database server.

- USE_SSL: will use SSL (encrypted protocol) if specified and set to 1.

#### Sybase Provider

To use the GDA Sybase provider, you'll need the gda-sybase package.

The Sybase provider accepts the following arguments in the GDA data source's DSN string:

- HOST: name of the host where the database server is running.

- USERNAME: user name to connect as.

- APPNAME:

- PASSWORD: password if the connection requires it.

- DATABASE:

[1] It would be a good idea to add a command-line tool for managing the configuration, as now, using `GConf`, is not a matter of hacking on a config text file, as it was before with `gnome_config`. The API for doing so is already available in the `libgda-common`library, so it would be really easy. Volunteers?

[2] It can be fixed, but it is better not to run the risk of it.