Database Schema

The schema for schema.xml contains a small number of elements with required and optional attributes. The Propel generator contains a DTD (source:trunk/generator/dtd/database.dtd) that can be used to validate your schema.xml document. Also, when you build your SQL and OM, the Propel generator will automatically validate your schema.xml file using a new, highly-detailed XSD (source:trunk/generator/resources/xsd/database.xsd).

At-a-Glance

The hierarchical tree relationship for the elements is:

<database>
   <external-schema />
   <table>
     <column>
       <inheritance />
     </column>
     <foreign-key>
       <reference />
     </foreign-key>
     <index>
       <index-column />
     </index>
     <unique>
       <unique-column />
     </unique>
     <id-method-parameter/>
   </table>
</database>

Detailed Reference

This page provides an alternate rendering of the Appendix B - Schema Reference from the user's guide. It spells out in specific detail, just where each attribute or element belongs.

First, some conventions:

• Text surrounded by a / is text that you would provide and is not defined in the language. (i.e. a table name is a good example of this.)
• Optional items are surrounded by [ and ] characters.
• Items where you have an alternative choice have a | character between them (i.e. true|false)
• Alternative choices may be delimited by { and } to indicate that this is the default option, if not overridden elsewhere.
• ... means repeat the previous item.

<database> element

Starting with the <database> element. The attributes and elements available are:

  <database 
    name="/DatabaseName/" 
    defaultIdMethod="native|none" 
    [package="/ProjectName/"] 
    [baseClass="/baseClassName/"]
    [basePeer="/baseClassPeerName/"]
    [defaultPhpNamingMethod="nochange|underscore|phpname"
    [heavyIndexing="true|false"]
  >
    <external-schema>
    <table>
    ...
  </database>

The package, baseClass, basePeer, defaultPhpNamingMethod, and heavyIndexing attributes are generally optional. A Database element may include an <external-schema> element, or multiple <table> elements.

<external-schema> element

The <external-schema> element is pretty simple. It just includes a schema file from somewhere on the file systems. The format is:

  <external-schema filename="/a path to a file/" />

<table> element

The <table> element is the most complicated of the usable elements. Its definition looks like this:

  <table 
     name = "/TableName/"
     [idMethod = "native|{none}"]
     [phpName = "/PhpObjectName/"]
     [skipSql = "true|false"]
     [abstract = "true|false"]
     [phpNamingMethod = "nochange|{underscore}|phpname"]
     [baseClass = "/baseClassName/"]
     [basePeer = "/baseClassPeerName/"]
     [description="/A text description of the table/"]
     [heavyIndexing = "true|false"]
     [readOnly = "true|false"]
  >

    <column>
    ...
    <foreign-key>
    ...
    <index>
    ...
    <unique>
    ...
    <id-method-parameter>
    ...
  </table>

According to the schema, name is the only required attribute. Also, the idMethod, phpNamingMethod, baseClass, basePeer, and heavyIndexing attributes all default to what is specified by the <database> element.

<column> element

  <column
    name = "/ColumnName/"
    [phpName = "/PHPColumnName/"]
    [peerName = "/PEERNAME/"]
    [primaryKey = "true|{false}"]
    [required = "true|{false}"]
    [type = "BOOLEAN|TINYINT|SMALLINT|INTEGER|BIGINT|DOUBLE|FLOAT|REAL|DECIMAL|CHAR|{VARCHAR}|LONGVARCHAR|DATE|TIME|TIMESTAMP|BLOB|CLOB"]
    [size = "/NumericLengthOfColumn/"]
    [scale = "/DigitsAfterDecimalPlace/"]
    [default = "/AnyDefaultValueMatchingType/"]
    [autoIncrement = "true|{false}"]
    [description = "/Column Description/"]
    [phpNamingMethod = "nochange|underscore|phpname"]
    [inheritance = "single|{false}"]
    [inputValidator = "NameOfInputValidatorClass"]
   >
   [<inheritance key="/KeyName/" class="/ClassName/" [extends="/BaseClassName/"] />]
   </column>

<foreign-key> element

To link a column to another table use the following syntax:

  <foreign-key 
     foreignTable = "/TheOtherTableName/"
     [name = "/Name for this foreign key/"]
     [onDelete = "cascade|setnull|{restrict}"]
  >
    <reference local="/LocalColumnName/" foreign="/ForeignColumnName/" />
  </foreign-key>

<index> element

To create an index on one or more columns, use the following syntax:

  <index>
     <index-column name="/ColumnName/" [size="/LengthOfIndexColumn/"] />
     ...
  </index>

In some cases your RDBMS may require you to specify an index size.

<unique> element

To create a unique index on one or more columns, use the following syntax:

  <unique>
     <unique-column name="/ColumnName/" [size="/LengthOfIndexColumn/"] />
     ...
  </unique>

In some cases your RDBMS may require you to specify an index size for unique indexes.

<id-method-parameter> element

If you are using a database that uses sequences for auto-increment columns (e.g. PostgreSQL or Oracle), you can customize the name of the sequence using the <id-method-paramter/> tag:

  <id-method-parameter value="my_custom_sequence_name"/>