GdaMetaStore: GNOME Data Access 5 manual

## GdaMetaStore GdaMetaStore — Dictionary object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaMetaStore * | gda_meta_store_new ()
GdaMetaStore * | gda_meta_store_new_with_file ()
gint | gda_meta_store_get_version ()
gchar * | gda_meta_store_sql_identifier_quote ()
GdaDataModel * | gda_meta_store_extract ()
GdaDataModel * | gda_meta_store_extract_v ()
GdaMetaStruct * | gda_meta_store_schema_get_structure ()
gboolean | gda_meta_store_get_attribute_value ()
gboolean | gda_meta_store_set_attribute_value ()
gboolean | gda_meta_store_schema_add_custom_object ()
GdaConnection * | gda_meta_store_get_internal_connection ()
gboolean | gda_meta_store_declare_foreign_key ()
gboolean | gda_meta_store_undeclare_foreign_key ()
GType | gda_meta_context_get_type ()
GdaMetaContext * | gda_meta_context_new ()
GdaMetaContext * | gda_meta_context_copy ()
void | gda_meta_context_set_table ()
const gchar * | gda_meta_context_get_table ()
void | gda_meta_context_set_column ()
void | gda_meta_context_set_columns ()
void | gda_meta_context_free ()

## Properties

gchar * | catalog | Write / Construct Only
GdaConnection * | cnc | Read / Write / Construct Only
gchar * | cnc-string | Write / Construct Only
gchar * | schema | Write / Construct Only

## Signals

void | meta-changed | Run First
void | meta-reset | Run First
GError* | suggest-update | Run Last

## Types and Values

| GdaMetaStore
enum | GdaMetaStoreError
| GdaMetaStoreChange
enum | GdaMetaStoreChangeType
| GdaMetaContext

## Object Hierarchy

        GObject
        ╰── GdaMetaStore

## Description

Previous versions of Libgda relied on an XML based file to store dictionary information, such as the database's schema (tables, views, etc) and various other information. The problems were that it was difficult for an application to integrate its own data into the dictionary and that there were some performances problems as the XML file needed to be parsed (and converted into its own in-memory structure) before any data could be read out of it.

The new dictionary now relies on a database structure to store its data (see the

database schema section for a detailed description). The actual database can be a

single file (using an SQLite database), an entirely in memory database (also using an SQLite database), or a more conventional backend such as a PostgreSQL database for a shared dictionary on a server.

The GdaMetaStore object is thread safe.

## Functions

### gda_meta_store_new ()

    GdaMetaStore *
    gda_meta_store_new (const gchar *cnc_string);

Create a new GdaMetaStore object.

#### Parameters

cnc_string | a connection string, or `NULL` for an in-memory internal database. | [allow-none]

#### Returns

the newly created object, or `NULL` if an error occurred.

[transfer full]

### gda_meta_store_new_with_file ()

    GdaMetaStore *
    gda_meta_store_new_with_file (const gchar *file_name);

Create a new GdaMetaStore object using `file_name` as its internal database

#### Parameters

file_name | a file name |

#### Returns

the newly created object, or `NULL` if an error occurred.

[transfer full]

### gda_meta_store_get_version ()

    gint
    gda_meta_store_get_version (GdaMetaStore *store);

Get `store` 's internal schema's version

#### Parameters

store | a GdaMetaStore object |

#### Returns

the version (incremented each time the schema changes, backward compatible)

### gda_meta_store_sql_identifier_quote ()

    gchar *
    gda_meta_store_sql_identifier_quote (const gchar *id,
                                         GdaConnection *cnc);

Use this method to get a correctly quoted (if necessary) SQL identifier which can be used to retrieve or filter information in a GdaMetaStore which stores meta data about `cnc` .

The returned SQL identifier can be used in conjunction with `gda_connection_update_meta_store()`, `gda_connection_get_meta_store_data()`, `gda_connection_get_meta_store_data_v()` and `gda_meta_store_extract()`.

#### Parameters

id | an SQL identifier |
cnc | a GdaConnection |

#### Returns

a new string, to free with `g_free()` once not needed anymore.

[transfer full]

Since: 4.0.3

### gda_meta_store_extract ()

    GdaDataModel *
    gda_meta_store_extract (GdaMetaStore *store,
                            const gchar *select_sql,
                            GError **error,
                            ...);

Extracts some data stored in `store` using a custom SELECT query. If the `select_sql` filter involves SQL identifiers (such as table or column names), then the values should have been adapted using `gda_meta_store_sql_identifier_quote()`.

