kexi
KexiDB::AlterTableHandler Class Reference
#include <alter.h>
Inheritance diagram for KexiDB::AlterTableHandler:

Detailed Description
A tool for handling altering database table schema.In relational (and other) databases, table schema altering is not an easy task. It may be considered as easy if there is no data that user wants to keep while the table schema is altered. Otherwise, if the table is alredy filled with data, there could be no easy algorithm like: 1. Drop existing table 2. Create new one with altered schema.
Instead, more complex algorithm is needed. To perform the table schema alteration, a list of well defined atomic operations is used as a "recipe".
1. Look at the current data, and: 1.1. analyze what values will be removed (in case of impossible conversion or table field removal); 1.2. analyze what values can be converted (e.g. from numeric types to text), and so on. 2. Optimize the atomic actions knowing that sometimes a compilation of one action and another that's opposite to the first means "do nothing". The optimization is a simulating of actions' execution. For example, when both action A="change field name from 'city' to 'town'" and action B="change field name from 'town' to 'city'" is specified, the compilation of the actions means "change field name from 'city' to 'city'", what is a NULL action. On the other hand, we need to execute all the actions on the destination table in proper order, and not just drop them. For the mentioned example, between actions A and B there can be an action like C="change the type of field 'city' to LongText". If A and B were simply removed, C would become invalid (there is no 'city' field). 3. Ask user whether she agrees with the results of analysis mentioned in 1. 3.2. Additionally, it may be possible to get some hints from the user, as humans usually know more about logic behind the altered table schema than any machine. If the user provided hints about the altering, apply them to the actions list. 4. Create (empty) destination table schema with temporary name, using the information collected so far. 5. Copy the data from the source to destionation table. Convert values, move them between fields, using the information collected. 6. Remove the source table. 7. Rename the destination table to the name previously assigned for the source table.
Notes: The actions 4 to 7 should be performed within a database transaction. [todo] We want to take care about database relationships as well. For example, is a table field is removed, relationships related to this field should be also removed (similar rules as in the Query Designer). Especially, care about primary keys and uniquess (indices). Recreate them when needed. The problem could be if such analysis may require to fetch the entire table data to the client side. Use "SELECT INTO" statments if possible to avoid such a treat.
The AlterTableHandler is used in Kexi's Table Designer. Already opened Connection object is needed.
Use case:
Connection *conn = ... // add some actions (in reality this is performed by tracking user's actions) // Actions 1, 2 will require physical table altering PhysicalAltering // Action 3 will only require changes in kexi__fields // Action 4 will only require changes in extended table schema written in kexi__objectdata AlterTable::ActionList list; // 1. rename the "city" field to "town" list << new ChangeFieldPropertyAction("city", "name", "town") // 2. change type of "town" field to "LongText" << new ChangeFieldPropertyAction("town", "type", "LongText") // 3. set caption of "town" field to "Town" << new ChangeFieldPropertyAction("town", "caption", "Town") // 4. set visible decimal places to 4 for "cost" field << new ChangeFieldPropertyAction("cost", "visibleDecimalPlaces", 4) AlterTableHandler::execute( *conn );
Actions for Alter
Definition at line 111 of file alter.h.
Public Types | |
enum | AlteringRequirements { PhysicalAlteringRequired = 1, DataConversionRequired = 2, MainSchemaAlteringRequired = 4, ExtendedSchemaAlteringRequired = 8, SchemaAlteringRequired = ExtendedSchemaAlteringRequired | MainSchemaAlteringRequired } |
typedef QAsciiDict< ActionBase > | ActionDict |
typedef QIntDict< ActionDict > | ActionDictDict |
typedef QAsciiDictIterator< ActionBase > | ActionDictIterator |
typedef QIntDictIterator< ActionDict > | ActionDictDictIterator |
typedef QPtrVector< ActionBase > | ActionVector |
typedef QPtrList< ActionBase > | ActionList |
typedef QPtrListIterator< ActionBase > | ActionListIterator |
Public Member Functions | |
AlterTableHandler (Connection &conn) | |
virtual | ~AlterTableHandler () |
void | addAction (ActionBase *action) |
AlterTableHandler & | operator<< (ActionBase *action) |
void | removeAction (int index) |
void | clear () |
void | setActions (const ActionList &actions) |
const ActionList & | actions () const |
TableSchema * | execute (const QString &tableName, tristate &result, bool simulate=false) |
void | debug () |
tristate | simulateExecution (const QString &tableName, QString &debugString) |
Protected Member Functions | |
TableSchema * | executeInternal (const QString &tableName, tristate &result, bool simulate=false, QString *debugString=0) |
Protected Attributes | |
Private * | d |
Classes | |
class | ActionBase |
Abstract base class used for implementing all the AlterTable actions. More... | |
class | ChangeFieldPropertyAction |
class | FieldActionBase |
Abstract base class used for implementing table field-related actions. More... | |
class | InsertFieldAction |
Defines an action for inserting a single table field. More... | |
class | MoveFieldPositionAction |
class | RemoveFieldAction |
Defines an action for removing a single table field. More... |
Member Typedef Documentation
typedef QAsciiDict<ActionBase> KexiDB::AlterTableHandler::ActionDict |
typedef QIntDict<ActionDict> KexiDB::AlterTableHandler::ActionDictDict |
typedef QPtrVector<ActionBase> KexiDB::AlterTableHandler::ActionVector |
typedef QPtrList<ActionBase> KexiDB::AlterTableHandler::ActionList |
typedef QPtrListIterator<ActionBase> KexiDB::AlterTableHandler::ActionListIterator |
Member Enumeration Documentation
Defines flags for possible altering requirements; can be combined.
- Enumerator:
Member Function Documentation
void AlterTableHandler::addAction | ( | ActionBase * | action | ) |
AlterTableHandler & AlterTableHandler::operator<< | ( | ActionBase * | action | ) |
void AlterTableHandler::removeAction | ( | int | index | ) |
void AlterTableHandler::clear | ( | ) |
void AlterTableHandler::setActions | ( | const ActionList & | actions | ) |
Sets actions for the alter table tool. Previous actions are cleared. actions will be owned by the AlterTableHandler object.
const AlterTableHandler::ActionList & AlterTableHandler::actions | ( | ) | const |
TableSchema * AlterTableHandler::execute | ( | const QString & | tableName, | |
tristate & | result, | |||
bool | simulate = false | |||
) |
Performs table alteration using predefined actions for table named tableName, assuming it already exists. The Connection object passed to the constructor must exist, must be connected and a database must be used. The connection must not be read-only.
If simulate is true, the execution is only simulated, i.e. al lactions are processed like for regular execution but no changes are performed physically. THis mode is used only for debugging purposes.
- Todo:
- For some cases, table schema can completely change, so it will be needed to refresh all objects depending on it. Implement this!
- Returns:
- the new table schema object created as a result of schema altering. The old table is returned if recreating table schema was not necessary or simulate is true. 0 is returned if result is not true.
tristate AlterTableHandler::simulateExecution | ( | const QString & | tableName, | |
QString & | debugString | |||
) |
TableSchema * AlterTableHandler::executeInternal | ( | const QString & | tableName, | |
tristate & | result, | |||
bool | simulate = false , |
|||
QString * | debugString = 0 | |||
) | [protected] |
Member Data Documentation
Private* KexiDB::AlterTableHandler::d [protected] |
The documentation for this class was generated from the following files: