kexi

KexiDB::AlterTableHandler Class Reference

#include <alter.h>

Inheritance diagram for KexiDB::AlterTableHandler:

KexiDB::Object

List of all members.


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< ActionBaseActionDict
typedef QIntDict< ActionDictActionDictDict
typedef QAsciiDictIterator
< ActionBase
ActionDictIterator
typedef QIntDictIterator
< ActionDict
ActionDictDictIterator
typedef QPtrVector< ActionBaseActionVector
typedef QPtrList< ActionBaseActionList
typedef QPtrListIterator
< ActionBase
ActionListIterator

Public Member Functions

 AlterTableHandler (Connection &conn)
void addAction (ActionBase *action)
AlterTableHandleroperator<< (ActionBase *action)
void removeAction (int index)
void clear ()
void setActions (const ActionList &actions)
const ActionListactions () const
TableSchemaexecute (const QString &tableName, ExecutionArguments &args)
void debug ()

Static Public Member Functions

static int alteringTypeForProperty (const QCString &propertyName)

Protected Attributes

Private * d

Classes

class  ActionBase
 Abstract base class used for implementing all the AlterTable actions. More...
class  ChangeFieldPropertyAction
class  ExecutionArguments
 Arguments for AlterTableHandler::execute(). More...
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

for collecting actions related to a single field

Definition at line 143 of file alter.h.

for collecting groups of actions by field UID

Definition at line 145 of file alter.h.

for collecting actions related to a single field

Definition at line 148 of file alter.h.

Defines a type for action list.

Definition at line 151 of file alter.h.

Defines a type for action list's iterator.

Definition at line 154 of file alter.h.


Member Enumeration Documentation

Defines flags for possible altering requirements; can be combined.

Enumerator:
PhysicalAlteringRequired  Physical table altering is required; e.g. ALTER TABLE ADD COLUMN.
DataConversionRequired  Data conversion is required; e.g. converting integer values to string after changing column type from integer to text.
SchemaAlteringRequired  Convenience flag, changes to the main or extended schema is required.

Definition at line 120 of file alter.h.


Member Function Documentation

void AlterTableHandler::addAction ( ActionBase action  ) 

Appends action for the alter table tool.

Definition at line 747 of file alter.cpp.

AlterTableHandler & AlterTableHandler::operator<< ( ActionBase action  ) 

Provided for convenience,

See also:
addAction(const ActionBase& action).

Definition at line 752 of file alter.cpp.

void AlterTableHandler::removeAction ( int  index  ) 

Removes an action from the alter table tool at index index.

Definition at line 763 of file alter.cpp.

void AlterTableHandler::clear (  ) 

Removes all actions from the alter table tool.

Definition at line 768 of file alter.cpp.

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.

Definition at line 773 of file alter.cpp.

const AlterTableHandler::ActionList & AlterTableHandler::actions (  )  const

Returns:
a list of actions for this AlterTable object. Use ActionBase::ListIterator to iterate over the list items.

Definition at line 758 of file alter.cpp.

TableSchema * AlterTableHandler::execute ( const QString &  tableName,
ExecutionArguments args 
)

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 args.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!
Sets args.result to true on success, to false on failure or when the above requirements are not met (then, you can get a detailed error message from KexiDB::Object). When the action has been cancelled (stopped), args.result is set to cancelled value. If args.debugString is not 0, it will be filled with debugging output.
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 args.simulate is true. 0 is returned if args.result is not true.

Todo:
err msg?

Todo:
err msg?

Todo:
err msg?

Todo:
err msg?

copy id

Todo:
better errmsg?

Todo:
delete newTable...

Todo:
support expressions (eg. TODAY()) as a default value
Todo:
this field can be notNull or notEmpty - check whether the default is ok (or do this checking also in the Table Designer?)

Todo:
support unique, validatationRule, unsigned flags...
Todo:
check for foreignKey values...

Todo:
delete newTable...

Todo:
delete newTable...

Todo:
delete newTable...

Definition at line 785 of file alter.cpp.

void AlterTableHandler::debug (  ) 

Displays debug information about all actions collected by the handler.

Definition at line 778 of file alter.cpp.

int AlterTableHandler::alteringTypeForProperty ( const QCString &  propertyName  )  [static]

Like execute() with simulate set to true, but debug is directed to debugString. This function is used only in the alter table test suite.

Helper.

Returns:
a combination of AlteringRequirements values decribing altering type required when a given property field's propertyName is altered. Used internally AlterTableHandler. Moreover it can be also used in the Table Designer's code as a temporary replacement before AlterTableHandler is fully implemented. Thus, it is possible to identify properties that have no PhysicalAlteringRequired flag set (e.g. caption or extended properties like visibleDecimalPlaces.

Definition at line 116 of file alter.cpp.


Member Data Documentation

Private* KexiDB::AlterTableHandler::d [protected]

for future extensions

Reimplemented from KexiDB::Object.

Definition at line 463 of file alter.h.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys