migration - packet
This topic discusses the migration packet API.
- All migration packets must be derived from the
BasePacketclass for the framework to execute them.- There are several specialized subclasses which facilitate certain types of migration
Classes
BasePacket
Methods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
BasePacket.__init__(self, migrationrule=None) | migrationrule: UUID | Initializes a new packet. If a packet is instanced without a uuid, not all features might work | |
BasePacket.create_migrationrule(self, override_dict=None) | override_dict: A dictionary of attributes to pass to ppms.create_record | The newly created UUID | Creates a record in table 314 for this migration packet and update the internal state of this instance so that further calls like save_history work |
BasePacket.delete(self) | Deletes this migration packet and all history records | ||
BasePacket.delete_log_content(self) | Deletes the currently buffered log and reset the internal logging buffer. This will not delete any logs saved to the database. | ||
BasePacket.fail(self, reason='') | reason: A text that describes why the packet failed | Updates the internal state of the packet to mark it as failed. Please note that this does not stop the execution of this migration packet and should always be used with a return | |
BasePacket.fix(self, packet_runner) | packet_runner: The instance of the migration framework that is running this packet | This method is called by the framework and should contain the code which this packet is supposed to run to migrate the system | |
BasePacket.generate_logfile_name(self) | A name that can be used as a logfile name | Generates a logfile name from the parameters of the packet | |
BasePacket.get_dependencies(self) | A list of dependencies | This method is called by the framework and should return the dependencies of this packet | |
BasePacket.log(self, text) | text: Log message | Log a message | |
BasePacket.log_heading(self, text, level=0) | text: Log message level: A number between 0 and 4 | Writes a heading in the log. Headings are marked by stars around the text. A value of 0 puts 5 stars around the text, a value of 4 puts 1 star around the text | |
BasePacket.make_active(self) | Called by the framework before execution to initialize the packet logging correctly | ||
BasePacket.mark_as_done(self) | Sets the Completed flag to True | ||
BasePacket.mark_as_undone(self) | Sets the Completed flag to False | ||
BasePacket.pending(self) | Sets the packet state to pending. Please note that this does not stop the execution of this migration packet and should always be used with a return | ||
BasePacket.rollback(self) | This method is called by the framework when a packet fails, so that it can gracefully undo any incomplete changes made to the system. The default implementation simply logs that no rollback action was defined | ||
BasePacket.save_history(self) | True or False | Creates a new history record in table 315 based on the current execution. The content of the log is written into a hyperlink and the current internal state is saved to Status | |
BasePacket.skip(self, reason='') | reason: A text that describes why this packet was skipped | Deprecated | |
BasePacket.success(self) | This method must be called after a packet has migrated the system successfully. Please note that this does not stop the execution of this migration packet and should always be used with a return | ||
BasePacket.unnecessary(self) | Marks the packet as unnecessary for the current migration. Please note that this does not stop the execution of this migration packet and should always be used with a return |
Classmethods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
BasePacket.from_packet_path(cls, packet_path) | packet_path: Python path | The packet instance or None | Search for the migration packet class, initialize it, and set the uuid accordingly |
Properties
| Property | Getter | Setter | Description |
|---|---|---|---|
| BasePacket.__fpath__ | Returns the path that is saved to Python path | ||
| BasePacket.__name__ | The name of the packet class | ||
| BasePacket.component | Fetches the component of the package that contains the migration packet | ||
| BasePacket.customizing_dependencies_are_met | Returns wheter the MinVersionDependency and MaxVersionDependency dependencies attached to this packet are met | ||
| BasePacket.dbms_dependency_is_met | Returns wheter the DBMSDependency attached to this packet is met | ||
| BasePacket.dependencies | Returns all dependencies of this packet as an iterable oject | ||
| BasePacket.dependencies_are_met | Returns whether all dependencies are met | ||
| BasePacket.description_long | Returns the entire docstring | ||
| BasePacket.description_short | Returns the first sentence of the docstring | ||
| BasePacket.done | Returns and sets to Completed. Note that setting the flag will write log messages to the packets internal logging buffer | ||
| BasePacket.is_failed_or_still_open | Returns if the last_state is one of PacketState.PENDING, PacketState.SKIPPED or PacketState.FAILED | ||
| BasePacket.last_state | Returns the PacketState of the last execution. If the packet has never been executed, PacketState.NEW is returned | ||
| BasePacket.log_content | Returns the content of the internal logging buffer | ||
| BasePacket.logfile_suffix | The file ending for the logfile hyperlink | ||
| BasePacket.maximum_customizing_dependency | Returns the expected version of a MaxVersionDependency attached to this packet or an empty string | ||
| BasePacket.maximum_customizing_dependency_is_met | Returns whether the MaxVersionDependency is met | ||
| BasePacket.migrationrule | UUID | ||
| BasePacket.minimum_customizing_dependency | Returns the expected version of a MinVersionDependency attached to this packet or an empty string | ||
| BasePacket.minimum_customizing_dependency_is_met | Returns wheter the MinVersionDependency is met | ||
| BasePacket.packet_dependencies_are_met | Returns whether all PacketDependency instances are met | ||
| BasePacket.pythonpath | Python path | ||
| BasePacket.release | Gets the release from the package this migration packet is part of | ||
| BasePacket.release_version | release converted to a LooseVersion | ||
| BasePacket.twiki_url | Returns the url to the ReleaseNotes topic where this packet is described |
SucceedOldPacket
SucceedOldPacket provides a method for easily setting the Erledigt flag on other packets.
- It is used to mark packets which are superseded by a more recent packet as done, regardless of whether they succeeded before or not
Methods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
SucceedOldPacket.mark_packet_as_done(self, packet_path) | packet_path: The Python path of a packet | True | Marks the packet with the specified Python path as done. If no packet with that path exists, no error will be raised |
ChangeDTPPacket
ChangeDTPPacket provides methods for changing values on dtp level
- All methods log intensively to assist with debugging
Methods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
ChangeDTPPacket.change_value(self, record, attribute, old_value, new_value) | record: A DtpRecord instanceattribute: The python id of the attribute to change old_value: The value you expect the data item to have new_value: The value the data item should be set to | True or False | Changes a value on a data item if the system matches the expected state. This method returns True if the value was changed successfully or if the data item already has the desired new_value. False is returned when the old_value does not match or if the data item could not be changed. If you pass None as old_value, no check will be performed. |
ChangeDTPPacket.get_record(self, dt_num, key_list, di_list) | dt_num: DT key_list: List of keys di_list: List of data items | DtpRecord or None | A wrapper around ppms.search_record that logs to the migration packet |
ChangeDTPPacket.verify_value(self, record, attribute, value) | record: DtpRecordattribute: Python id of the attribute to check value: The expected value | True or False | Verifies that a dataitem matches a certain ex |
SQLPacket
The SQLPacket is designed to execute sql files and make changes to the database
select_and_log()andmodify_and_log()should be used over callingdb_select()anddb_modify()directly, as theSQLPacketmethods provide useful logging
Methods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
SQLPacket.apply_dml_file(self, sql_dialect, filename, split=True, separator=;$) | sql_dialect: 'dbms' or 'ansi' filename: Filename split: True or False separator: A regular expression to determine how to split the statements in the file | Applies an sql file from the current folder to the database. The sql files should have a suffix like _oracle, _mssql or _ansi but this method must be called without the suffix. Based on the sql_dialect parameter, the correct suffix is added and the file is parsed. When split is True, the separator is used to split the file content and then all statements are executed.Autocommit is disabled and then all statements are executed before committing to the database. If an error is encountered in the course of this, db_rollback() will be called. | |
SQLPacket.apply_fix_ddl_file(self, sql_dialect, filename, split=False, separator=;$) | sql_dialect: 'dbms' or 'ansi' filename: Filename split: True or False separator: A regular expression to determine how to split the statements in the file | Works like apply_dml_file, except that the autocommit state is not changed | |
SQLPacket.get_queries_from_file(self, file_path, encoding=utf-8, split=True, separator=;$) | file_path: The path to a file containing SQL statements encoding: The encoding of the file split: True or False separator: A regular expression to determine how to split the statements in the file | A list of statements | Reads the file at the given path and extract the queries. When split is False, a list with only 1 statement is returned |
SQLPacket.get_sql_file_path(self, sql_dialect, filename) | sql_dialect: 'dbms' or 'ansi' filename: Filename | Filename with added suffix | Returns the path to the given file name with an added suffix |
SQLPacket.select_and_log(self, query, log_rows=True) | query: A select statement log_rows: True or False | Result of the select | Logs and executes a select. When log_rows is True, the number of rows selected is also logged |
Staticmethods
| Function | Parameters | Return Value | Description |
|---|---|---|---|
SQLPacket.alter_precision_of_numeric_column(table_name, column_name, desired_precision, expected_precision=None) | table_name: Variable name column_name: SQL-ID desired_precision: The precision the column should have expected_precision: The precision the column currently has | True or False | Alters the precision of a numeric column. When expected_precision is given and does not match, nothing will be changed. |
SQLPacket.column_allows_null(table_name, column_name) | table_name: Variable name column_name: SQL-ID | True or False | Checks whether a column allows Null values |
SQLPacket.column_exists(table_name, column_name) | table_name: Variable name column_name: SQL-ID | True or False | Checks whether a column exists |
SQLPacket.columns_have_index_already(table_name, column_names) | table_name: Variable name column_names: List of SQL-ID | True or False | Checks whether a bunch of columns have an index spanning across them |
SQLPacket.constraint_exists(table_name, constraint_name) | table_name: Variable name constraint_name: Name of the constraint | True or False | Checks whether a constraint exists |
SQLPacket.drop_column(table_name, column_name, remove_customizing=False) | table_name: Variable name column_name: SQL-ID remove_customizing: True or False | Drops a column. Returns True if the column was dropped or does not exist.When remove_customizing is True, the data item that was associated with this table/column pair is identified and removed from all customizing tables. This includes data fields, exits, sub data items and the data item itself. | |
SQLPacket.drop_constraint(table_name, constraint_name) | table_name: Variable name constraint_name: Name of the constraint | Drops a constraint if it exists | |
SQLPacket.drop_index(table_name, index_name) | table_name: Variable name index_name: Name of the index | Drops a index if it exists | |
SQLPacket.get_char_length_of_varchar_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | Maximum number of characters | Gets the maximum number of characters for a varchar column. |
SQLPacket.get_column_type(table_name, column_name) | table_name: Variable name column_name: SQL-ID | A column type like 'NUMERIC' or 'NUMBER' | Gets the column type of the given column in upper case |
SQLPacket.get_constraints_of_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | List of constraint names | Gets the constraints of the column |
SQLPacket.get_default_value_for_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | Default value or None | Gets the default value of a column. Returns None if the table/column does not exist.This is currently only implemented for Oracle! |
SQLPacket.get_indices_of_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | List of index names | Gets the indices this column is used in |
SQLPacket.get_precision_and_scale_of_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | Tuple of (precision, scale) | Gets the column precision and scale if applicable |
SQLPacket.get_varchar_column_type(table_name, column_name) | table_name: Variable name column_name: SQL-ID | 'B' or 'C' | Gets the varchar column type. Returns B for bytes and C for char. This is currently only implemented for Oracle! |
SQLPacket.index_exists(table_name, index_name) | table_name: Variable name index_name: SQL name | True or False | Checks whether a given index exists |
SQLPacket.is_nullable(table_name, column_name) | table_name: Variable name column_name: SQL-ID | True or False | Checks whether a column allows null values. Returns None if the table/column pair does not exist |
SQLPacket.modify_and_log(query, log_rows=True) | query: Sql statement log_rows: True or False | Number of rows affected | Executes an sql statement on the database. If log_rows is True then the number of rows modified is logged. |
SQLPacket.move_table_to_different_schema(table_number, source_schema, target_schema) | table_number: DT source_schema: DB-Schema target_schema: DB-Schema | True | Moves a table to a different schema. If the table has hyperlinks, this will raise a NotImplementedError. Translations will be ported automatically, but the method was written to only support Q5B as a target schema for now. If the table has no translations, the schema will not be changed. |
SQLPacket.object_is_materialized_view(object_name) | object_name: SQL name | True or False | Checks whether a materialized view with the given name exists. Note that materialized views do not exist in MSSQL. |
SQLPacket.object_is_table(object_name) | object_name: SQL name | True or False | Checks whether a table with the given object name exists |
SQLPacket.procedure_exists(procedure_name) | procedure_name: SQL name | True or False | Checks whether a given procedure exists. This is currently only implemented for MSSQL! |
SQLPacket.remove_constraints_from_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | Removes all constraints from the column | |
SQLPacket.remove_customizing_for_column(table_name, column_name) | table_name: Variable name column_name: SQL-ID | True or False | Removes all customizing records that use the dataitem associated with the table/column pair. |
SQLPacket.table_exists(table_name) | table_name: Variable name | True or False | Checks whether a table with the given object name exists |
SQLPacket.rename_table(old_table_name, new_table_name) | old_table_name: Variable name new_table_name: New table name | True or False | Renames a table on the database. |
SQLPacket.rename_column(table_name, old_column_name, new_column_name) | table_name: Variable name old_column_name: SQL-ID new_column_name: New column name | True or False | Renames a column in a table. |