## GdaConnection GdaConnection — Management of connections to data sources |

## Synopsis

    enum        GdaConnectionOptions;
    GdaConnection* gda_connection_new           (GdaClient *client,
                                                 GdaServerProvider *provider,
                                                 const gchar *dsn,
                                                 const gchar *username,
                                                 const gchar *password,
                                                 GdaConnectionOptions options,
                                                 GError **error);
    gboolean    gda_connection_close            (GdaConnection *cnc);
    gboolean    gda_connection_is_open          (GdaConnection *cnc);
    GdaClient*  gda_connection_get_client       (GdaConnection *cnc);
    void        gda_connection_set_client       (GdaConnection *cnc,
                                                 GdaClient *client);
    GdaConnectionOptions gda_connection_get_options
                                                (GdaConnection *cnc);
    const gchar* gda_connection_get_server_version
                                                (GdaConnection *cnc);
    const gchar* gda_connection_get_database    (GdaConnection *cnc);
    const gchar* gda_connection_get_dsn         (GdaConnection *cnc);
    const gchar* gda_connection_get_cnc_string  (GdaConnection *cnc);
    const gchar* gda_connection_get_provider    (GdaConnection *cnc);
    const gchar* gda_connection_get_username    (GdaConnection *cnc);
    const gchar* gda_connection_get_password    (GdaConnection *cnc);
    void        gda_connection_add_event        (GdaConnection *cnc,
                                                 GdaConnectionEvent *error);
    void        gda_connection_add_event_string (GdaConnection *cnc,
                                                 const gchar *str,
                                                 ...);
    void        gda_connection_add_events_list  (GdaConnection *cnc,
                                                 GList *events_list);
    const GList* gda_connection_get_events      (GdaConnection *cnc);
    void        gda_connection_clear_events_list
                                                (GdaConnection *cnc);
    gboolean    gda_connection_change_database  (GdaConnection *cnc,
                                                 const gchar *name);
    gboolean    gda_connection_create_table     (GdaConnection *cnc,
                                                 const gchar *table_name,
                                                 const GList *attributes_list,
                                                 const GList *index_list);
    gboolean    gda_connection_drop_table       (GdaConnection *cnc,
                                                 const gchar *table_name);
    gboolean    gda_connection_create_index     (GdaConnection *cnc,
                                                 const GdaDataModelIndex *index,
                                                 const gchar *table_name);
    gboolean    gda_connection_drop_index       (GdaConnection *cnc,
                                                 const gchar *index_name,
                                                 gboolean primary_key,
                                                 const gchar *table_name);
    GList*      gda_connection_execute_command  (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);
    gchar*      gda_connection_get_last_insert_id
                                                (GdaConnection *cnc,
                                                 GdaDataModel *recset);
    GdaDataModel* gda_connection_execute_single_command
                                                (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);
    gint        gda_connection_execute_non_query
                                                (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);
    gboolean    gda_connection_begin_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);
    gboolean    gda_connection_commit_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);
    gboolean    gda_connection_rollback_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);
    GdaBlob*    gda_connection_create_blob      (GdaConnection *cnc);
    const GList* gda_connection_get_events      (GdaConnection *cnc);
    enum        GdaConnectionFeature;
    gboolean    gda_connection_supports         (GdaConnection *cnc,
                                                 GdaConnectionFeature feature);
    enum        GdaConnectionSchema;
    GdaDataModel* gda_connection_get_schema     (GdaConnection *cnc,
                                                 GdaConnectionSchema schema,
                                                 GdaParameterList *params);

## Description

The GdaConnection class offers access to all operations involving an opened connection to a database. GdaConnection objects are obtained via the GdaClient class.

Once obtained, applications can use GdaConnection to execute commands, run transactions, and get information about all objects stored in the underlying database.

## Details

### enum GdaConnectionOptions

    typedef enum {
    	GDA_CONNECTION_OPTIONS_READ_ONLY = 1 << 0,
    	GDA_CONNECTION_OPTIONS_DONT_SHARE = 2 << 0
    } GdaConnectionOptions;

### gda_connection_new ()

    GdaConnection* gda_connection_new           (GdaClient *client,
                                                 GdaServerProvider *provider,
                                                 const gchar *dsn,
                                                 const gchar *username,
                                                 const gchar *password,
                                                 GdaConnectionOptions options,
                                                 GError **error);

This function creates a new GdaConnection object. It is not intended to be used directly by applications (use gda_client_open_connection instead).

`client` : | a GdaClient object.
`provider` : | a GdaServerProvider object.
`dsn` : | GDA data source to connect to.
`username` : | user name to use to connect.
`password` : | password for `username`.
`options` : | options for the connection.
`error` : |
Returns : | a newly allocated GdaConnection object.

