Class Connection

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 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!

If gda_stmt changes or is destroyed, the the association will be lost and the connection will lose the reference it has on prepared_stmt.

If one of the statement fails, then none of the subsequent statement will be executed, and the method returns the list of #GObject created by the correct execution of the previous statements. If a transaction is required, then it should be started before calling this method.

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

GdaDbCatalog *catalog = gda_db_catalog_new (); g_object_set (catalog, "connection", cnc, NULL);

The equivalent SQL command is: DELETE FROM <table> WHERE <condition_column_name> = <condition_value>.

A simple example to remove a row in database.

GdaConnection *cnc;
//Open connection here

GError *error = NULL;

GValue *v_id = gda_value_new (G_TYPE_INT);
GValue *v_name = gda_value_new_from_string ("Aldibino Refinino", G_TYPE_STRING);

//The number 10 represents a primary key record in the table
g_value_set_int (v_id, 10);

//Delete a record with a specific ID in the col_id column
if (!gda_connection_delete_row_from_table (cnc, "TABLE_CONTACTS",
                                           "col_id", v_id,
                                           &error))
{
  g_error ("Could not delete row in table: %s\n",
           error && error->message ? error->message : "No detail");
}

//Delete a record with a specific NAME in the col_name column
if (!gda_connection_delete_row_from_table (cnc, "TABLE_CONTACTS",
                                           "col_name", v_name,
                                           &error))
{
  g_error ("Could not delete row in table: %s\n",
           error && error->message ? error->message : "No detail");
}

gda_value_free (v_id);
gda_value_free (v_name);

g_error_free (error);

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.

Warning: the cnc object may change the list if connection events occur

If no main context has been defined, then some function calls (for example connection opening) may block until the operation has finished.

If %NULL is returned, then no transaction has been associated with cnc

This is a convenience function, which creates an INSERT statement and executes it using the values provided. It internally relies on variables which makes it immune to SQL injection problems.

The equivalent SQL command is: INSERT INTO <table> (<column_name> [,...]) VALUES (<column_name> = <new_value> [,...]).

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

Note: destroy_func, needs to free the memory associated to data, if necessary.

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

Note: this function should not be called if gda_connection_internal_statement_executed() has already been called because a statement's execution was necessary to perform the action.

If the connection is already opened, then this function returns %TRUE immediately.

If the connection is already opened, then this function returns an error (with the %GDA_CONNECTION_ALREADY_OPENED_ERROR code).

Note: callback function will be called when processing events from the #GMainContext defined by gda_connection_set_main_context(), for example when there is a main loop for that main context.

GDA_SERVER_OPERATION_CREATE_TABLE_FKEY_FLAG: string with the table's name referenced an integer with the number pairs "local_field", "referenced_field" used in the reference Pairs of "local_field", "referenced_field" to use, must match the number specified above. a string with the action for ON DELETE; can be: "RESTRICT", "CASCADE", "NO ACTION", "SET NULL" and "SET DEFAULT". Example: "ON UPDATE CASCADE". a string with the action for ON UPDATE (see above).

Create a #GdaServerOperation object using an opened connection, taking three arguments, a column's name the column's GType and #GdaServerOperationCreateTableFlag flag, you need to finish the list using %NULL.

You'll be able to modify the #GdaServerOperation object to add custom options to the operation. When finished call #gda_server_operation_perform_create_table or #gda_server_provider_perform_operation in order to execute the operation.

This method may add double quotes (or other characters) around id: if id is a reserved SQL keyword (such as SELECT, INSERT, ...) if id contains non allowed characters such as spaces, or if it starts with a digit in any other event as necessary for cnc, depending on the the options passed when opening the cnc connection, and specifically the GDA_CONNECTION_OPTIONS_SQL_IDENTIFIERS_CASE_SENSITIVE option.

