Welcome to Project Dewdrop

XML Tag Reference

DewDrop uses XML Schema to ensure that your database definitions conform to the above rules and others when specifying xml elements. If you are not familiar with XML Schema, the below tag descriptions will help you understand how your database definitions are to be structured. If you are familiar with XML Schema, you can also look at DewDrop's XML Schema Database Specification directly.

Elements:

database
table
column
primaryKey
foreignKey
index

<database>

A database has 4 attributes:

Attribute	Description	Required?
xmlns	Helps the xml parser validate the format of the xml element definitions within the document.	Yes
xmlns:xsi	Specifies schema instance namespace	Yes
xsi:schemaLocation	Specifies document location used to validate the schema namespace	Yes
name	The name of your database	Yes

A database must be defined in the following manner:

<database xmlns="http://dewdrop.sourceforge.net/xmlns/database_1_0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://dewdrop.sourceforge.net/xmlns/database_1_0 
                              database.xsd"
          name="myDatabase">
 
    ... table, index, and alteration definitions ...

</database>

Your database definition should look exactly like the above example, except for the "name" attribute. Use "name" to define a name for your database that makes sense.

Within a database definition, there are one or more table, index or alteration definitions which define the tablespace of the database you are creating.

<table>

A database must contain one or more tables.

A table has the following attributes:

Attribute	Description	Required?	Default
name	Defines the name of the table. This name must be unique across all tables.	Yes
global	If the target database supports global definitions, the table will be defined as global in the tablespace. Valid values are "true" or "false"	No	false
temporary	If the target database supports temporary table definitions, the table will be defined as temporary. Valid values are "true" or "false".	No	false

A table may contain columns, table-wide constraints (primary keys, foreign keys, unique), and native sql declarations.

They must be defined in the following order:

<table attributes...>
  
    column definitions ...

    table primary key definition (optional)

    table constraints in any order (e.g. <foreignKey> or <unique> ) (optional)

    native declarations (optional)
    
</table>

A description of all of a table's components are described later.

<column>

Columns specify a table's data structure, and they are the core of what defines a database. For this reason, the <column> element is the most complex, but it is easily understood after understanding its attributes.

A column has the following attributes:

Attribute	Description	Required?	Default
name	Defines the name of the table	Yes
sysName	DewDrop generates an sql name based on the above `name` attribute according to popular sql naming conventions. For example, if you specify the above `name` attribute to be "productInventoryCount", the actual column name in the sql file will be "product_inventory_count". If you don't want this naming convention to be applied, set`sysName` to be the actual value that you want in the sql file.	No	applied naming convention of the `name` attribute
type	Defines the data type the column is to represent. Valid values for this attribute are defined in the sql data types section.	Yes
length	Defines the maximum length that `type` may be. This attribute must be specified for `type`s that require it, and it will be ignored for those that can't understand it.	Only if specifying a `type` that requires it
precision	Defines the precision a column must adhere to. This attribute is only read for numerical types and ignored for all others.	No
default	If the target database supports default values for columns, this attribute specifies the default value for a column. The default value is set when doing an insert update to the column, and the column's value is not specified during the insert/update.	No
required	Specifies if this column must contain a value at all times (i.e. it must be "not null"). Valid values are "true" or "false". A value of "true" is a shortcut technique for specifying a column constraint of "not null".	No	false
unique	Specifies if all values in this column should be unique across all table rows. Valid values are "true" or "false".	No	false
primaryKey	Shortcut specification determining if this column is to participate in the table wide primary key definition. Primary Keys are described in detail in the Primary Keys section.	No	false
tableRef	Shortcut specification of declaring a foreign key inline with the column definition. The value must be a table `name` of a previously defined table. This attribute must also be accompanied by the `columnRef` attribute defined below.	No
columnRef	Shortcut specification of declaring a foreign key inline with the column definition. The value must be a column `name` of a previously defined column in a previously defined table.	Only if attribute `tableRef` is specified.
onDelete	Shortcut specification of declaring a foreign key inline with the column definition. If the target database supports constraint trigger actions, this attribute will specify what modification action is to be done to this column when the referencing column is deleted. Valid values are defined in the modification actions section.	No
onUpdate	Shortcut specification of declaring a foreign key inline with the column definition. If the target database supports constraint trigger actions, this attribute will specify what modification action is to be done to this column when the referencing column is updated. Valid values are defined in the modification actions section.	No

