GdaDbCatalog

GdaDbCatalog — Object to constract database representation from an xml file or by reading the existing datatabase

Stability Level

Stable, unless otherwise indicated

Functions

Properties

GdaConnection * connection Read / Write
char * schema-name Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── GdaDbCatalog

Includes

#include <libgda/libgda.h>

Description

This is a main object that represents overall database. The best way to create an instance of GdaDbCatalog is to call gda_connection_create_db_catalog(). This object may be also constracted from an xml file using gda_db_catalog_parse_file() or gda_db_catalog_parse_file_from_path() or didrectly from the open connection using gda_db_catalog_parse_cnc().

The database can be updated or modified using gda_db_catalog_perform_operation() and dumped to a file using gda_db_catalog_write_to_path() or gda_db_catalog_write_to_file().

Functions

gda_db_catalog_new ()

GdaDbCatalog *
gda_db_catalog_new (void);

Create new instance of GdaDbCatalog.

Returns

a new instance of GdaDbCatalog

Since: 6.0


gda_db_catalog_get_tables ()

GList *
gda_db_catalog_get_tables (GdaDbCatalog *self);

Parameters

self

a GdaDbCatalog object

 

Returns

a list of tables as GdaDbTable or NULL.

[element-type Gda.DbTable][transfer none]

Since: 6.0


gda_db_catalog_get_views ()

GList *
gda_db_catalog_get_views (GdaDbCatalog *self);

Parameters

self

a GdaDbCatalog object

 

Returns

a list of views as GdaDbView or NULL.

[element-type Gda.DbView][transfer none]

Since: 6.0


gda_db_catalog_append_table ()

void
gda_db_catalog_append_table (GdaDbCatalog *self,
                             GdaDbTable *table);

This method append table to the total list of all tables stored in self . This method increase reference count for table .

Parameters

self

a GdaDbCatalog instance

 

table

table to append

 

Since: 6.0


gda_db_catalog_append_view ()

void
gda_db_catalog_append_view (GdaDbCatalog *self,
                            GdaDbView *view);

This method append view to the total list of all views stored in self . This method increase reference count for view .

Parameters

self

a GdaDbCatalog instance

 

view

view to append

 

Since: 6.0


gda_db_catalog_parse_cnc ()

gboolean
gda_db_catalog_parse_cnc (GdaDbCatalog *self,
                          GError **error);

Parse internal cnc to populate self object. This method should be called every time after database was modified or self was just created using gda_connection_create_db_catalog(). The method will return FALSE if no internal GdaConnection available.

Parameters

self

a GdaDbCatalog instance

 

error

error storage object

 

Returns

Returns TRUE if succeeded, FALSE otherwise.

Since: 6.0


gda_db_catalog_parse_file ()

gboolean
gda_db_catalog_parse_file (GdaDbCatalog *self,
                           GFile *xmlfile,
                           GError **error);

For detailed description see gda_db_catalog_parse_file_from_path()

Parameters

self

an instance of GdaDbCatalog

 

xmlfile

xml file as GFile instance

 

error

Error container

 

Since: 6.0


gda_db_catalog_parse_file_from_path ()

gboolean
gda_db_catalog_parse_file_from_path (GdaDbCatalog *self,
                                     const gchar *xmlfile,
                                     GError **error);

This method reads information from xmlfile and populate self object. The xmlfile should correspond to the following DTD format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<!ELEMENT schema (table+, view*)>
<!ATTLIST schema name           CDATA   #IMPLIED>

<!ELEMENT table (comment?,column+, fkey*, constraint*)>
<!ATTLIST table temptable       (TRUE|FALSE)    "FALSE">
<!ATTLIST table name            CDATA           #REQUIRED>
<!ATTLIST table space           CDATA           #IMPLIED>

<!ELEMENT column (comment?, value?, check?)>
<!ATTLIST column name           CDATA           #REQUIRED>
<!ATTLIST column type           CDATA           #REQUIRED>
<!ATTLIST column pkey           (TRUE|FALSE)    "FALSE">
<!ATTLIST column unique         (TRUE|FALSE)    "FALSE">
<!ATTLIST column autoinc        (TRUE|FALSE)    "FALSE">
<!ATTLIST column nnul           (TRUE|FALSE)    "FALSE">

