migration - packet

This topic discusses the migration packet API.

All migration packets must be derived from the BasePacket class 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` instance attribute: 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: `DtpRecord` attribute: 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() and modify_and_log() should be used over calling db_select() and db_modify() directly, as the SQLPacket methods 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.