### gda_connection_close ()

    gboolean    gda_connection_close            (GdaConnection *cnc);

Closes the connection to the underlying data source. After calling this function, you should not use anymore the GdaConnection object, since it may have been destroyed.

`cnc` : | a GdaConnection object.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_is_open ()

    gboolean    gda_connection_is_open          (GdaConnection *cnc);

Checks whether a connection is open or not.

`cnc` : | a GdaConnection object.
Returns : | `TRUE` if the connection is open, `FALSE` if it's not.

### gda_connection_get_client ()

    GdaClient*  gda_connection_get_client       (GdaConnection *cnc);

Gets the GdaClient object associated with a connection. This is always the client that created the connection, as returned by gda_client_open_connection.

`cnc` : | a GdaConnection object.
Returns : | the client to which the connection belongs to.

### gda_connection_set_client ()

    void        gda_connection_set_client       (GdaConnection *cnc,
                                                 GdaClient *client);

Associates a GdaClient with this connection. This function is not intended to be called by applications.

`cnc` : | a GdaConnection object.
`client` : | a GdaClient object.

### gda_connection_get_options ()

    GdaConnectionOptions gda_connection_get_options
                                                (GdaConnection *cnc);

Gets the GdaConnectionOptions used to open this connection.

`cnc` : | a GdaConnection object.
Returns : | the connection options.

### gda_connection_get_server_version ()

    const gchar* gda_connection_get_server_version
                                                (GdaConnection *cnc);

Gets the version string of the underlying database server.

`cnc` : | a GdaConnection object.
Returns : | the server version string.

### gda_connection_get_database ()

    const gchar* gda_connection_get_database    (GdaConnection *cnc);

Gets the name of the currently active database in the given `GdaConnection`.

`cnc` : | A GdaConnection object.
Returns : | the name of the current database.

### gda_connection_get_dsn ()

    const gchar* gda_connection_get_dsn         (GdaConnection *cnc);

`cnc` : | a GdaConnection object
Returns : | the data source name the connection object is connected to.

### gda_connection_get_cnc_string ()

    const gchar* gda_connection_get_cnc_string  (GdaConnection *cnc);

Gets the connection string used to open this connection.

The connection string is the string sent over to the underlying database provider, which describes the parameters to be used to open a connection on the underlying data source.

`cnc` : | a GdaConnection object.
Returns : | the connection string used when opening the connection.

### gda_connection_get_provider ()

    const gchar* gda_connection_get_provider    (GdaConnection *cnc);

Gets the provider id that this connection is connected to.

`cnc` : | a GdaConnection object.
Returns : | the provider ID used to open this connection.

### gda_connection_get_username ()

    const gchar* gda_connection_get_username    (GdaConnection *cnc);

Gets the user name used to open this connection.

`cnc` : | a GdaConnection object.
Returns : | the user name.

### gda_connection_get_password ()

    const gchar* gda_connection_get_password    (GdaConnection *cnc);

Gets the password used to open this connection.

`cnc` : | a GdaConnection object.
Returns : | the password.

### gda_connection_add_event ()

    void        gda_connection_add_event        (GdaConnection *cnc,
                                                 GdaConnectionEvent *error);

Adds an event to the given connection. This function is usually called by providers, to inform clients of events that happened during some operation.

As soon as a provider (or a client, it does not matter) calls this function with an `event` object which is an error, the connection object (and the associated GdaClient object) emits the "error" signal, to which clients can connect to be informed of events.

WARNING: the reference to the `event` object is stolen by this function!

`cnc` : | a GdaConnection object.
`error` : |

### gda_connection_add_event_string ()

    void        gda_connection_add_event_string (GdaConnection *cnc,
                                                 const gchar *str,
                                                 ...);

Adds a new error to the given connection object. This is just a convenience function that simply creates a GdaConnectionEvent and then calls gda_server_connection_add_error.

`cnc` : | a GdaServerConnection object.
`str` : | a format string (see the printf(3) documentation).
`...` : | the arguments to insert in the error message.

### gda_connection_add_events_list ()

    void        gda_connection_add_events_list  (GdaConnection *cnc,
                                                 GList *events_list);

This is just another convenience function which lets you add a list of GdaConnectionEvent's to the given connection.* As with gda_connection_add_event and gda_connection_add_event_string, this function makes the connection object emit the "error" signal for each error event.

`events_list` is copied to an internal list and freed.

`cnc` : | a GdaConnection object.
`events_list` : | a list of GdaConnectionEvent.

### gda_connection_get_events ()

    const GList* gda_connection_get_events      (GdaConnection *cnc);

Retrieves a list of the last errors ocurred in the connection. You can make a copy of the list using gda_connection_event_list_copy.

`cnc` : | a GdaConnection.
Returns : | a GList of GdaConnectionEvent.