A column may contain a foreign key element. If you specify both a foreign key using the shortcut method (with column attributes) and a foreign key using the explicit declaration, the shortcut will be overridden. That is, the explicit declaration takes precedence.

Shortcut Method:

<column name="myColumn" type="sqlDataType" foreignKeyAttributes...(optional) />

or:

Explicit Method::

<column name="myColumn" type="sqlDataType">
			
    ... foreign key declaration ... (optional)    

</column>

<primaryKey>

A row in a database table is uniquely identified from any other row by a primary key. A <primaryKey> is a collection of column references, that together, form a unique combination, different from any other combination in any other row. Many times a primary key is just one column, meaning that column is guaranteed to be unique in every row in the table.

A Primary Key has the following attributes:

Attribute	Description	Required?	Default
name	Defines the name of the primary key.	No	Applied naming convention of tablename_pk

A Primary Key must have at least one local columnRef element to indicate what local columns in the table will participate in the table's primary key.

You can define a Primary Key in two ways:

With a standard <primaryKey> element declaration in the table definition.
Via a shortcut method using column attributes.

Standard Declaration:

You can define single and multi-column primary keys by using the <primaryKey> element in a table definition. If you use the <primaryKey> element in a table definition, it must be the first element after the last <column> definition. You specify what columns are to participate in the primary key by using <columnRef> elements.

Example: Standard definition, single column Primary Key

<table attributes...>

    <column name="columnId" type="integer"/>
    
    other column declarations ...
 
    <primaryKey>
        <columnRef local="columnId"/>
    </primaryKey>

</table>

A <columnRef> element's "local" attribute tells DewDrop what column to reference local to the current table. (As you'll see later, <columnRef> elements can be used to reference foreign columns in other tables too).

The Primary Key element can be used to just as easily create multi-column primary keys:

Example: Standard definition, multi-column Primary Key

<table attributes...>

    <column name="column1" type="varChar" length="50"/>
    <column name="column2" type="varChar" length="30"/>

     other column declarations ...
 
    <primaryKey>
        <columnRef local="column1"/>
        <columnRef local="column2"/>
        other local columnRefs...
    </primaryKey>

</table>

If you don't specify a name attribute for the primaryKey, then DewDrop will conveniently make one for you based on the table name, for example: my_table_name_pk.

Shortcut Declaration:

If you don't want, you can conveniently specify if a column participates in the table's primary key by specifying a "true" value for the column's primaryKey attribute:

Example: Shortcut method, single column Primary Key:

 <column name="columnId" type="integer" primaryKey="true"/>

This acts exactly like the first Standard definition, single column example shown above. DewDrop will create the primary key constraint trigger name for you based on the described naming convention. If you want to specify your own name, you'll have to use the <primaryKey> standard element declaration.

Multi-column primary keys using the shortcut method are nearly identical:

Example: Shortcut method, multi-column Primary Key:

 <column name="column1" type="varChar" length="50" primaryKey="true"/>
 <column name="column2" type="varChar" length="30" primaryKey="true"/>
 other column declarations ...

Specifying multi-column primary keys this way behaves exactly like the second Standard definition, multi-column example shown above. DewDrop will will create the primary key constraint trigger name for you based on the described naming convention. If you want to specify your own name, you'll have to use the <primaryKey> standard element declaration.

<foreignKey>

A row in a database table can be constrained to only reference values that are in another row in another table. This is known as a foreign key, because the local row is being keyed off of a foreign table's row. Not all databases support foreign keys, but DewDrop is intelligent enough to know the differences. DewDrop will write out Foreign Key declarations in SQL only when your target database supports them, so you don' thave to worry about possible SQL syntax errors.

