Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Database Policy

This document details the normative requirements for use of the relational database systems in Qt Extended and should be read in conjunction with the Database Specification which contains background information for these policies. The development of applications or use of the relational database systems other than in compliance with this policy is not supported.

Database Schema Modification and Creation

Database Schema Modification and Creation

To modify the the Qt Extended database system a number of rules must be followed for each database element.

For example, TABLE, must have a Unique Prefix constructed using the following steps:

Using the full company or organization URL (for example, example.com) follow these steps:

reverse the order of the sections separated by periods: com.example
replace the periods with an underscore character: com_example
append an underscore character: com_example_

resulting in a Unique Prefix for example.com of: com_example_

The following table provides the normative requirements for each rule and a brief description of the rule.

Note:

The term the schema refers to the Qt Extended schema implementation as described in the Database Specification.
The term unique_prefix_ should be replaced with the constructed Unique Prefix.

Normative Rule	Explanation
Avoid modifying the schema	Create a custom database with code such as: CREATE DATABASE unique_prefix_some_database There are both positives and negatives to this scenario. The positives are that your database wil not be subject to system wide upgrades to the database system. This will allow you complete control over your data lifetime. The negatives are that your data will not be included in system data backups and restores, and as such you are responsible for providing for the safety and security of your own data.
Avoid modifying existing tables.	Create a custom table with code such as: CREATE TABLE unique_prefix_some_table (...) Use a foreign key into the table whose data is required to be referenced so that that table does not need to be altered. The system tables controlled by the Qt Extended development team should be classed as untouchable for several reasons. The foremost being that the only field we guarantee to exist will be the key field. Key fields for information will not be modified when the record is modified, so you can base your own custom data storage upon these keys. Referential integrity is not guaranteed on all database platforms, so you must also make sure to handle foreign key constraints in your application (ie, rows may be added/dissapear outside of your control, you should code to handle this).
Do not modify or add columns to system tables.	Use the string attribute tables, for example, the `*custom` tables in `PIM` or the `contentProps` table in `Content`. See QContent::property() for information on how to access this table. These tables have been designed to allow quick and easy extension to the system information. If this suits your design, you are free and encouraged to use them.
Do not delete or modify column definitions.	Breaking this rule may prevent version migration scripts from working. The overhead of having a column empty is preferable to breaking compatibility. Create a new column with the desired information, for example: ALTER TABLE qtopia_table ADD COLUMN unique_prefix_old_col INT; UPDATE qtopia_table SET unique_prefix_old_col=old_col\|\|'_new_data'; Columns should not be removed between minor releases (ie, 4.16->4.17) to ensure backwards compatibility. Between major releases (ie, 4.16->4.20), a database migration script should be supplied if migration is necessary, otherwise a straight table to table copy will be invoked. When handling database per-media, if a prior major-revision database is available upon the card, it will be considered read-only, and modifications will be stored sideways in a version-numbered database with the original database left intact (so that if for example, an SD-Card is inserted into an older version device, the original data will still continue to work as designed).
Do not remove or alter `INDEXES`.	This can change the way existing queries work in subtle and hard-to-debug ways. If a particular query requires a new method to sort data, consider setting up a new table and importing the data, or performing the query with a sub-select or temporary table.
Do not to modify the existing schema for new functionality.	Research the problem to see if another way can be found. If at all possible in the design phase, take into account the fact that extra data may be needed at a later date, or by another application. Adding a facility to your tables and code to store data tied by keys to the original information will save you a lot of extra work in the long run.
Create a consistent primary key field.	If there is a chance that third parties will be using your data to reference too, create a primary key field. This will allow third party developers to include/reference your data in their own tables and applications without the need to modify your table directly, reducing the chance of the table being in a previously unforseen state. While the row exists in a valid form, every effort should be made to keep this key consistent as much as possible to facilitate referential integrity by 3rd parties.

Trademarks

Qt Extended 4.4.3