# Provider's notes

This section lists some notes and recommendations on how to use each database provider.

Before opening a connection with a database provider, one needs to specify the connection parameters. These parameters, even though some are shared by many database providers, are specific to each provider and the gda-sql or the gda-list-config tools can be used to obtain a complete list.

## For Oracle

The following arguments are used to connect to an Oracle database:

Argument name | Description | Required
--- | --- | ---
DB_NAME | Service name: global database name entered during database creation (it combines a database name with a domain name), can be left empty to connect to the default database. | No
HOST | Database server: host on which the database server is running | Yes
PORT | Port: database server port (leave this field empty for the default 1521 port) | No
SCHEMA | Schema: Name of the schema to use. If not specified, the schema defaults to that of the connected user. | No

Note however all the arguments above can be replaced by a single TNSNAME argument (see the "Oracle Database Net Services Administrator's Guide" for more information about defining connection identifiers).

Also refer to the Oracle's provider's limitations.

## For SQLite

The following arguments are used to connect to an SQLite database:

Argument name | Description | Required
--- | --- | ---
DB_NAME | Name of the database. This should be the name of the database file without the ".db" extension. However when opening a database, if a file named after the DB_NAME value exists then it is used (so beware, for example if DB_NAME is set to "mydb" and a file named "mydb" exists but is not an SQLite database, then an error will occur). Using the ":memory:" database name will result in a database residing purely in memory, the database ceases to exist as soon as the database connection is closed (every memory database is distinct from every other); refer to SQLite's in memory databases for more information. | Yes
APPEND_DB_EXTENSION | Defines if the '.db' extension need to be appended to the name of the database. Defaults to TRUE if not specified. | No
DB_DIR | The directory where the database file is; if not specified, the current working directory is used. | No
EXTRA_FUNCTIONS | If set to TRUE (or unspecified), then some extra functions defined by &LIBGDA; are added. The functions are: `gda_file_exists()`, `gda_hex_print()`, `gda_hex()`, `gda_rmdiacr()`, `gda_lower()` and `gda_upper()`; see below for more information about them. | No
EXTRA_COLLATIONS | If set to TRUE (or unspecified), then some extra collations defined by &LIBGDA; are added. They are: `LOCALE` (the strings are compared taking into account UTF8 sorting and the current locale) and `DCASE` (before comparison, all the diacritical signs (for example accents) are removed from the strings and they are converted to lower case). | No
REGEXP | If set to TRUE (or unspecified), then the `regexp()` and `regexp_match()` functions are defined. The `regexp()` function is used by SQL statement with a construct as "x REGEXP y", and the `regexp_match()` is more general. The default for this option is TRUE. See below for more information about this function. | No
FK | Defines if foreign keys are enforced, by default, they are. | No
EXTENSIONS | Defines if SQLite extensions are allowed to be loaded, using the load_extension() function, default is to deny loading extensions. | No

### The `gda_file_exists()` function

This function accepts a filename as argument, and returns 0 if the file with that filename does not exist, or 1 if it does.

### The `gda_hex_print()` function

This function accepts at most 2 arguments, in that order:

- a blob value

- a length (not mandatory)

It returns a string suitable to be printed (where all the non ascii characters are converted to the "\xyz" syntax where "xyz" is the decimal value of the character), limited to the specified length if any.

### The `gda_hex()` function

This function accepts at most 2 arguments, in that order:

- a blob value

- a length (not mandatory)

It returns a hex dump string of the blob value, limited to the specified length if any.

### The `gda_rmdiacr()` function

This function accepts at most 2 arguments, in that order:

- a string value

- a case conversion to do (not mandatory), as a string which must be 'upper' or 'lower'

It returns a string where all the diacritical signs (for example accents) from the input string, and optionally converts the string to upper or lower case if specified. This function takes into account the current locale and is useful to do some text search.

### The `gda_upper()` and `gda_lower()` functions

These function accept one string argument and convert it to upper or lower case, taking into account the locale (the standard SQLite `upper()` and `lower()` functions only operating on ASCII characters).

### The `regexp_match()` function

This function accepts at most 3 arguments, in that order:

- the string on which the regular expression will be applied

- the regular expression to apply

- the options (not mandatory)

The options are specified as a string where each character corresponds to a boolean flag (the presence of the character meaning the flag is set). They are:

- 'i': specifies a case insensitive matching

- 'm': specifies that the the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end of the string

- 'v': specifies that instead of returning 0 or 1 as a result for matching or non matching, the function returns the string which actually matches, or NULL if not match was found

This function is implemented using GLib's Perl-compatible regular expressions implementation: GRegex, itself based on the PCRE library.

Also refer to the SQLite's provider's limitations.

## For SQLCipher

The SQLCipher database provider allows one to connect to a database encrypted using the SQLCipher adaptations to the SQLite database. This section deals about how to manage the passphrase associated with a database file, please also consult the information provided by SQLCipher before attempting to use this database provider.

