GdaDbTable: libgda Reference Manual

## GdaDbTable GdaDbTable — Object to represent table database object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaDbTable * | gda_db_table_new ()
gboolean | gda_db_table_is_valid ()
void | gda_db_table_append_column ()
GList * | gda_db_table_get_columns ()
void | gda_db_table_append_fkey ()
GList * | gda_db_table_get_fkeys ()
gboolean | gda_db_table_prepare_create ()
gboolean | gda_db_table_update ()
void | gda_db_table_append_constraint ()
GQuark | gda_db_table_error_quark ()
gboolean | gda_db_table_get_is_temp ()
void | gda_db_table_set_is_temp ()

## Properties

char * | comment | Read / Write
char * | istemp | Read / Write

## Types and Values

| GdaDbTable
enum | GdaDbTableError
#define | GDA_TYPE_DB_TABLE
#define | GDA_DB_TABLE_ERROR

## Object Hierarchy

        GObject
        ╰── GdaDbBase
            ╰── GdaDbTable

## Implemented Interfaces

GdaDbTable implements GdaDbBuildable and GdaDdlModifiable.

## Includes

    #include <libgda/libgda.h>

## Description

This object represents a table of a database. The table view can be constracted manually using API or generated from xml file together with other databse objects. See GdaDbCatalog. GdaDbTable implements GdaDbBuildable interface for parsing xml file.

GdaDbTable can be used as a container to hold other objects, e.g. GdaDbColumn, GdaDbFkey and as soon as populated with all needed objects the table can be created using `gda_ddl_modifiable_create()`,

To delete the table a method `gda_ddl_modifiable_drop()` can be called.

A simple example of how to create a table with 3 columns being the last column of the foreign key.

    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
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    GdaConnection *cnc;
    //Open connection here

    GError        *error = NULL;

    GdaDbTable *tproject = gda_db_table_new ();
    gda_db_base_set_name (GDA_DB_BASE (tproject), "Project");

    GdaDbColumn *pid   = gda_db_column_new ();
    GdaDbColumn *pname = gda_db_column_new ();
    GdaDbColumn *pfkey = gda_db_column_new ();
    GdaDbFkey   *fkey  = gda_db_fkey_new ();

    gda_db_column_set_name (pid, "id");
    gda_db_column_set_type (pid, G_TYPE_INT);
    gda_db_column_set_nnul (pid, TRUE);
    gda_db_column_set_autoinc (pid, TRUE);
    gda_db_column_set_unique (pid, TRUE);
    gda_db_column_set_pkey (pid, TRUE);

    gda_db_column_set_name (pname, "name");
    gda_db_column_set_type (pname, G_TYPE_STRING);
    gda_db_column_set_size (pname, 30);
    gda_db_column_set_nnul (pname, TRUE);
    gda_db_column_set_unique (pname, TRUE);

    gda_db_column_set_name (pfkey, "fkey");
    gda_db_column_set_type (pfkey, G_TYPE_INT);
    gda_db_column_set_nnul (pfkey, TRUE);

    gda_db_fkey_set_ref_table (fkey, "AnotherTable");
    gda_db_fkey_set_ondelete (fkey, GDA_DB_FKEY_RESTRICT);
    gda_db_fkey_set_onupdate (fkey, GDA_DB_FKEY_RESTRICT);
    gda_db_fkey_set_field (fkey, "fkey", "another_table_id");

    gda_db_table_append_column (tproject, pid);
    g_object_unref (pid);

    gda_db_table_append_column (tproject, pname);
    g_object_unref (pname);

    gda_db_table_append_column (tproject, pfkey);
    g_object_unref (pfkey);

    gda_db_table_append_fkey (tproject, fkey);
    g_object_unref (fkey);

    if (!gda_ddl_modifiable_create (GDA_DDL_MODIFIABLE (tproject), cnc, NULL, &error))
    {
      g_error ("It was not possible to create the table in the database: %s\n",
               error && error->message ? error->message : "No detail");
    }

    g_object_unref (tproject);

## Functions

### gda_db_table_new ()

    GdaDbTable *
    gda_db_table_new (void);

#### Returns

New instance of GdaDbTable, to free with `g_object_unref()` once not needed anymore

Since: 6.0

Stability Level: Stable

### gda_db_table_is_valid ()

    gboolean
    gda_db_table_is_valid (GdaDbTable *self);

This method returns `TRUE` if at least one column is added to the table. It ruturns `FALSE` if the table has no columns.

#### Parameters

self | a GdaDbTable instance |

#### Returns

`TRUE` or `FALSE`

Since: 6.0

Stability Level: Stable

