GdaDbCatalog: libgda Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaDbCatalog * | gda_db_catalog_new ()
GList * | gda_db_catalog_get_tables ()
GList * | gda_db_catalog_get_views ()
void | gda_db_catalog_append_table ()
void | gda_db_catalog_append_view ()
gboolean | gda_db_catalog_parse_cnc ()
gboolean | gda_db_catalog_parse_file ()
gboolean | gda_db_catalog_parse_file_from_path ()
gboolean | gda_db_catalog_perform_operation ()
gboolean | gda_db_catalog_write_to_file ()
gboolean | gda_db_catalog_write_to_path ()
GQuark | gda_db_catalog_error_quark ()
gboolean | gda_db_catalog_validate_file_from_path ()

## Properties

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

## Types and Values

| GdaDbCatalog
enum | GdaDbCatalogError
#define | GDA_TYPE_DB_CATALOG
#define | GDA_DB_CATALOG_ERROR

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