The first noticeable point is that any SQLite database file can be opened using the SQLCipher and will remain useable with the "standard" SQLite provider as long as it's not explicitely encrypted using a passphrase.

### How to create and encrypted database

To create an encrypted database, you can use the gda-sql and when prompted enter the requested passphrase, as:

    prompt> gda-sql-6.0 "SQLCipher://DB_NAME=testcrypt"
    Welcome to the GDA SQL console, version 5.1.0

    Type: .copyright to show usage and distribution terms
          .? for help with internal commands
          .q (or CTRL-D) to quit
          (the '.' can be replaced by a '\')
          or any query terminated by a semicolon

    Opening connection 'c0' for: SQLCipher://DB_NAME=testcrypt
    	Password for 'c0':

### How to encrypt an existing plaintext database to an encrypted database file

To encrypt an existing (SQLite) database, connect to the plaintext database using the SQLCipher provider and execute the following SQL commands (replace the passphrase with the requested passphrase):

    ATTACH DATABASE 'encrypted.db' AS encrypted KEY 'passphrase';
    SELECT sqlcipher_export('encrypted');
    DETACH DATABASE encrypted;

This step prevents opening the database file by the "standard" SQLite provider.

### How to change the passphrase of an encrypted database

To change an encrypted database's passphrase, open a connection to the database and enter the following SQL command (replace the passphrase with the requested new passphrase):

    PRAGMA rekey = 'passphrase';

### How to decrypt an existing database to a plaintext database

To decrypt an existing encrypted database, connect to the database using the SQLCipher provider and execute the following SQL commands (replace the passphrase with the requested passphrase):

    ATTACH DATABASE 'plaintext.db' AS plaintext KEY '';
    SELECT sqlcipher_export('plaintext');
    DETACH DATABASE plaintext;

This step allows opening the database file by the "standard" SQLite provider.

Also refer to the SQLite's provider's notes, and SQLCipher provider's limitations.

## For LDAP

### Authentication

For the LDAP authentification, one can provide the user name as a valid Distinguished Name (DN), or one can provide a user name which correponds to an entry in the LDAP tree; however the LDAP server usually requires a DN to authenticate. Providing a DN is usually inconvenient and people prefer to remember their user name rather than the associated DN. For this reason, if a user name is not provided, the LDAP provider tries the following:

- do an anonymous bind

- search a DN from the specified user name

- fetch the DN is it exists and is the only result

- close the anonymous connection

- bind using the found DN

However for an Active Directory server, this may fail if the server does not allow anonymous binding or searches, and one can use one of the following username syntaxes instead:

- username@DOMAIN

- DOMAIN\username

### Mapping to GdaDataModel

The LDAP provider maps LDAP searches to &LIBGDA;'s data models, with the following design choices:

- A data model column is created for each attibute the LDAP search returns, plus one column for the DN (Distinguished name), as the 1st column of each search; so if no attribute is requested, the resulting data model will only contain one column for the DN

- If not otherwise specified, the data type of each data model column is determined by the data type of the corresponding column attribute

- Multi valued attributes are by default handled as an invalid data, but it is possible to specify instead to report a NULL value, or an array in a CSV notation.

- For performances reasons, some data is cached (unless the "USE_CACHE" connection variable is set to FALSE). Cache files are in the users's home directory, as per the XDG Base Directory Specification

For more information, see the GdaDataModelLdap and the GdaLdapConnection objects.

## For JDBC

### How it works

JDBC (Java Database Connectivity) is a Java-based technology to access databases, not unlike ODBC. The JDBC provider runs a Java Virtual Machine in which the installed JDBC drivers are loaded. Connections are established and used through the JDBC driver, making an extensive use of the JNI (Java Native Interface) technology.

Any JDBC driver can be used, though only some of them have actually been tested. Some specializations have been made to adapt to some corner cases in the way some JDBC drivers are written or some specificities of some database engines.

Note that the JDBC drivers are not provided by Libgda and must be obtained and installed separately.

### JDBC drivers' location

JDBC drivers (".jar" files) are searched for in the following locations:

1. in each directory or JAR file in the `CLASSPATH` environment variable (if set)

2. in the `$HOME/.local/share/libgda/config` directory (or `$HOME/.libgda` if if exists and `$HOME/.local/share/libgda/config` if does not)

### Connection parameters

To connect to a database, the expected connection parameters are the ones required by the JDBC driver being used, which varies from driver to driver (for more information, refer to each driver's documentation). Thus &LIBGDA; expects only one argument named "URL" which it passes (without any modification) to the JDBC driver.

However, for some widely used servers (such as SqlServer), Libgda also accepts some parameters like for other database providers (like DB_NAME, HOST, ...). In this case one can either provide these parameters or provide the URL parameter (like for any JDBC provider) to specify a connection to open.

Also refer to the JDBC provider's limitations.