# Introduction

## Overview

&ODBC; and &SQL; are established standards. However &ODBC; is mostly limited to the Microsoft Windows environment (even though the UnixODBC project exists and links to some drivers), and the API is quite old and not well integrated into the GNOME ecosystem.

&SQL; itself is standardized but up to some point only, so that &SQL; source compatibility can not be assured for all database servers. And for some sort of servers, &SQL; is not even feasible (think about &LDAP;).

&JDBC; is a more recent standard which replaces &ODBC; in the Java world, but it's limited to the Java programming world, and is difficult to integrate in C (or other languages different from Java). There are however a lot of JDBC drivers out there for many database engines.

&GDA; (GNOME Data Access) tries to tackle the &ODBC; and &JDBC; "limitations" and help you with the &SQL; problem. It's a sort of middleware to access different data sources. It offers a high level view of data sources and has some places where you can plug in low level access to the database for special tasks.

It offers a wrapper around the database internals, thus making it easier for programmers to make use of all the power provided by many RDBMS without knowing much about it. It comes as a set of libraries, a core one and some extensions (the GTK+ UI extension for example) and some drivers for the most common OpenSource or proprietary database engines.

Some of these drivers are a bit special: the LDAP provider allows one to adress an LDAP directory as if it were composed of tables (provided some configuration), and the &JDBC; provider "wraps" any &JDBC; driver.

Along with these libraries (and associated header files and language bindings for development), &LIBGDA; includes several tools and utilities to help you with the task of developing applications based on &LIBGDA;, as well as for automating some database-related tasks.

&LIBGDA; is implemented for UNIX -like operating systems (including Linux ), and Windows .

## Features

This section presents the main features of the 5.2 version of Libgda.

Libgda is a low-level database abstraction layer built on top of each database C API. In terms of abstraction, Libgda offers the following top features:

- Open a connection to any database which type is supported using either a defined data source (defined per user or system wide) or directly providing connection parameters. Several connections can be opened at the same time.

- Run any SQL query against an opened connection; furthermore any SQL query can be extended to define query parameters using an easy to understand notation. If the SQL query was a SELECT statement, then an array of data is returned (as a `GdaDataModel` object), and otherwise the number of rows affected by the query is returned. For very large data sets, it is possible to specify that the returned array of data should be based on a cursor to avoid loading it into memory.

- Perform most of the data definition queries (including database creation) for the database types which support it using a key/value mechanism.

- Create, maintain and extend a view of the database's structure and meta data including the definitions of the tables, constraints, data types, .... It is defined as closely as possible to the information schema SQL standard (ISO/IEC 9075); see the Dictionary - metadata section for more information.

- Easy to extend data models for custom requirements

- Support for binary data and for BLOBs in a transparent way, see the Gda value section

- Support for detailed parameters in SQL queries, see the GdaSqlParser object

- Support for virtual connections, see the Virtual connections chapter

- Partially thread-safe, see the threads limitation for more details

The database types which can be accessed at the time of writing are the following ones:

- MySQL: fully functional;

- PostgreSQL: fully functional;

- SQLite: fully functional;

- SQLCipher: fully functional;

## Architecture

A &LIBGDA; application is composed of three layers. The lower level layer are the &GDA; providers: plug-ins whose task is to map the &RDBMS;-specific &API; to the &GDA; model.

Then, in a middle layer, are the libraries provided by &LIBGDA; and used by the programmer: an easy-to-use and full featured set of libraries.

Finally, at the upper layer is the application part itself, as writen by the developer.

Typical &LIBGDA; application's architecture

Architecture of an application connected to 4 databases of 3 different types.

&LIBGDA; also includes:

- some example code which can be "cloned" to create new database providers for database engines not yet supported by &LIBGDA;

- a graphical configuration manager

- an SQL console to connect to dabatase serveurs and perform some &LIBGDA; related administrative tasks

- some other more specific tools

## Data sources

To open a connection, the programmer needs to specify the database provider to use, and some connection parameters, some of them specific to the database engine to be used, some of them more generic (such as the "DB_NAME" parameter to specify a database name).

All the parameters are combined together to give &LIBGDA; enough information to open a connection; refer to gda_connection_new_from_string() for more information.

However, remembering the complete string to open a connection can be tedious, and so &LIBGDA; supports named data sources (DSN) whereby a connection is specified and named once and opened refering to its name rather than to the actual parameters used. Refer to the Define a data source (DSN) section, and the gda_config_define_dsn() and gda_connection_new_from_dsn() functions.

DSN can have a scope limited to the user, or be system wide. User scope DSN definitions are stored in $XDG_DIR/libgda where $XDG_DIR is determined by the XDG Base Directory Specification (using g_get_user_data_dir()). System wide definitions are stored in $ETC/$VERSION where $ETC is the configuration directory where &LIBGDA; is installed and $VERSION is &LIBGDA;'s major version.

Note that these locations can be changes using some properties of the global GdaConfig object.

## Authentication information management

When named data sources are used, &LIBGDA; can also store authentication information (username and password). This is accomplished using libsecret, or libgnome-keyring if available, or stored in an insecure way (along the DSN definition) if none of these libraries are available.