# Foreword about abstraction

&LIBGDA; aims both at making it easier to use databases and, for applications written using it, at making it easier to switch to a different database or to to be able to use different types of databases with a minimum or no code modifications. To achieve the 2nd goal, &LIBGDA; proposes an abstraction of most of database's engine features, which has to be understood to write portable code.

## Variables syntax in SQL

Each database engine has its own way of specifying variables (i.e. place holders) in SQL code (for example: `$<number>`, `:<name>`, `?<number>`, or `?`). &LIBGDA; has specified yet another format for variables which can be used with all the databases and which has the following advantages:

- allow to specify a name (and optionally a description)

- allow to specify a type, see gda_g_type_from_string()

- allow to specify if the variable can be NULL

For more information, refer to the GdaSqlParser object's documentation

## NULL handling when using variables

When using variables in statements (see Variables syntax in SQL) for example like

    SELECT * FROM users WHERE name = ##name::string::null;

, database engines will generally not handle correctly the case where a variable is valued to NULL. For instance this example would result in the code being executed as

    SELECT * FROM users WHERE name = NULL;

which would probably give no result, whereas the expected equivalent code would be

    SELECT * FROM users WHERE name IS NULL;

&LIBGDA; automatically handles theses cases and makes sure the `IS NULL` or `IS NOT NULL` constructions are used when necessary. It won't of course handle variable's NULL values when using other operators that equal or different, tough.

## SQL identifiers

The SQL standard has never defined if SQL identifiers (database object's names) have to be case sensitive or not, leaving that subject to each database engine implementation. All of them accept two syntaxes for SQL identifiers:

- the first is if the SQL identifier is surrounded by double quotes (sometimes backquotes or other characters), usually making the SQL identifier case sensitive (and also making it possible to use reserved SQL keywords as identifiers).

- the second is if it's not enquoted, usually meaning that the SQL identifier is not case sensitive.

Sometimes those rules don't apply or apply only partially. For example a MySQL server, depending on how it is configured and on what kind of OS it is running on, will have different sets of meanings for these notations.

As a result, &LIBGDA; has to be the least intrusive possible when the user wants to execute an SQL statement, and lets the database being accessed apply its own rules. However &LIBGDA; features meta data information retrieval (getting the list of tables, views,...) and there some representation conventions have been fixed, see the meta data section about SQL identifiers for more information.

The following diagram illustrates how &LIBGDA; handles SQL identifiers' representations depending where they are used: Diagram illustrating how &LIBGDA; handles SQL identifiers' representations

## Binary large objects (BLOBs)

Binary large objects (BLOBs) are potentially very big (several GigaBytes) pieces of binary data which databases can store. Because of their potential size, they are not manipulated like any other data, and are usually not transfered to the database engine at the same time as the SQL text is transfered: first a reference to a blob is created for an existing or a new blob, and then that reference is used, before or after the statement is being executed, depending on the database engine accessed, to get or set some parts of the blob.

&LIBGDA; makes its best to hide the complexity of this and most of the time blobs can be used like any other type of values with the following limitations:

- When getting a blob through a SELECT statement, a transaction will automatically be started if it's not already started, and usually the transaction (implicitly or explicitly) will be locked untill all the ressources associated to the fetched blobs are liberated (by calling g_object_unref() on the model).

- When fetching a blob value (using gda_data_model_get_value_at() for example), the blob itself is not fetched, only a reference to the blob is fetched, and one has to use the GdaBlobOp object embedded in a blob value to get the blob's contents.

Please consult each database provider's notes and limitations for database specific rules regarding BLOBs. Also have a look at the Blobs manipulation source code example.