Gda.MetaStore

g GObject.Object GObject.Object Gda.MetaStore Gda.MetaStore GObject.Object->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:
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:
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:

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:

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