Like primary keys, foreign keys can be single or multi-column keys. However, foreign keys must specify the foreign table they are referencing, as well as each foreign column their local columns reference.

A Foreign Key has the following attributes:

Attribute	Description	Required?	Default
name	Defines the name of the foreign key.	No	Applied naming convention of tablename_columnname_fk
foreignTable	Name of the foreign table this key will reference.	Yes
onUpdate	If the target database supports constraint trigger actions, this attribute will specify what modification action is to be done to this column when the referencing column is updated. Valid values are defined in the modification actions section.	No	noAction
onDelete	If the target database supports constraint trigger actions, this attribute will specify what modification action is to be done to this column when the referencing column is deleted. Valid values are defined in the modification actions section.	No	noAction

A Foreign Key must have at least one columnRef element with both a local and a foreign attribute to indicate what local columns in the table will participate in the foreign key, as well as what foreign columns this key is to reference.

You can define a Primary Key in two ways:

With a standard <foreignKey> element declaration in the table definition.
Via a shortcut method using column attributes.

Standard Declaration:

You can define single and multi-column foreign keys by using the <foreignKey> element in a table definition. If you use the <foreignKey> element in a table definition, it must be defined after any column definitions and the <primaryKey> element, if it exists. You specify what local columns are to participate in the foreign key by using <columnRef> elements, also specifying what foreign columns are keyed.

Example: Standard definition, single column Foreign Key

<table attributes...>
    
    <column name="columnId" type="integer"/>

    other column declarations ...

    primary key declaration (optional) 
 
    <foreignKey foreignTable="otherTable" onDelete="cascade">
        <columnRef local="columnId" foreign="otherTableColumnId"/>
    </primaryKey>

</table>

A <columnRef> element's "local" attribute tells DewDrop what column to reference local to the current table, and the "foreign" attribute tells DewDrop what column to key off of in the foreign table. Both are required when specifying a foreign key.

The Foreign Key element can be used to just as easily create multi-column foreign keys:

Example: Standard definition, multi-column Primary Key

<table attributes...>

    <column name="column1" type="varChar" length="50"/>
    <column name="column2" type="varChar" length="30"/>

     other column declarations ...
 
     primary key declaration (optional)

     <foreignKey foreignTable="otherTable" onDelete="cascade">
        <columnRef local="column1" foreign="otherTableColumn1"/>
        <columnRef local="column2" foreign="otherTableColumn2"/>
        other local columnRefs...
    </primaryKey>

</table>

If you don't specify a name attribute for the foreignKey, then DewDrop will conveniently make one for you based on the table name, for example: tablename_multicol1_fk.

Shortcut Declaration (single column foreign key only):

If you want, instead of using the standard declaration, you can conveniently specify if a column participates in single column foreign key by using the column's foreignKey attributes (tableRef, columnRef, onDelete, and onUpdate):

Example: Shortcut method, single column Foreign Key:

 <column name="columnId" type="integer" 
         tableRef="otherTable" columnRef="otherTableColumnId"
         onDelete="cascade"/>

This acts exactly like the first Standard definition, single column Foreign Key example shown above. If specifying a foreign key this way, both the tableRef and columnRef attributes are required, while the onUpdate and onDelete attributes are optional. DewDrop will create the foreign key constraint trigger name for you based on the described naming convention. If you want to specify your own name, you'll have to use the <foreignKey> standard element declaration.

Note: Multi-column foreign keys do not have a shortcut method. If you have a foreign key that is keyed off of multiple columns you'll have to explicitly declare the foreign key with the <foreignKey> element.

<index>

An index helps catalog a table's columns for efficient lookup when using the database. Indices are especially helpful for tables with potentially very large amounts of data. You do not have to specify an index on a table's primary key, as all primary keys are already indexed internally by a database.