### gda_connection_clear_events_list ()

    void        gda_connection_clear_events_list
                                                (GdaConnection *cnc);

This function lets you clear the list of GdaConnectionEvent's of the given connection.

`cnc` : | a GdaConnection object.

### gda_connection_change_database ()

    gboolean    gda_connection_change_database  (GdaConnection *cnc,
                                                 const gchar *name);

Changes the current database for the given connection. This operation is not available in all providers.

`cnc` : | a GdaConnection object.
`name` : | name of database to switch to.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_create_table ()

    gboolean    gda_connection_create_table     (GdaConnection *cnc,
                                                 const gchar *table_name,
                                                 const GList *attributes_list,
                                                 const GList *index_list);

Creates a table on the given connection from the specified set of fields. In case of none or single column index only, the various index fields can be set in GdaColumn and `index_list` can be set to NULL. Index related values set in GdaColumn should not overlap settings in `index_list`. A table can only have one Primary Key for instance. Either set it in GdaColumn that is part of `attributes_list` or in GdaColumnIndex that is part of `index_list`.

`cnc` : | a GdaConnection object.
`table_name` : | name of the table to be created.
`attributes_list` : | list of GdaColumn for all fields in the table.
`index_list` : | list of GdaDataModelIndex of all (multi column) index entries of a table.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_drop_table ()

    gboolean    gda_connection_drop_table       (GdaConnection *cnc,
                                                 const gchar *table_name);

Drops a table from the database.

`cnc` : | a GdaConnection object.
`table_name` : | name of the table to be removed.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_create_index ()

    gboolean    gda_connection_create_index     (GdaConnection *cnc,
                                                 const GdaDataModelIndex *index,
                                                 const gchar *table_name);

Creates an index for a given table on the given connection from the specified set of fields.

`cnc` : | a GdaConnection object.
`index` : | a GdaDataModelIndex object containing all index details.
`table_name` : | name of the table to create index for.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_drop_index ()

    gboolean    gda_connection_drop_index       (GdaConnection *cnc,
                                                 const gchar *index_name,
                                                 gboolean primary_key,
                                                 const gchar *table_name);

Drops an index from a table from the database. Some data providers do not allow to assign a name to a PRIMARY KEY. To be able to drop a PRIMARY KEY, the parameter `primary_key` can be set to `TRUE`.

`cnc` : | a GdaConnection object.
`index_name` : | name of the index to be removed.
`primary_key` : | if the index is a primary key.
`table_name` : | name of the table of index to be removed from.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_connection_execute_command ()

    GList*      gda_connection_execute_command  (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);

Executes a command on the underlying data source.

This function provides the way to send several commands at once to the data source being accessed by the given GdaConnection object. The GdaCommand specified can contain a list of commands in its "text" property (usually a set of SQL commands separated by ';').

The return value is a GList of GdaDataModel's, which you are responsible to free when not needed anymore.

`cnc` : | a GdaConnection object.
`cmd` : | a GdaCommand.
`params` : | parameter list.
`error` : | a place to store an error, or `NULL`
Returns : | a list of GdaDataModel's, as returned by the underlying provider.

### gda_connection_get_last_insert_id ()

    gchar*      gda_connection_get_last_insert_id
                                                (GdaConnection *cnc,
                                                 GdaDataModel *recset);

Retrieve from the given GdaConnection the ID of the last inserted row. A connection must be specified, and, optionally, a result set. If not NULL, the underlying provider should try to get the last insert ID for the given result set.

`cnc` : | a GdaConnection object.
`recset` : | recordset.
Returns : | a string representing the ID of the last inserted row, or NULL if an error occurred or no row has been inserted. It is the caller's reponsibility to free the returned string.

### gda_connection_execute_single_command ()

    GdaDataModel* gda_connection_execute_single_command
                                                (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);

Executes a single command on the given connection.

This function lets you retrieve a simple data model from the underlying difference, instead of having to retrieve a list of them, as is the case with gda_connection_execute_command.

`cnc` : | a GdaConnection object.
`cmd` : | a GdaCommand.
`params` : | parameter list.
`error` : | a place to store an error, or `NULL`
Returns : | a GdaDataModel containing the data returned by the data source, or `NULL` on error.

### gda_connection_execute_non_query ()

    gint        gda_connection_execute_non_query
                                                (GdaConnection *cnc,
                                                 GdaCommand *cmd,
                                                 GdaParameterList *params,
                                                 GError **error);

Executes a single command on the underlying database, and gets the number of rows affected.

`cnc` : | a GdaConnection object.
`cmd` : | a GdaCommand.
`params` : | parameter list.
`error` : |
Returns : | the number of affected rows by the executed command, or -1 on error.

### gda_connection_begin_transaction ()

    gboolean    gda_connection_begin_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);