<!ELEMENT comment       (#PCDATA)>
<!ELEMENT value         (#PCDATA)>
<!ATTLIST value size            CDATA          #IMPLIED>
<!ATTLIST value scale           CDATA          #IMPLIED>

<!ELEMENT check         (#PCDATA)>

<!ELEMENT constraint    (#PCDATA)>

<!ELEMENT fkey (fk_field?)>
<!ATTLIST fkey reftable CDATA #IMPLIED>
<!ATTLIST fkey onupdate (RESTRICT|CASCADE|SET_NULL|NO_ACTION|SET_DEFAULT)       #IMPLIED>
<!ATTLIST fkey ondelete (RESTRICT|CASCADE|SET_NULL|NO_ACTION|SET_DEFAULT)       #IMPLIED>

<!ELEMENT fk_field (#PCDATA)>
<!ATTLIST fk_field name         CDATA           #REQUIRED>
<!ATTLIST fk_field reffield     CDATA           #REQUIRED>

<!ELEMENT view (definition)>
<!ATTLIST view name             CDATA           #REQUIRED>
<!ATTLIST view replace          (TRUE|FALSE)    "FALSE">
<!ATTLIST view temp             (TRUE|FALSE)    "FALSE">
<!ATTLIST view ifnotexists      (TRUE|FALSE)    "TRUE">

<!ELEMENT definition (#PCDATA)>

Up to day description of the xml file schema can be found in DTD file libgda-db-catalog.dtd

The given xmlfile will be checked before parsing and FALSE will be returned if fails. The xmlfile will be validated internally using gda_db_catalog_validate_file_from_path(). he same method can be used to validate xmlfile before parsing it.

Parameters

self

an instance of GdaDbCatalog

 

xmlfile

xml file to parse

 

error

Error container

 

gda_db_catalog_perform_operation ()

gboolean
gda_db_catalog_perform_operation (GdaDbCatalog *self,
                                  GError **error);

After population self with all data this method may be called to trigger code and modify user database. This is the main method to work with database. For retrieving information from database to an xml file use gda_db_catalog_parse_cnc() and gda_db_buildable_write_node().

Connection can be added as a property using g_object_set() call and should be opened to use this method. See gda_connection_open() method for reference.

Only table can be created. Views are ignored

Each table from database compared with each table in the GdaDbCatalog instance. If the table doesn't exist in database, it will be created (CREATE_TABLE). If table exists in the database and xml file, all columns will be checked. If columns are present in xml file but not in the database it will be created (ADD_COLUMN). If column exists but has different parameters, e.g. nonnull it will not be modified.

Note: Pkeys are not checked. This is a limitation that should be removed. The corresponding issue was open on gitlab page.

Parameters

self

a GdaDbCatalog object

 

error

object to store error

 

gda_db_catalog_write_to_file ()

gboolean
gda_db_catalog_write_to_file (GdaDbCatalog *self,
                              GFile *file,
                              GError **error);

This method writes database description as xml file. Similar to gda_db_catalog_write_to_path()

Parameters

self

a GdaDbCatalog instance

 

file

a GFile to write database description

 

error

container to hold error

 

Returns

TRUE if no error occurred, FALSE otherwise.

Since: 6.0


gda_db_catalog_write_to_path ()

gboolean
gda_db_catalog_write_to_path (GdaDbCatalog *self,
                              const gchar *path,
                              GError **error);

Save content of self to a user friendly xml file.

Parameters

self

a GdaDbCatalog instance

 

path

path to xml file to save GdaDbCatalog

 

error

container to hold an error

 

Returns

TRUE is no error, FALSE otherwise.

Since: 6.0


gda_db_catalog_error_quark ()

GQuark
gda_db_catalog_error_quark (void);

gda_db_catalog_validate_file_from_path ()

gboolean
gda_db_catalog_validate_file_from_path
                               (const gchar *xmlfile,
                                GError **error);

Convenient method to varify xmlfile before prsing it.

Parameters

xmlfile

xml file to validate

 

error

error container

 

Returns

TRUE if xmlfile is valid, FALSE otherwise

Since: 6.0

Types and Values

GdaDbCatalog

typedef struct _GdaDbCatalog GdaDbCatalog;

enum GdaDbCatalogError

These error are primary for developers to troubleshoot the problem rather than for user.

Members

GDA_DB_CATALOG_CONTEXT_NULL

Context is NULL. Should not be NULL for normal operation.

 

GDA_DB_CATALOG_DOC_NULL

xmlDocPtr is NULL.

 

GDA_DB_CATALOG_INVALID_XML

Sets if xml check fails. Xml file structure doesn't match with DTD file

 

GDA_DB_CATALOG_INVALID_SCHEMA

Sets if the used schema is invalid.

 

GDA_DB_CATALOG_SERVER_OPERATION

Sets if server operation is NULL.

 

GDA_DB_CATALOG_FILE_READ

Sets if xml file is not readable

 

GDA_DB_CATALOG_PARSE_CONTEXT

Sets if an error with context during parsing an xml file

 

GDA_DB_CATALOG_PARSE

Sets if parsing reports an error

 

GDA_DB_CATALOG_PARSE_CHUNK

If set, error with parse chunk algorithm.

 

GDA_DB_CATALOG_CONNECTION_CLOSED

Connection is not open.

 

GDA_TYPE_DB_CATALOG

#define GDA_TYPE_DB_CATALOG (gda_db_catalog_get_type())

GDA_DB_CATALOG_ERROR

#define GDA_DB_CATALOG_ERROR gda_db_catalog_error_quark()

Property Details

The “connection” property

  “connection”               GdaConnection *

Connection to use.

Owner: GdaDbCatalog

Flags: Read / Write


The “schema-name” property

  “schema-name”              char *

Name of the schema.

Owner: GdaDbCatalog

Flags: Read / Write

Default value: NULL

See Also

GdaDbTable, GdaDbView