For more information about SQL identifiers are represented in `store` , see the

meta data section about SQL identifiers.

[skip]

#### Parameters

store | a GdaMetaStore object |
select_sql | a SELECT statement |
error | a place to store errors, or `NULL`. | [allow-none]
... | a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentioned in `select_sql` . If there is no variable then this part can be omitted. |

#### Returns

a new GdaDataModel, or `NULL` if an error occurred.

[transfer full]

### gda_meta_store_extract_v ()

    GdaDataModel *
    gda_meta_store_extract_v (GdaMetaStore *store,
                              const gchar *select_sql,
                              GHashTable *vars,
                              GError **error);

Extracts some data stored in `store` using a custom SELECT query. If the `select_sql` filter involves SQL identifiers (such as table or column names), then the values should have been adapted using `gda_meta_store_sql_identifier_quote()`.

For more information about SQL identifiers are represented in `store` , see the

meta data section about SQL identifiers.

#### Parameters

store | a GdaMetaStore object |
select_sql | a SELECT statement |
vars | a hash table with all variables names as keys and GValue* as value, representing values for all the variables mentioned in `select_sql` . If there is no variable then this part can be omitted. | [element-type utf8 GObject.Value][allow-none]
error | a place to store errors, or `NULL` |

#### Returns

a new GdaDataModel, or `NULL` if an error occurred.

[transfer full]

Since: 4.2.6

### gda_meta_store_schema_get_structure ()

    GdaMetaStruct *
    gda_meta_store_schema_get_structure (GdaMetaStore *store,
                                         GError **error);

Creates a new GdaMetaStruct object representing `store` 's internal database structure.

#### Parameters

store | a GdaMetaStore object |
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

a new GdaMetaStruct object, or `NULL` if an error occurred.

[transfer full]

### gda_meta_store_get_attribute_value ()

    gboolean
    gda_meta_store_get_attribute_value (GdaMetaStore *store,
                                        const gchar *att_name,
                                        gchar **att_value,
                                        GError **error);

The GdaMetaStore object maintains a list of (name,value) attributes (attributes names starting with a '_' character are for internal use only and cannot be altered). This method and the `gda_meta_store_set_attribute_value()` method allows the user to add, set or remove attributes specific to their usage.

This method allows to get the value of a attribute stored in `store` . The returned attribute value is placed at `att_value` , the caller is responsible for free that string.

If there is no attribute named `att_name` then `att_value` is set to `NULL` and `error` will contain the GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR error code, and FALSE is returned.

#### Parameters

store | a GdaMetaStore object |
att_name | name of the attribute to get |
att_value | the place to store the attribute value. | [out]
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

TRUE if no error occurred

### gda_meta_store_set_attribute_value ()

    gboolean
    gda_meta_store_set_attribute_value (GdaMetaStore *store,
                                        const gchar *att_name,
                                        const gchar *att_value,
                                        GError **error);

Set the value of the attribute named `att_name` to `att_value` ; see `gda_meta_store_get_attribute_value()` for more information.

#### Parameters

store | a GdaMetaStore object |
att_name | name of the attribute to set |
att_value | value of the attribute to set, or `NULL` to unset the attribute. | [allow-none]
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

TRUE if no error occurred

### gda_meta_store_schema_add_custom_object ()

    gboolean
    gda_meta_store_schema_add_custom_object
                                   (GdaMetaStore *store,
                                    const gchar *xml_description,
                                    GError **error);

The internal database used by `store` can be 'augmented' with some user-defined database objects (such as tables or views). This method allows one to add a new database object.

If the internal database already contains the object, then:

- if the object is equal to the provided description then TRUE is returned

- if the object exists but differs from the provided description, then FALSE is returned, with the GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR error code

The `xml_description` defines the table of view's definition, for example:

    <table name="mytable">
        <column name="id" pkey="TRUE"/>
        <column name="value"/>
    </table>

