# Table class

Table class is an implementation of DbTable interface. It uses GDA to get access to a database's table description.

In order to load data, you need to set a Gda.Connection and a table's name. Then update() method will introspect table information using GDA's MetaStore object and executing SELECT commands to retrive meta data to strore store it, you don't need to call update() again unless your table definition has changed.

## Table class UML definition

### UML definition

This diagram describes Table class and its implementations.

## Using a Table class to access a table meta data

This codes initiate a Table class, set a name and a connection in order to call update()

      var t = new Table ();
      t.name = "customer";
      t.connection = connection;
      t.update ();

In the above code, connection is opened before to be set to Table.connection property. You need to set Table.name property. Internally Gda.Connection.update_meta_store() is called, this could take some time, then executes some SELECT commands to introspect table, columns description are stored in DbFiledInfo objects.

## Using a Table class to add a new table

This setup a table to be added to a database's table

      var t = new Table ();
      t.name = "created_table";
      t.connection = connection;
      var field = new FieldInfo ();
      // Setup column id
      field.name = "id";
      field.value_type = typeof (int);
      field.attributes = DbFieldInfo.Attribute.PRIMARY_KEY |
                         DbFieldInfo.Attribute.AUTO_INCREMENT;
      t.set_field (field);

      // Setup column name
      var field1 = new FieldInfo ();
      field1.name = "name";
      field1.value_type = typeof (string);
      field1.attributes = DbFieldInfo.Attribute.NONE;
      t.set_field (field1);

      // Setup column company
      var field2 = new FieldInfo ();
      field2.name = "company";
      field2.value_type = typeof (int);
      field2.default_value = 1;

      // Setup column's foreign key
      var fk = new DbFieldInfo.ForeignKey ();
      var rt = new Table ();
      rt.name = "company";
      fk.reftable = rt;
      fk.refcol.add ("id");
      fk.update_rule = DbFieldInfo.ForeignKey.Rule.CASCADE;
      fk.delete_rule = DbFieldInfo.ForeignKey.Rule.SET_DEFAULT;
      field2.fkey = fk;
      t.set_field (field2);

      // Append new table
      t.append ();

In the above code a new table will be added. Create a new Table object, set its name and connection, use Table.set_field() to set column definitions. You must create DbFieldInfo objects, setting its name, type and attributes is enough to be set in a table. If your column must be a PRIMARY_KEY you must set DbFieldInfo.attributes to DbFieldInfo.Attribute.PRIMARY_KEY; if it is autoincrement key you must use | operator to add a DbFieldInfo.Attribute.AUTO_INCREMENT attribute.

If the column will refer to a column in other table as a foreign key you must set DbFieldInfo.fkey. DbFieldInfo.ForeignKey object is used for column's foreign keys.

## Deleting tables

If you want to delete a table you must create a new Table object, set a name and a Gda.Connection; finally you just call Table.drop() method.

### Dropping a table. Example

This code describes how to delete a table in a database

        var t = new Table ();
        t.name = "table_name";
        t.connection = connection;
        t.drop ();

## Iterating through Fields definitions

You can iterate over Table's fields descriptions using Vala foreach statement, by using Record.fields property; it's a Gee.Collection of DbFieldInfo objects, then you can use:

      foreach (DbFieldInfo f in table.fields) {
        /* work with DbField object */
      }

The same apply for all keys you set by using Table.primary_keys property.

## Access rows in a table

All rows in a table can be accessed using Table.records property, as a Gee.Collection of DbRecord objects. Internally, when this property is accessed a "SELECT * FROM table" SQL command is executed, you can filter them using Gee.Traversable.filter() function.

Table.records is a RecordCollection object that implements DbRecordCollection and its pre-requisites: Gee.Collection, Gee.Traversable and Gee.Iterable

Future implementations will include a way to create powerful filter to be used when SQL command is executed to avoid load all rows and iterate all over them when using Gee.Traversable.filter().

## Table's dependencies

In order to introspect a database table, you must create a new Table object, set a name and a Gda.Connection, then call Table.update(). After this you are able to know its dependencies.

### ForeignKeys

You can access to all DbTable objects referenced in foreign keys for each column in the table definition, using Table.depends, through a Gee.Collection of DbTable objects.

### Tables referencing your table

Using Table.referenced property, you can access to a Gee.Collection of DbTable objects that depends on your table.