Gda.MetaStore¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (cnc_string)
class	`new_with_file` (file_name)
class	`sql_identifier_quote` (id, cnc)
	`create_modify_data_model` (table_name)
	`declare_foreign_key` (mstruct, fk_name, catalog, schema, table, ref_catalog, ref_schema, ref_table, colnames, ref_colnames)
	`extract` (select_sql, vars)
	`get_attribute_value` (att_name)
	`get_internal_connection` ()
	`get_version` ()
	`modify` (table_name, new_data, condition, value_names, values)
	`modify_with_context` (context, new_data)
	`schema_add_custom_object` (xml_description)
	`schema_get_all_tables` ()
	`schema_get_depend_tables` (table_name)
	`schema_get_structure` ()
	`schema_remove_custom_object` (obj_name)
	`set_attribute_value` (att_name, att_value)
	`set_identifiers_style` (style)
	`set_reserved_keywords_func` (func)
	`undeclare_foreign_key` (mstruct, fk_name, catalog, schema, table, ref_catalog, ref_schema, ref_table)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_meta_reset` ()
	`do_suggest_update` (suggest)

Properties¶

Name	Type	Flags	Short Description
`catalog`	`str`	w/co	Catalog in which the database objects will be created
`cnc`	`Gda.Connection`	r/w/co	Connection object internally used
`cnc-string`	`str`	w/co	Connection string for the internal connection to use
`schema`	`str`	w/co	Schema in which the database objects will be created

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`meta-changed`	This signal is emitted when the store's contents have changed (the changes are in the changes list)
`meta-reset`	This signal is emitted when the store's contents have been reset completely and when no detailed changes are available
`suggest-update`	This signal is emitted when the contents of a table should be updated (data to update or insert only; deleting data is done automatically).

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
object	`GObject.Object`	r

Class Details¶

class Gda.MetaStore(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gda.MetaStoreClass

classmethod error_quark()¶

Return type:: int

classmethod new(cnc_string)¶

Parameters:: cnc_string (str or None) – a connection string, or None for an in-memory internal database
Returns:: the newly created object, or None if an error occurred
Return type:: Gda.MetaStore

Create a new Gda.MetaStore object.

classmethod new_with_file(file_name)¶

Parameters:: file_name (str) – a file name
Returns:: the newly created object, or None if an error occurred
Return type:: Gda.MetaStore

Create a new Gda.MetaStore object using file_name as its internal database

classmethod sql_identifier_quote(id, cnc)¶

Parameters:

id (str) – an SQL identifier
cnc (Gda.Connection) – a Gda.Connection

Returns:

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

Return type:

str

Use this method to get a correctly quoted (if necessary) SQL identifier which can be used to retrieve or filter information in a Gda.MetaStore 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.MetaStore.extract().

New in version 4.0.3.

create_modify_data_model(table_name)¶

Parameters:: table_name (str) – the name of a table present in self
Returns:: a new Gda.DataModel
Return type:: Gda.DataModel

Creates a new Gda.DataModelArray data model which can be used, after being correctly filled, with the Gda.MetaStore.modify() methods.*

To be used by provider’s implementation

declare_foreign_key(mstruct, fk_name, catalog, schema, table, ref_catalog, ref_schema, ref_table, colnames, ref_colnames)¶

Parameters:

mstruct (Gda.MetaStruct or None) – a Gda.MetaStruct, or None
fk_name (str) – the name of the foreign key to declare
catalog (str or None) – the catalog in which the table (for which the foreign key is for) is, or None
schema (str or None) – the schema in which the table (for which the foreign key is for) is, or None
table (str) – the name of the table (for which the foreign key is for)
ref_catalog (str or None) – the catalog in which the referenced table is, or None
ref_schema (str or None) – the schema in which the referenced table is, or None
ref_table (str) – the name of the referenced table
colnames ([str]) – an array of column names from the table for which the foreign key is for
ref_colnames ([str]) – an array of column names from the referenced table

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Defines a new declared foreign key into self. 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 None (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 Gda.MetaStruct is None.

The catalog, schema, table, ref_catalog, ref_schema and ref_table must follow the SQL identifiers naming convention, see the ‘SQL identifiers [gen:sql_identifiers]’ section. The same convention needs to be respected for the strings in conames and ref_colnames.

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

New in version 4.2.4.

extract(select_sql, vars)¶

Parameters:

select_sql (str) – a SELECT statement
vars ({str: GObject.Value} or None) – a hash table with all variables names as keys and GObject.Value as value, representing values for all the variables mentioned in select_sql. If there is no variable then this part can be omitted.

Raises:

GLib.Error

Returns:

a new Gda.DataModel, or None if an error occurred

Return type:

Gda.DataModel

Extracts some data stored in self 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.MetaStore.sql_identifier_quote().

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

‘meta data section about SQL identifiers [information_schema:sql_identifiers]’.

New in version 4.2.6.

get_attribute_value(att_name)¶

Parameters:

att_name (str) – name of the attribute to get

Raises:

GLib.Error

Returns:

True if no error occurred

att_value:: the place to store the attribute value

Return type:

(bool, att_value: str)

The Gda.MetaStore 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.MetaStore.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 self. 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 None and error will contain the Gda.MetaStoreError.ATTRIBUTE_NOT_FOUND_ERROR error code, and False is returned.

get_internal_connection()¶

Returns:: a Gda.Connection, or None
Return type:: Gda.Connection

Get a pointer to the Gda.Connection object internally used by self to store its contents.

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

get_version()¶

Returns:: the version (incremented each time the schema changes, backward compatible)
Return type:: int

Get self's internal schema’s version

modify(table_name, new_data, condition, value_names, values)¶

Parameters:

table_name (str) – the name of the table to modify within self
new_data (Gda.DataModel or None) – a Gda.DataModel containing the new data to set in table_name, or None (treated as a data model with no row at all)
condition (str or None) – SQL expression (which may contain variables) defining the rows which are being obsoleted by new_data, or None
value_names ([str]) – names of values
values ([GObject.Value]) – values

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Propagates an update to self, the update’s contents is represented by new_data, this function is primarily reserved to database providers.

New in version 4.2.6.

modify_with_context(context, new_data)¶

Parameters:

context (Gda.MetaContext) – a Gda.MetaContext context describing what to modify in self
new_data (Gda.DataModel or None) – a Gda.DataModel containing the new data to set in table_name, or None (treated as a data model with no row at all)

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Propagates an update to self, the update’s contents is represented by new_data, this function is primarily reserved to database providers.

schema_add_custom_object(xml_description)¶

Parameters:: xml_description (str) – an XML description of the table or view to add to self
Raises:: GLib.Error
Returns:: True if the new object has successfully been added
Return type:: bool

The internal database used by self 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.MetaStoreError.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)>

schema_get_all_tables()¶

Returns:: a new list of tables names (as str), the list must be freed when no longer needed, but the strings present in the list must not be modified.
Return type:: [str]

Get an ordered list of the tables self knows about. The tables are ordered in a way that tables dependencies are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned list.

schema_get_depend_tables(table_name)¶

Parameters:: table_name (str) – the name of the table for which all the dependencies must be listed
Returns:: a new list of tables names (as str), the list must be freed when no longer needed, but the strings present in the list must not be modified.
Return type:: [str]

Get an ordered list of the tables self knows about on which the table_name table depends (recursively). The tables are ordered in a way that tables dependencies are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned list.

schema_get_structure()¶

Raises:: GLib.Error
Returns:: a new Gda.MetaStruct object, or None if an error occurred
Return type:: Gda.MetaStruct

Creates a new Gda.MetaStruct object representing self's internal database structure.

schema_remove_custom_object(obj_name)¶

Parameters:: obj_name (str) – name of the custom object to remove
Raises:: GLib.Error
Returns:: True if the custom object has successfully been removed
Return type:: bool

Removes the custom database object named obj_name.

set_attribute_value(att_name, att_value)¶

Parameters:

att_name (str) – name of the attribute to set
att_value (str or None) – value of the attribute to set, or None to unset the attribute

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Set the value of the attribute named att_name to att_value; see Gda.MetaStore.get_attribute_value() for more information.

set_identifiers_style(style)¶

Parameters:: style (Gda.SqlIdentifierStyle) – a style

Specifies how self must handle SQL identifiers it has to store. This method is mainly used by database providers.

New in version 4.2.

set_reserved_keywords_func(func)¶

Parameters:: func (Gda.SqlReservedKeywordsFunc or None) – a Gda.SqlReservedKeywordsFunc function, or None

Specifies a function which self will use to determine if a keyword is an SQL reserved keyword or not.

This method is mainly used by database providers.

New in version 4.2.

undeclare_foreign_key(mstruct, fk_name, catalog, schema, table, ref_catalog, ref_schema, ref_table)¶

Parameters:

mstruct (Gda.MetaStruct or None) – a Gda.MetaStruct, or None
fk_name (str) – the name of the foreign key to declare
catalog (str or None) – the catalog in which the table (for which the foreign key is for) is, or None
schema (str or None) – the schema in which the table (for which the foreign key is for) is, or None
table (str) – the name of the table (for which the foreign key is for)
ref_catalog (str or None) – the catalog in which the referenced table is, or None
ref_schema (str or None) – the schema in which the referenced table is, or None
ref_table (str) – the name of the referenced table

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Removes a declared foreign key from self.

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 None (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 Gda.MetaStruct is None.

See Gda.MetaStore.declare_foreign_key() for more information anout the catalog, schema, name, ref_catalog, ref_schema and ref_name arguments.

New in version 4.2.4.

do_meta_reset() virtual¶

do_suggest_update(suggest) virtual¶

Parameters:: suggest (Gda.MetaContext) –
Return type:: GLib.Error

Signal Details¶

Gda.MetaStore.signals.meta_changed(meta_store, changes)¶

Signal Name:

meta-changed

Flags:

RUN_FIRST

Parameters:

meta_store (Gda.MetaStore) – The object which received the signal
changes ([Gda.MetaStoreChange]) – a list of changes made, as a GLib.SList of pointers to Gda.MetaStoreChange (which must not be modified)

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

Gda.MetaStore.signals.meta_reset(meta_store)¶

Signal Name:: meta-reset
Flags:: RUN_FIRST
Parameters:: meta_store (Gda.MetaStore) – The object which received the signal

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

Gda.MetaStore.signals.suggest_update(meta_store, suggest)¶

Signal Name:

suggest-update

Flags:

RUN_LAST

Parameters:

meta_store (Gda.MetaStore) – The object which received the signal
suggest (Gda.MetaContext) – the suggested update, as a Gda.MetaContext structure

Returns:

a new GLib.Error error structure if there was an error when processing the signal, or None if signal propagation should continue

Return type:

GLib.Error

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 Gda.Connection object.

Property Details¶

Gda.MetaStore.props.catalog¶

Name:: catalog
Type:: str
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

Catalog in which the database objects will be created

Gda.MetaStore.props.cnc¶

Name:: cnc
Type:: Gda.Connection
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Connection object internally used

Gda.MetaStore.props.cnc_string¶

Name:: cnc-string
Type:: str
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

Connection string for the internal connection to use

Gda.MetaStore.props.schema¶

Name:: schema
Type:: str
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

Schema in which the database objects will be created