### gda_db_table_append_column ()

    void
    gda_db_table_append_column (GdaDbTable *self,
                                GdaDbColumn *column);

Append `column` to the internal list of columns

#### Parameters

self | a GdaDbTable instance |
column | column to add |

Since: 6.0

Stability Level: Stable

### gda_db_table_get_columns ()

    GList *
    gda_db_table_get_columns (GdaDbTable *self);

Use this method to obtain internal list of all columns. The internal list should not be freed.

#### Parameters

self | an GdaDbTable object |

#### Returns

A list of GdaDbColumn objects or `NULL` if the internal list is not set or if `NULL` is passed.

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

Since: 6.0

Stability Level: Stable

### gda_db_table_append_fkey ()

    void
    gda_db_table_append_fkey (GdaDbTable *self,
                              GdaDbFkey *fkey);

Append `fkey` to the internal list of columns

#### Parameters

self | a GdaDbTable instance |
fkey | fkry to add |

Since: 6.0

Stability Level: Stable

### gda_db_table_get_fkeys ()

    GList *
    gda_db_table_get_fkeys (GdaDbTable *self);

Use this method to obtain internal list of all fkeys. The internal list should not be freed.

#### Parameters

self | A GdaDbTable object |

#### Returns

A list of GdaDbFkey objects or `NULL` if the internal list is not set or `NULL` is passed.

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

Since: 6.0

Stability Level: Stable

### gda_db_table_prepare_create ()

    gboolean
    gda_db_table_prepare_create (GdaDbTable *self,
                                 GdaServerOperation *op,
                                 gboolean ifnotexists,
                                 GError **error);

Populate `op` with information stored in `self` . This method sets `op` to execute CREATE_TABLE operation.

#### Parameters

self | a GdaDbTable instance |
op | an instance of GdaServerOperation to populate. |
ifnotexists | Set it to TRUE if "IF NOT EXISTS" should be added |
error | error container |

#### Returns

`TRUE` if no error occured and `FALSE` otherwise.

Since: 6.0

Stability Level: Stable

### gda_db_table_update ()

    gboolean
    gda_db_table_update (GdaDbTable *self,
                         GdaMetaTable *obj,
                         GdaConnection *cnc,
                         GError **error);

With this method object `obj` in the database available through `cnc` will be updated using ADD_COLUMN operation with information stored in `self` . This method is designed for internal use only and should not be used for the new code. It will be obsolete.

#### Parameters

self | a GdaDbTable instance |
obj | The corresponding meta object to take data from |
cnc | opened connection |
error | error container |

#### Returns

`TRUE` if no error and `FALSE` otherwise

### gda_db_table_append_constraint ()

    void
    gda_db_table_append_constraint (GdaDbTable *self,
                                    const gchar *constr);

Adds global table constraint. It will be added to the sql string by the provider implementation if it supports it. Usually, table constraint is very complex and the current method just append a list of constraints to the sql string.

#### Parameters

self | a GdaDbTable instance |
constr | a constraint string to append |

Since: 6.0

Stability Level: Stable

### gda_db_table_error_quark ()

    GQuark
    gda_db_table_error_quark (void);

### gda_db_table_get_is_temp ()

    gboolean
    gda_db_table_get_is_temp (GdaDbTable *self);

### gda_db_table_set_is_temp ()

    void
    gda_db_table_set_is_temp (GdaDbTable *self,
                              gboolean istemp);

Set if the table should be temporary or not. `FALSE` is set by default.

#### Parameters

self | a GdaDbTable object |
istemp | Set if the table should be temporary |

Since: 6.0

Stability Level: Stable

## Types and Values

### GdaDbTable

    typedef struct _GdaDbTable GdaDbTable;

### enum GdaDbTableError

#### Members

GDA_DB_TABLE_COLUMN_EMPTY | Table doesn't contain columns |
GDA_DB_TABLE_CONNECTION_NOT_OPENED | Closed connection was passed as parameter |
GDA_DB_TABLE_SERVER_OPERATION | Error related to GdaServerOperation |

### GDA_TYPE_DB_TABLE

    #define GDA_TYPE_DB_TABLE (gda_db_table_get_type())

### GDA_DB_TABLE_ERROR

    #define GDA_DB_TABLE_ERROR gda_db_table_error_quark()

## Property Details

### The `“comment”` property

      “comment”                  char *

Table comment.

Owner: GdaDbTable

Flags: Read / Write

Default value: NULL

### The `“istemp”` property

      “istemp”                   char *

Is table temporary.

Owner: GdaDbTable

Flags: Read / Write

Default value: NULL

## See Also

GdaDbView, GdaDbCatalog