>> Table of Contents >> Article
<< Functions Index Purpose of the SML format >>

ChangeLog

This section defines the syntax of all elements required to keep track of any significant changes made to the database, which require an update of the physical structure of the database. This includes newly created, renamed, modified and dropped database objects. SQL-statements may be provided for any additional action, which is not covered by this definition. Implementations may provide functionality to generate valid SQL-statements to automatically update a given database to a later version of the XDDL document. he change-log should provide any information, that is necessary, to perform such an action.

Element changelog

  ELEMENT changelog (create|rename|drop|update|sql)*
Description

The changelog element of a database definition is meant to document updates. Updates must be sorted by version number in descending order. This means, that the first element is always the most recent update.
The updates contain the type of the modification, a version number and the subject of modification. A description of the changes may be added as PCDATA.

Implementation

The changelog may be used for automated database updates. The implementation may provide an application that scans the changelog and updates the database schema from a given version number to a later version. This implementation should try to execute all changes within a transaction. In case of a nonrecoverable error it should try to rollback all changes.

Element create

  ELEMENT create (#PCDATA)
  ATTRIBUTE
       name        string
       subject     string
       version     string
       ignoreError bool
Attributes
Attributes Type Mandatory Default Description
name string yes n/a Name identifier of the changed object. It should be lowercased and a valid XML and SQL identifier.
subject string yes n/a table | column | index | view | sequence | trigger | constraint
version string - n/a The version this log-entry applies to.
ignoreError bool - no Used to tell the handler function, which performs the update, how to react, if this step causes an error while updating the database structure. If the value is set to "yes", the database update should continue, even if this step fails. If set to "no", the update should stop and all previous changes should be rolled back.
Description

Documents the creation of a new database element. The type of element is stored as attribute "subject". The element itself is identified via the attribute "name". The name must specify a unique identifier for the element. Where necessary it must specify the namespaces, within which the element's name is unique. In that case the character '.' must be used as a delimiter. The implementation may throw an error if the element is not found or if it is ambiguous. The PCDATA section of the element may be used for documentation purposes and may contain any text.

Element rename

  ELEMENT rename EMPTY
  ATTRIBUTE
       name        string
       subject     string
       version     string
       ignoreError bool
       oldname     string
Attributes
Attributes Type Mandatory Default Description
name string yes n/a Name identifier of the changed object. It should be lowercased and a valid XML and SQL identifier.
subject string yes n/a table | column | index | view | sequence | trigger | constraint
version string - n/a The version this log-entry applies to.
ignoreError bool - no Used to tell the handler function, which performs the update, how to react, if this step causes an error while updating the database structure. If the value is set to "yes", the database update should continue, even if this step fails. If set to "no", the update should stop and all previous changes should be rolled back.
oldname string - n/a Previous name of the renamed object. Note: For columns the name must include the table ("table.column").
Description

Documents renaming an existing database element. The type of element is stored as attribute "subject". The element itself is identified via the attribute "name". The previous name of the element is stored as the attribute "oldname". The name must specify a unique identifier for the element. Where necessary it must specify the namespaces, within which the element's name is unique. In that case the character '.' must be used as a delimiter. The implementation may throw an error if the element is not found or if it is ambiguous. The PCDATA section of the element may be used for documentation purposes and may contain any text.

Element drop

  ELEMENT drop EMPTY
  ATTRIBUTE
       name        string
       subject     string
       version     string
       ignoreError bool
Attributes
Attributes Type Mandatory Default Description
name string yes n/a Name identifier of the changed object. It should be lowercased and a valid XML and SQL identifier.
subject string yes n/a table | column | index | view | sequence | trigger | constraint
ignoreError bool - no Used to tell the handler function, which performs the update, how to react, if this step causes an error while updating the database structure. If the value is set to "yes", the database update should continue, even if this step fails. If set to "no", the update should stop and all previous changes should be rolled back.
version string - n/a The version this log-entry applies to.
Description

Documents that an existing database element has been removed. The type of element is stored as attribute "subject". The element itself is identified via the attribute "name". The name must specify a unique identifier for the element. Where necessary it must specify the namespaces, within which the element's name is unique. In that case the character '.' must be used as a delimiter. The implementation may throw an error if the element is not found or if it is ambiguous. The PCDATA section of the element may be used for documentation purposes and may contain any text.

A typical situation where you might want to set the attribute "ignoreError" to "yes" is when dropping an element. Usually a database update should not fail, just because an element can't be drop because it doesn't exist (anymore).

Note that some DBMS are unable to rollback dropped database elements. In case of an error this restriction may have influence on the behavior of an implementation that updates the database structure.

Element update

  ELEMENT update EMPTY
  ATTRIBUTE
       name        string
       subject     string
       version     string
       ignoreError bool
       property    string
       value       string
       oldvalue    string
Attributes
Attributes Type Mandatory Default Description
name string yes n/a Name identifier of the changed object. It should be lowercased and a valid XML and SQL identifier.
subject string yes n/a table | column | index | view | sequence | trigger | constraint
version string - n/a The version this log-entry applies to.
ignoreError bool - no Used to tell the handler function, which performs the update, how to react, if this step causes an error while updating the database structure. If the value is set to "yes", the database update should continue, even if this step fails. If set to "no", the update should stop and all previous changes should be rolled back.
property string - n/a Specifies which property of the object has been updated.
value string - n/a New value of the updated property. The syntax of this attribute may be defined by the implementation. It may be a serialized string.
oldvalue string - n/a Old value of the property that has changed. The syntax of this attribute may be defined by the implementation. It may be a serialized string.
Description

Documents the alteration of an existing database element. The type of element is stored as attribute "subject". The element itself is identified via the attribute "name". The name must specify a unique identifier for the element. Where necessary it must specify the namespaces, within which the element's name is unique. In that case the character '.' must be used as a delimiter. The implementation may throw an error if the element is not found or if it is ambiguous. The PCDATA section of the element may be used for documentation purposes and may contain any text. Where available the modified "property" plus it's "oldvalue" and new "value" may be defined.

Element sql

  ELEMENT sql EMPTY
  ATTRIBUTE
       version     string
       ignoreError bool
       dbms        string
Attributes
Attributes Type Mandatory Default Description
dbms string - generic The name of the target DBMS. The value "generic" means that the definition is suitable for any DBMS. Usually this is used as a fall-back option for DBMS you haven't thought of when creating the database structure or for those that simply doesn't have the feature in question.
version string - n/a The version this log-entry applies to.
ignoreError bool - no Used to tell the handler function, which performs the update, how to react, if this step causes an error while updating the database structure. If the value is set to "yes", the database update should continue, even if this step fails. If set to "no", the update should stop and all previous changes should be rolled back.
Description

Documents a custom SQL statement that is to be executed. It's execution may be limited to a certain DBMS. SQL-statements may be provided for any additional action, which is not covered by the other elements of this definition. For example, to copy data to a newly created table. The PCDATA section of the element must contain the SQL code which also serves as documentation.

<< Functions Index Purpose of the SML format >>

Author: Thomas Meyer, www.yanaframework.net