The documentation from version 39.5.17 of PLANTA project can be found in the new PLANTA Online Help.

migration - Packets

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   Initialize 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 Create a record in table 314 for this migration packet and update the internal state of this instance so further calls like save_history work
BasePacket.delete(self)     Delete this migration packet and all history records
BasePacket.delete_log_content(self)     Delete the currently buffered log and reset the internal logging buffer. This won't delete any logs saved to the database.
BasePacket.fail(self, reason='') reason: A text that describes why the packet failed   Update 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 that 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 Generate 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 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__ Checked Unchecked Returns the path that is saved to Python path
BasePacket.__name__ Checked Unchecked The name of the packet class
BasePacket.component Checked Unchecked Fetches the component of the package that contains the migration packet
BasePacket.customizing_dependencies_are_met Checked Unchecked Returns wheter the MinVersionDependency and MaxVersionDependency dependencies attached to this packet are met
BasePacket.dbms_dependency_is_met Checked Unchecked Returns wheter the DBMSDependency attached to this packet is met
BasePacket.dependencies Checked Unchecked Returns all dependencies of this packet as an iterable oject
BasePacket.dependencies_are_met Checked Unchecked Returns if all dependencies are met
BasePacket.description_long Checked Unchecked Returns the entire docstring
BasePacket.description_short Checked Unchecked Returns the first sentence of the docstring
BasePacket.done Checked Checked 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 Checked Unchecked Returns if the last_state is one of PacketState.PENDING, PacketState.SKIPPED or PacketState.FAILED
BasePacket.last_state Checked Unchecked Returns the PacketState of the last execution. If the packet was never executed, PacketState.NEW is returned
BasePacket.log_content Checked Unchecked Return the content of the internal logging buffer
BasePacket.logfile_suffix Checked Unchecked The file ending for the logfile hyperlink
BasePacket.maximum_customizing_dependency Checked Unchecked Returns the expected version of a MaxVersionDependency attached to this packet or an empty string
BasePacket.maximum_customizing_dependency_is_met Checked Unchecked Returns wheter the MaxVersionDependency is met
BasePacket.migrationrule Checked Checked UUID
BasePacket.minimum_customizing_dependency Checked Unchecked Returns the expected version of a MinVersionDependency attached to this packet or an empty string
BasePacket.minimum_customizing_dependency_is_met Checked Unchecked Returns wheter the MinVersionDependency is met
BasePacket.packet_dependencies_are_met Checked Unchecked Returns wheter all PacketDependency instances are met
BasePacket.pythonpath Checked Unchecked Python path
BasePacket.release Checked Unchecked Get the release from the package this migration packet is part of
BasePacket.release_version Checked Unchecked release converted to a LooseVersion
BasePacket.twiki_url Checked Unchecked Returns the url to the ReleaseNotes topic where this packet is described

SucceedOldPacket

SucceedOldPacket provides a method for easily setting the Completed flag on other packets.

  • It is used to mark packets which are superseded by a newer packet as done, regardless of if 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 Mark the packet with the specified Python path as done. If no packet with that path exists, no error is 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 dataitem to have
new_value: The value the dataitem should be set to
True or False Changes a value on a dataitem if the system matches the expected state. This method returns True if the value was changed successfully or the dataitem already has the desired new_value. False is returned when the old_value does not match or the dataitem could not be changed. When you pass None as old_value no check is performed.
ChangeDTPPacket.get_record(self, dt_num, key_list, di_list) dt_num: DT
key_list: List of keys
di_list: List of dataitems
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 Verify that a dataitem matches a certain expected state

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 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 during this, db_rollback() is 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 the autocommit state isn't 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 Read 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 filename with an added suffix
SQLPacket.select_and_log(self, query, log_rows=True) query: A select statement

log_rows: True or False
The result of the select Log and execute a select. When log_rows is True, the amount 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 Alter the precision of a numeric column. When expected_precision is given and doesn't match, nothing is changed.
SQLPacket.column_allows_null(table_name, column_name) table_name: Variable name
column_name: SQL-ID
True or False Check if a column allows Null values
SQLPacket.column_exists(table_name, column_name) table_name: Variable name
column_name: SQL-ID
True or False Check if 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 Check if 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 Check if 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
  Drop a column. Returns True if the column was dropped or doesn't exist.
When remove_customizing is True, the DataItem that was associated with this table/column pair is determined and removed from all customizing tables. This includes datafields, exits, sub dataitems and the dataitem itself.
SQLPacket.drop_constraint(table_name, constraint_name) table_name: Variable name
constraint_name: Name of the constraint
  Drop a constraint if it exists
SQLPacket.drop_index(table_name, index_name) table_name: Variable name
index_name: Name of the index
  Drop 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 amount of characters Get the maximum amount 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' Get 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 Get 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 Get the default value of a column. Returns None if the table/column doesn't 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 Get 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) Get 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' Get 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 Check if a given index exists
SQLPacket.is_nullable(table_name, column_name) table_name: Variable name
column_name: SQL-ID
True or False Check if a column allows null values. Returns None if the table/column pair doesn't exist
SQLPacket.modify_and_log(query, log_rows=True) query: Sql statement

log_rows: True or False
Amount of rows affected Execute an sql statement on the database. If log_rows is True then the amount 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 Move 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 won't be changed.
SQLPacket.object_is_materialized_view(object_name) object_name: SQL name True or False Check if 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 Check if a table with the given object name exists
SQLPacket.procedure_exists(procedure_name) procedure_name: SQL name True or False Check if 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 Remove 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 Check if 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 Rename 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 Rename a column in a table.

         PLANTA project









 
  • Suche in Topic-Namen

  • Suche in Topic-Inhalten
This site is powered by the TWiki collaboration platform Powered by Perl