One can safely pass an already quoted id to this method, either with quoting characters allowed by cnc or using the double quote (") character.

If error is not %NULL and stop_on_error is %FALSE, then it may contain the last error which occurred.

For exemple if there is a GUI which needs to continue to handle events, then you can use this function to pass the default #GMainContext used for the UI refreshing, for example:

If context is %NULL, then potentially blocking operation will actually block any event from being processed while the blocking operation is being performed.

As stmt can, by design (and if not abused), contain only one SQL statement, the return object will either be: a #GdaDataSelect object (which is also a #GdaDataModel) if stmt is a SELECT statement (usually a GDA_SQL_STATEMENT_SELECT, see #GdaSqlStatementType) containing the results of the SELECT. The resulting data model is by default read only, but modifications can be enabled, see the #GdaDataSelect's documentation for more information. a #GdaSet for any other SQL statement which correctly executed. In this case (if the provider supports it), then the #GdaSet may contain value holders named: a (gint) #GdaHolder named "IMPACTED_ROWS" a (GObject) #GdaHolder named "EVENT" which contains a #GdaConnectionEvent

If last_insert_row is not %NULL and stmt is an INSERT statement, then it will contain a new #GdaSet object composed of value holders named "+<column number>" starting at column 0 which contain the actual inserted values. For example if a table is composed of an 'id' column which is auto incremented and a 'name' column then the execution of a "INSERT INTO mytable (name) VALUES ('joe')" query will return a #GdaSet with two holders: one with the '+0' ID which may for example contain 1 (note that its "name" property should be "id") one with the '+1' ID which will contain 'joe' (note that its "name" property should be "name") Note that the value pointer by last_insert_row may be %NULL after the function call if either the database provider does not support it, or if the last interted row could not be determined (for example with SQLite if the table in which the data is inserted has the WITHOUT ROWID optimization).

This method may fail with a %GDA_SERVER_PROVIDER_ERROR domain error (see the #GdaServerProviderError error codes).

Note1: If stmt is a SELECT statement which has some parameters and if params is %NULL, then the statement can't be executed and this method will return %NULL.

Note2: If stmt is a SELECT statement which has some parameters and if params is not %NULL but contains some invalid parameters, then the statement can't be executed and this method will return %NULL, unless the model_usage has the GDA_STATEMENT_MODEL_ALLOW_NOPARAM flag.

Note3: If stmt is a SELECT statement which has some parameters and if params is not %NULL but contains some invalid parameters and if model_usage has the GDA_STATEMENT_MODEL_ALLOW_NOPARAM flag, then the returned data model will contain no row but will have all the correct columns (even though some of the columns might report as GDA_TYPE_NULL). In this case, if (after this method call) any of params' parameters change then the resulting data model will re-run itself, see the GdaDataSelect's

auto-reset property for more information.

Note4: if model_usage does not contain the GDA_STATEMENT_MODEL_RANDOM_ACCESS or GDA_STATEMENT_MODEL_CURSOR_FORWARD flags, then the default will be to return a random access data model

Note5: If stmt is a SELECT statement which returns blob values (of type %GDA_TYPE_BLOB), then an implicit transaction will have been started by the database provider, and it's up to the caller to close the transaction (which will then be locked) once all the blob ressources have been liberated (when the returned data model is destroyed). See the section about

Binary large objects (BLOBs) for more information.

Also see the provider's limitations, and the

Advanced GdaDataSelect usage sections.

This function returns the number of rows affected by the execution of stmt, or -1 if an error occurred, or -2 if the connection's provider does not return the number of rows affected.

This function is just a convenience function around the gda_connection_statement_execute() function. See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

See gda_connection_statement_execute() form more information about last_insert_row.

This function returns a #GdaDataModel resulting from the SELECT statement, or %NULL if an error occurred.

This function is just a convenience function around the gda_connection_statement_execute() function.

See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

This function returns a #GdaDataModel resulting from the SELECT statement, or %NULL if an error occurred.

This function is just a convenience function around the gda_connection_statement_execute() function.

See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

This function is also useful to make sure stmt is fully understood by the database before actually executing it.

Note however that it is also possible that gda_connection_statement_prepare() fails when gda_connection_statement_execute() does not fail (this will usually be the case with statements such as because database usually don't allow variables to be used in place of a table name).

In order to keep the meta store's contents in a consistent state, the update process involves updating the contents of all the tables related to one where the contents change. For example the "_columns" table (which lists all the columns of a table) depends on the "_tables" table (which lists all the tables in a schema), so if a row is added, removed or modified in the "_tables", then the "_columns" table's contents needs to be updated as well regarding that row.

If context is %NULL, then the update process will simply overwrite any data that was present in all the meta store's tables with new (up to date) data even if nothing has changed, without having to build the tables' dependency tree. This is the recommended way of proceeding when dealing with a meta store which might be outdated.

On the other hand, if context is not %NULL, then a tree of the dependencies has to be built (depending on context) and only some parts of the meta store are updated following that dependencies tree. Specifying a context may be useful for example in the following situations: One knows that a database object has changed (for example a table created), and may use the context to request that only the information about that table be updated One is only interested in the list of views, and may request that only the information about views may be updated

When context is not %NULL, and contains specified SQL identifiers (for example the "table_name" of the "_tables" table), then each SQL identifier has to match the convention the #GdaMetaStore has adopted regarding case sensitivity, using gda_connection_quote_sql_identifier() or gda_meta_store_sql_identifier_quote().

see the meta data section about SQL identifiers for more information, and the documentation about the gda_sql_identifier_quote() function which will be most useful.

Note however that usually more information will be updated than strictly requested by the context argument.

For more information, see the Database structure section, and the Update the meta data about a table howto.

This is a convenience function, which creates an UPDATE statement and executes it using the values provided. It internally relies on variables which makes it immune to SQL injection problems.

The equivalent SQL command is: UPDATE <table> SET <column_name> = <new_value> [,...] WHERE <condition_column_name> = <condition_value>.