The partial DTD for this XML description of the object to add is the following (the top node must be a <table> or a <view>):

    <!ELEMENT table (column*,check*,fkey*,unique*)>
    <!ATTLIST table
              name NMTOKEN #REQUIRED>

    <!ELEMENT column EMPTY>
    <!ATTLIST column
              name NMTOKEN #REQUIRED
              type CDATA #IMPLIED
              pkey (TRUE|FALSE) #IMPLIED
              autoinc (TRUE|FALSE) #IMPLIED
              nullok (TRUE|FALSE) #IMPLIED>

    <!ELEMENT check (#PCDATA)>

    <!ELEMENT fkey (part+)>
    <!ATTLIST fkey
              ref_table NMTOKEN #REQUIRED>

    <!ELEMENT part EMPTY>
    <!ATTLIST part
              column NMTOKEN #IMPLIED
              ref_column NMTOKEN #IMPLIED>

    <!ELEMENT unique (column)>

    <!ELEMENT view (definition)>
    <!ATTLIST view
              name NMTOKEN #REQUIRED
              descr CDATA #IMPLIED>

    <!ELEMENT definition (#PCDATA)>

#### Parameters

store | a GdaMetaStore object |
xml_description | an XML description of the table or view to add to `store` |
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

TRUE if the new object has successfully been added

### gda_meta_store_get_internal_connection ()

    GdaConnection *
    gda_meta_store_get_internal_connection
                                   (GdaMetaStore *store);

Get a pointer to the GdaConnection object internally used by `store` to store its contents.

The returned connection can be used to access some other data than the one managed by `store` itself. The returned object is not owned by the caller (if you need to keep it, then use `g_object_ref()`). Do not close the connection.

#### Parameters

store | a GdaMetaStore object |

#### Returns

a GdaConnection, or `NULL`.

[transfer none]

### gda_meta_store_declare_foreign_key ()

    gboolean
    gda_meta_store_declare_foreign_key (GdaMetaStore *store,
                                        GdaMetaStruct *mstruct,
                                        const gchar *fk_name,
                                        const gchar *catalog,
                                        const gchar *schema,
                                        const gchar *table,
                                        const gchar *ref_catalog,
                                        const gchar *ref_schema,
                                        const gchar *ref_table,
                                        guint nb_cols,
                                        gchar **colnames,
                                        gchar **ref_colnames,
                                        GError **error);

Defines a new declared foreign key into `store` . If another declared foreign key is already defined between the two tables and with the same name, then it is first removed.

This method begins a transaction if possible (ie. none is already started), and if it can't, then if there is an error, the job may be partially done.

A check is always performed to make sure all the database objects actually exist and returns an error if not. The check is performed using `mstruct` if it's not `NULL` (in this case only the tables already represented in `mstruct` will be considered, in other words: `mstruct` will not be modified), and using an internal GdaMetaStruct is `NULL`.

The `catalog` , `schema` , `table` , `ref_catalog` , `ref_schema` and `ref_table` must follow the SQL identifiers naming convention, see the SQL identifiers section. The same convention needs to be respected for the strings in `conames` and `ref_colnames` .

If `catalog` is not `NULL`, then `schema` must also be not `NULL` (the same restriction applies to `ref_catalog` and `ref_schema` ).

#### Parameters

store | a GdaMetaStore |
mstruct | a GdaMetaStruct, or `NULL`. | [allow-none]
fk_name | the name of the foreign key to declare |
catalog | the catalog in which the table (for which the foreign key is for) is, or `NULL`. | [allow-none]
schema | the schema in which the table (for which the foreign key is for) is, or `NULL`. | [allow-none]
table | the name of the table (for which the foreign key is for) |
ref_catalog | the catalog in which the referenced table is, or `NULL`. | [allow-none]
ref_schema | the schema in which the referenced table is, or `NULL`. | [allow-none]
ref_table | the name of the referenced table |
nb_cols | the number of columns involved (>0) |
colnames | an array of column names from the table for which the foreign key is for. | [array length=nb_cols]
ref_colnames | an array of column names from the referenced table. | [array length=nb_cols]
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

`TRUE` if no error occurred

Since: 4.2.4

### gda_meta_store_undeclare_foreign_key ()

    gboolean
    gda_meta_store_undeclare_foreign_key (GdaMetaStore *store,
                                          GdaMetaStruct *mstruct,
                                          const gchar *fk_name,
                                          const gchar *catalog,
                                          const gchar *schema,
                                          const gchar *table,
                                          const gchar *ref_catalog,
                                          const gchar *ref_schema,
                                          const gchar *ref_table,
                                          GError **error);

Removes a declared foreign key from `store` .

This method begins a transaction if possible (ie. none is already started), and if it can't, then if there is an error, the job may be partially done.

A check is always performed to make sure all the database objects actually exist and returns an error if not. The check is performed using `mstruct` if it's not `NULL` (in this case only the tables already represented in `mstruct` will be considered, in other words: `mstruct` will not be modified), and using an internal GdaMetaStruct is `NULL`.

See `gda_meta_store_declare_foreign_key()` for more information anout the `catalog` , `schema` , `name` , `ref_catalog` , `ref_schema` and `ref_name` arguments.

#### Parameters

store | a GdaMetaStore |
mstruct | a GdaMetaStruct, or `NULL`. | [allow-none]
fk_name | the name of the foreign key to declare |
catalog | the catalog in which the table (for which the foreign key is for) is, or `NULL`. | [allow-none]
schema | the schema in which the table (for which the foreign key is for) is, or `NULL`. | [allow-none]
table | the name of the table (for which the foreign key is for) |
ref_catalog | the catalog in which the referenced table is, or `NULL`. | [allow-none]
ref_schema | the schema in which the referenced table is, or `NULL`. | [allow-none]
ref_table | the name of the referenced table |
error | a place to store errors, or `NULL`. | [allow-none]

#### Returns

`TRUE` if no error occurred

Since: 4.2.4

### gda_meta_context_get_type ()

    GType
    gda_meta_context_get_type (void);

### gda_meta_context_new ()

    GdaMetaContext *
    gda_meta_context_new (void);

Creates a new GdaMetaContext struct with a GHashTable to store column/value pairs.

Return: (transfer full): a new GdaMetaContext struct with a new created hash to store column name/value pairs.

Since: 5.2

### gda_meta_context_copy ()

    GdaMetaContext *
    gda_meta_context_copy (GdaMetaContext *ctx);

Copy constructor.

#### Parameters

ctx | a GdaMetaContext |

#### Returns

a new GdaMetaContext

Since: 5.2

### gda_meta_context_set_table ()

    void
    gda_meta_context_set_table (GdaMetaContext *ctx,
                                const gchar *table);

Set table's name to use in the context. The table is one of database schema used to store meta information about the database. Use "_tables" to update meta information about database's tables.

#### Parameters

ctx | a GdaMetaContext struct to set table to |
table | a string with the table's name to use in context |

Since: 5.2

### gda_meta_context_get_table ()

    const gchar *
    gda_meta_context_get_table (GdaMetaContext *ctx);

Get table's name to used in the context.

Return: (transfer none): A string with the table's name used in the context.

#### Parameters

ctx | a GdaMetaContext struct to get table's name from |

Since: 5.2

### gda_meta_context_set_column ()

    void
    gda_meta_context_set_column (GdaMetaContext *ctx,
                                 const gchar *column,
                                 const GValue *value,
                                 GdaConnection *cnc);

Sets a new column/value pair to the given context `ctx` . Column, must be a column in the given table's name setted by `gda_meta_context_set_table()` (a table in the database schema). If the given `column` already exists it's value is overwrited.

Column's name and value is copied and destroyed when gda_meta_context_free is called.

#### Parameters

ctx | a GdaMetaContext struct to add column/value pais to |
column | the column's name. | [transfer none]
value | the column's value. | [transfer none]
cnc | a GdaConnection to be used when identifier are normalized, or NULL. | [allow-none]

Since: 5.2

### gda_meta_context_set_columns ()

    void
    gda_meta_context_set_columns (GdaMetaContext *ctx,
                                  GHashTable *columns,
                                  GdaConnection *cnc);

Set columns to use in the context. The GHashTable use column's name as key and a GValue as value, to represent its value.

`columns` incements its reference counting. Is recommended to use gda_meta_context_free in order to free them.

#### Parameters

ctx | a GdaMetaContext struct to set colums to |
columns | a GHashTable with the table's columns' name and their values to use in context. | [element-type utf8 GObject.Value]
cnc | a GdaConnection to used to normalize identifiers quoting, or NULL. | [allow-none]

Since: 5.2

### gda_meta_context_free ()

    void
    gda_meta_context_free (GdaMetaContext *ctx);

Frees any resources taken by `ctx` struct. If `ctx` is `NULL`, then nothing happens.

#### Parameters

ctx | a GdaMetaContext struct to free. | [allow-none]

Since: 5.2

## Types and Values

### GdaMetaStore

    typedef struct _GdaMetaStore GdaMetaStore;

### enum GdaMetaStoreError

#### Members

GDA_META_STORE_INCORRECT_SCHEMA_ERROR |  |
GDA_META_STORE_UNSUPPORTED_PROVIDER_ERROR |  |
GDA_META_STORE_INTERNAL_ERROR |  |
GDA_META_STORE_META_CONTEXT_ERROR |  |
GDA_META_STORE_MODIFY_CONTENTS_ERROR |  |
GDA_META_STORE_EXTRACT_SQL_ERROR |  |
GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR |  |
GDA_META_STORE_ATTRIBUTE_ERROR |  |
GDA_META_STORE_SCHEMA_OBJECT_NOT_FOUND_ERROR |  |
GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR |  |
GDA_META_STORE_SCHEMA_OBJECT_DESCR_ERROR |  |
GDA_META_STORE_TRANSACTION_ALREADY_STARTED_ERROR |  |

### GdaMetaStoreChange

    typedef struct {
    	/* change general information */
    	GdaMetaStoreChangeType  c_type;
    	gchar                  *table_name;
    	GHashTable             *keys; /* key = ('+' or '-') and a column position in @table (string) starting at 0,
    	                               * value = a GValue pointer */
    } GdaMetaStoreChange;

#### Members

GdaMetaStoreChangeType `c_type`; |  |
gchar *`table_name`; |  |
GHashTable *`keys`; | . | [element-type utf8 GObject.Value]

### enum GdaMetaStoreChangeType

#### Members

GDA_META_STORE_ADD |  |
GDA_META_STORE_REMOVE |  |
GDA_META_STORE_MODIFY |  |

### GdaMetaContext

    typedef struct {
    	gchar                  *table_name;
    	gint                    size;
    	gchar                 **column_names;
    	GValue                **column_values;
    	GHashTable             *columns;/* Added since 5.2 */
    } GdaMetaContext;

The GdaMetaContext represents a meta data modification context: the how when used with `gda_meta_store_modify_with_context()`, and the what when used with `gda_connection_update_meta_store()`.

To create a new GdaMetaContext use gda_meta_context_new.

To add a new column/value pair use gda_meta_context_add_column.

To free a GdaMetaContext, created by gda_meta_context_new, use gda_attributes_manager_free.

Since 5.2, you must consider this struct as opaque. Any access to its internal must use public API. Don't try to use gda_meta_context_free on a struct that was created manually.

#### Members

gchar *`table_name`; | the name of the table in the GdaMetaStore's internal database |
gint `size`; | the size of the `column_names` and `column_values` arrays |
gchar **`column_names`; | an array of column names (columns of the `table_name` table). | [array length=size][transfer container]
GValue **`column_values`; | an array of values, one for each column named in `column_names` . | [array length=size][transfer container]
GHashTable *`columns`; | A GHashTable storing columns' name as key and GValue as column's value. | [element-type utf8 GObject.Value]

## Property Details

### The `“catalog”` property

      “catalog”                  gchar *

Catalog in which the database objects will be created.

Flags: Write / Construct Only

Default value: NULL

### The `“cnc”` property

      “cnc”                      GdaConnection *

Connection object internally used.

Flags: Read / Write / Construct Only

### The `“cnc-string”` property

      “cnc-string”               gchar *

Connection string for the internal connection to use.

Flags: Write / Construct Only

Default value: NULL

### The `“schema”` property

      “schema”                   gchar *

Schema in which the database objects will be created.

Flags: Write / Construct Only

Default value: NULL

## Signal Details

### The `“meta-changed”` signal

    void
    user_function (GdaMetaStore *store,
                   gpointer      changes,
                   gpointer      user_data)

This signal is emitted when the `store` 's contents have changed (the changes are in the `changes` list)

#### Parameters

store | the GdaMetaStore instance that emitted the signal |
changes | a list of changes made, as a GSList of pointers to GdaMetaStoreChange (which must not be modified). | [type GLib.SList][element-type Gda.MetaStoreChange]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“meta-reset”` signal

    void
    user_function (GdaMetaStore *store,
                   gpointer      user_data)

This signal is emitted when the `store` 's contents have been reset completely and when no detailed changes are available

#### Parameters

store | the GdaMetaStore instance that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“suggest-update”` signal

    GError*
    user_function (GdaMetaStore *store,
                   gpointer      suggest,
                   gpointer      user_data)

This signal is emitted when the contents of a table should be updated (data to update or insert only; deleting data is done automatically). This signal is used for internal purposes by the GdaConnection object.

#### Parameters

store | the GdaMetaStore instance that emitted the signal |
suggest | the suggested update, as a GdaMetaContext structure. | [type Gda.MetaContext]
user_data | user data set when the signal handler was connected. |

#### Returns

a new GError error structure if there was an error when processing the signal, or `NULL` if signal propagation should continue

Flags: Run Last

## See Also

GdaMetaStruct