GNOME Data Access 5 manual: Connections & commands

## Connections & commands

The Libgda library allows several connections to databases to be opened at once. Once a connection (manipulated through the GdaConnection object) has been created and is opened, it is able to proceed GdaStatement statements.

Each GdaStatement can only hold one SQL statement (such as SELECT, INSERT, CREATE TABLE, BEGIN, etc); statements can be grouped together into GdaBatch batches objects. There are two ways for creating a GdaStatement object:

- either by passing an SQL string to a parser (a GdaSqlParser).

  Libgda unifies the way variables (also known as "placeholders") are defined (because each database type has its own syntax for doing so); consult the GdaSqlParser object's documentation for a description of this syntax.

- by building it from its structure: see the GdaSqlStatement for reference. However keep in mind that this API is meant to be used primarily by database provider's implementations and for Libgda's internal usage. A more user friendly API will be added in the future.

The following schema illustrates how a statement is created and executed:

As each database implements its own SQL variant (all variants more or less close to the SQL92 or SQL99 standards), the Libgda library allows one to use either a generic SQL parser, or a parser provided by each database adapter (database provider), through the gda_connection_create_parser() method.

The following schema illustrates how a statement is executed:

## Description of the data model returned by gda_connection_get_meta_store_data()

The gda_connection_get_meta_store_data() method allows one to get the meta-data information about a database such as its structure (schema). The following table describes the actual data retrieved by each GdaConnectionMetaType type of request.

### GDA_CONNECTION_META_NAMESPACES

Lists the namespaces (also known as "schemas" by PostgreSQL).

Optional filter:

- "name" (G_TYPE_STRING): the name of the namespace

Columns of the returned data model:

Table 4.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | Namespace name
1 | G_TYPE_STRING | Namespace owner
2 | G_TYPE_BOOLEAN | TRUE if this namespace is reserved for internal use by the database

### GDA_CONNECTION_META_TYPES

Lists all the data types

Optional filter:

- "name" (G_TYPE_STRING): a type name

Columns of the returned data model:

Table 5.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | Type name
1 | G_TYPE_STRING | Type's associated GType type
2 | G_TYPE_STRING | Type's comments
3 | G_TYPE_STRING | Synonyms (separated by commas)

### GDA_CONNECTION_META_TABLES

Lists the tables which are "visible" without having to specify a schema name.

Optional filter:

- "name" (G_TYPE_STRING): the name of the table

Columns of the returned data model:

Table 6.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | Table's name
1 | G_TYPE_STRING | Namespace in which the table is
2 | G_TYPE_STRING | Table's complete name (ie. schema name + table name)
3 | G_TYPE_STRING | Table owner
4 | G_TYPE_STRING | Table's associated comments

### GDA_CONNECTION_META_VIEWS

Lists the views.

Optional filter:

- "name" (G_TYPE_STRING): the name of the view

Columns of the returned data model:

Table 7.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | View's name
1 | G_TYPE_STRING | Namespace in which the view is
2 | G_TYPE_STRING | View's complete name (if the view is not in the default namespace)
3 | G_TYPE_STRING | View owner
4 | G_TYPE_STRING | View's associated comments

### GDA_CONNECTION_META_FIELDS

Lists a table or view's fields

Mandatory filter:

- "name" (G_TYPE_STRING): the name of the table or view

Optional filter:

- "field_name" (G_TYPE_STRING): the name of a field

Columns of the returned data model:

Table 8.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | Field's name
1 | G_TYPE_STRING | Field's data type
2 | G_TYPE_STRING | Field's GType type
3 | G_TYPE_INT | Field's size
4 | G_TYPE_INT | Field's scale
5 | G_TYPE_BOOLEAN | TRUE if the field does not have a NOT NULL constraint
6 | G_TYPE_STRING | Field's default value
7 | G_TYPE_STRING | Extra attributes for the field as a comma separated values list of keywords (AUTO_INCREMENT)

### GDA_CONNECTION_META_INDEXES

Lists a table's associated indexes

Mandatory filter:

- "name" (G_TYPE_STRING): the name of the table

Optional filter:

- "index_name" (G_TYPE_STRING): the name of an index

Columns of the returned data model:

Table 9.

Column # | Type | Description
--- | --- | ---
0 | G_TYPE_STRING | Table's name
1 | G_TYPE_STRING | Namespace in which the table is
2 | G_TYPE_STRING | Index's name
3 | G_TYPE_STRING | Column's name involved in the index
4 | G_TYPE_INT | Sequence order
5 | G_TYPE_STRING | Index's type