Connections & commands

GdaConnection — A connection to a database
GdaSqlParser — SQL parser
GdaSqlBuilder — Factory object for statements
GdaStatement — Single SQL statement
GdaRepetitiveStatement — Execute the same statement several times with different values
GdaBatch — Multiple SQL statements grouped together.
GdaHolderContainer for a single GValue
GdaSet — Container for several values
GdaConnectionEventAny event which has occurred on a GdaConnection
GdaTransactionStatus — Keeps track of the transaction status of a connection
GdaXaTransaction — Distributed transaction manager
Description of the data model returned by gda_connection_get_meta_store_data()
GDA_CONNECTION_META_NAMESPACES
GDA_CONNECTION_META_TYPES
GDA_CONNECTION_META_TABLES
GDA_CONNECTION_META_VIEWS
GDA_CONNECTION_META_FIELDS
GDA_CONNECTION_META_INDEXES

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:

Statement execution illustrated

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:

Statement execution illustrated

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