Starts a transaction on the data source, identified by the `xaction` parameter.

Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the gda_connection_supports function.

`cnc` : | a GdaConnection object.
`xaction` : | a GdaTransaction object.
Returns : | `TRUE` if the transaction was started successfully, `FALSE` otherwise.

### gda_connection_commit_transaction ()

    gboolean    gda_connection_commit_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);

Commits the given transaction to the backend database. You need to do `gda_connection_begin_transaction()` first.

`cnc` : | a GdaConnection object.
`xaction` : | a GdaTransaction object.
Returns : | `TRUE` if the transaction was finished successfully, `FALSE` otherwise.

### gda_connection_rollback_transaction ()

    gboolean    gda_connection_rollback_transaction
                                                (GdaConnection *cnc,
                                                 GdaTransaction *xaction);

Rollbacks the given transaction. This means that all changes made to the underlying data source since the last call to gda_connection_begin_transaction or gda_connection_commit_transaction will be discarded.

`cnc` : | a GdaConnection object.
`xaction` : | a GdaTransaction object.
Returns : | `TRUE` if the operation was successful, `FALSE` otherwise.

### gda_connection_create_blob ()

    GdaBlob*    gda_connection_create_blob      (GdaConnection *cnc);

Fetch an existing BLOB (Binary Large OBject) using its SQL ID.

`cnc` : | a GdaConnection object.
Returns : | `FALSE` if the database does not support BLOBs. `TRUE` otherwise and the GdaBlob is created and ready to be used.

### gda_connection_get_events ()

    const GList* gda_connection_get_events      (GdaConnection *cnc);

Retrieves a list of the last errors ocurred in the connection. You can make a copy of the list using gda_connection_event_list_copy.

`cnc` : | a GdaConnection.
Returns : | a GList of GdaConnectionEvent.

### enum GdaConnectionFeature

    typedef enum {
    	GDA_CONNECTION_FEATURE_AGGREGATES,
    	GDA_CONNECTION_FEATURE_BLOBS,
    	GDA_CONNECTION_FEATURE_INDEXES,
    	GDA_CONNECTION_FEATURE_INHERITANCE,
    	GDA_CONNECTION_FEATURE_NAMESPACES,
    	GDA_CONNECTION_FEATURE_PROCEDURES,
    	GDA_CONNECTION_FEATURE_SEQUENCES,
    	GDA_CONNECTION_FEATURE_SQL,
    	GDA_CONNECTION_FEATURE_TRANSACTIONS,
    	GDA_CONNECTION_FEATURE_TRIGGERS,
    	GDA_CONNECTION_FEATURE_UPDATABLE_CURSOR,
    	GDA_CONNECTION_FEATURE_USERS,
    	GDA_CONNECTION_FEATURE_VIEWS,
    	GDA_CONNECTION_FEATURE_XML_QUERIES
    } GdaConnectionFeature;

### gda_connection_supports ()

    gboolean    gda_connection_supports         (GdaConnection *cnc,
                                                 GdaConnectionFeature feature);

Asks the underlying provider for if a specific feature is supported.

`cnc` : | a GdaConnection object.
`feature` : | feature to ask for.
Returns : | `TRUE` if the provider supports it, `FALSE` if not.

### enum GdaConnectionSchema

    typedef enum {
    	GDA_CONNECTION_SCHEMA_AGGREGATES,
    	GDA_CONNECTION_SCHEMA_DATABASES,
    	GDA_CONNECTION_SCHEMA_FIELDS,
    	GDA_CONNECTION_SCHEMA_INDEXES,
    	GDA_CONNECTION_SCHEMA_LANGUAGES,
    	GDA_CONNECTION_SCHEMA_NAMESPACES,
    	GDA_CONNECTION_SCHEMA_PARENT_TABLES,
    	GDA_CONNECTION_SCHEMA_PROCEDURES,
    	GDA_CONNECTION_SCHEMA_SEQUENCES,
    	GDA_CONNECTION_SCHEMA_TABLES,
    	GDA_CONNECTION_SCHEMA_TRIGGERS,
    	GDA_CONNECTION_SCHEMA_TYPES,
    	GDA_CONNECTION_SCHEMA_USERS,
    	GDA_CONNECTION_SCHEMA_VIEWS
    } GdaConnectionSchema;

### gda_connection_get_schema ()

    GdaDataModel* gda_connection_get_schema     (GdaConnection *cnc,
                                                 GdaConnectionSchema schema,
                                                 GdaParameterList *params);

Asks the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: `schema`, which specifies the specific schema required, and `params`, which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type.

`cnc` : | a GdaConnection object.
`schema` : | database schema to get.
`params` : | parameter list.
Returns : | a GdaDataModel containing the data required. The caller is responsible of freeing the returned model.