Inheritance diagram for Drupal\tripal_chado\Task\ChadoUpgrader:

[legend]

Collaboration diagram for Drupal\tripal_chado\Task\ChadoUpgrader:

[legend]

Public Member Functions
	__construct (?\Drupal\Core\Database\Connection $database=NULL, ?\Psr\Log\LoggerInterface $logger=NULL, ?\Drupal\tripal_biodb\Lock\SharedLockBackendInterface $locker=NULL, ?\Drupal\Core\State\StateInterface $state=NULL)

	validateParameters ()

	performTask ()

	getProgress ()

	getStatus ()

Public Member Functions inherited from Drupal\tripal_chado\Task\ChadoTaskBase
	getTripalDbxClass ($class)

Public Member Functions inherited from Drupal\tripal_biodb\Task\BioTaskBase
	__construct (?\Drupal\Core\Database\Connection $database=NULL, ?\Psr\Log\LoggerInterface $logger=NULL, ?\Drupal\tripal_biodb\Lock\SharedLockBackendInterface $locker=NULL, ?\Drupal\Core\State\StateInterface $state=NULL)

	setParameters (array $parameters=[])

	getId ()

	getLogger ()

Public Attributes
const	TASK_NAME = 'upgrader'

const	DEFAULT_CHADO_VERSION = '1.3'

const	CHADO_REF_SCHEMA_13 = '_chado_13_template'

const	CHADO_OBJECT_PRIORITY_13

Public Attributes inherited from Drupal\tripal_chado\Task\ChadoTaskBase
const	TASK_NAME = 'chado'

Public Attributes inherited from Drupal\tripal_biodb\Task\BioTaskBase
const	TASK_NAME = 'task'

const	STATE_KEY_DATA_PREFIX = 'tripal_biodb_'

Protected Member Functions
	setProgress (float $value)

	setupReferenceSchema ()

	prepareDropColumnDefaults ()

	prepareDropFunctions ()

	prepareDropAllViews ()

	prepareUpgradeTypes ()

	prepareUpgradeSequences ()

	preparePrototypeFunctions ()

	prepareUpgradeTables ()

	prepareSequenceAssociation ()

	prepareUpgradeViews ()

	prepareFunctionUpgrade ()

	prepareAggregateFunctionUpgrade ()

	prepareUpgradeTableDefauls ()

	prepareCommentUpgrade ()

	reinitSchema ()

	processUpgradeQueries ()

Protected Member Functions inherited from Drupal\tripal_biodb\Task\BioTaskBase
	prepareSchemas (array $schema_list)

	getSchemaLockName (\Drupal\tripal\TripalDBX\TripalDbxConnection $db)

	initId ()

	acquireTaskLocks ()

	releaseTaskLocks ()

Protected Attributes
	$upgradeQueries

	$bioTool

	$tripalDbxApi = NULL

Protected Attributes inherited from Drupal\tripal_biodb\Task\BioTaskBase
	$id

	$connection

	$logger

	$locker

	$state

	$parameters = ['input_schemas' => [], 'output_schemas' => [], ]

	$inputSchemas = []

	$outputSchemas = []

Detailed Description

Chado upgrader.

Usage:

// Where 'chado' is the name of an existing Chado schema.
$upgrader = \Drupal::service('tripal_chado.upgrader');
$upgrader->setParameters([
  'output_schemas' => ['chado'],
]);
if (!$upgrader->performTask()) {
  // Display a message telling the user the task failed and details are in
  // the site logs.
}

Constructor & Destructor Documentation

◆ __construct()

Drupal\tripal_chado\Task\ChadoUpgrader::__construct	(	?\Drupal\Core\Database\Connection	$database = `NULL`,
		?\Psr\Log\LoggerInterface	$logger = `NULL`,
		?\Drupal\tripal_biodb\Lock\SharedLockBackendInterface	$locker = `NULL`,
		?\Drupal\Core\State\StateInterface	$state = `NULL`
	)

{}

Member Function Documentation

◆ getProgress()

Drupal\tripal_chado\Task\ChadoUpgrader::getProgress ( )

{Returns the percent of progress of current task.This method can also be used to check if a task is currently running if it has a > 0 value. A negative value means an error occured while running.

Returns: float A value between -1 and 1, 0 meaning the task has not been started yet, 1 meaning the task is completed with success and a negative value meaning that the task failed. The negative value may be used as a code to identify the error.

}

Implements Drupal\tripal_biodb\Task\BioTaskInterface.

◆ getStatus()

Drupal\tripal_chado\Task\ChadoUpgrader::getStatus ( )

{{Returns a string describing current status of the performed task.This function returns the last known status, even if the task ended. In case of failure, this function may return the reason of the failure.

Returns: string A localized description.

}}

Reimplemented from Drupal\tripal_biodb\Task\BioTaskBase.

◆ performTask()

Drupal\tripal_chado\Task\ChadoUpgrader::performTask ( )

Upgrade a given chado schema to the specified version.

Before using this function, we recommand you backup your database and/or clone your Chado schema first and try to upgrade that clone first. In case of failure during the upgrade process, the upgraded schema may become unusable so you will have to restore a working version. But be careful, even if the upgrade process scceeded, it may have removed some data that did not feet in the reference schema. Therefore, you will have to check the content of the upgraded schema and may have to manully import back removed data (it could be custom tables, columns, functions, whatever that was not present in the official Chado schema version selected).

The upgrade process

First, if no reference input schema is provieded, we create a new Chado template schema (see CHADO_REF_SCHEMA*) to use as a reference for the upgrade process. The structure of the reference schema will be "applied" to the schema to upgrade. In the end, the schema to upgrade will contain the same functions, tables, columns, views, etc. that the reference schema has.

After the reference schema is setup (or selected), we process each PostgreSQL object categories and compare the schema to upgrade to the reference one. When changes are required, we store the corresponding SQL queries for each object in the 'upgradeQueries' class member. Cleanup queries are stored in 'upgradeQueries['#cleanup']' in order to remove unnecessary objects.

The upgrade process is the following: 1) Prepare table column defaults removal in table definitions (ie. remove sequences and function dependencies) 2) Prepare functions and aggregate functions removal 3) Prepare views removal 4) Prepare database type upgrade 5) Prepare sequence upgrade 6) Prepare function prototypes (for function inter-dependencies) 7) Prepare table column type upgrade Columns that match $chado_column_upgrade will be upgraded using the corresponding queries. Other columns will be updated using default behavior. Defaults are dropped and will be added later. 8) Prepare sequence association (to table columns) 9) Prepare view upgrade 10) Prepare function upgrade 11) Prepare aggregate function upgrade 12) Prepare table column default upgrade 13) Prepare comment upgrade 14) Prepare data initialization 15) Process upgrade queries 16) Update Tripal integration

Note: a couple of PostgreSQL object are not processed as they are not part of Chado schema specifications: collations, domains, triggers, unlogged tables and materialized views (in PostgreSQL sens, Tripal MV could be processed but are removed by default and will need to be recreated).

Parameters

Task parameter array provided to the class constructor includes:

'output_schemas' array: one output Chado schema that must exist and contain data (required). This ouput schema is the schema that needs to be upgraded.
'input_schemas' array: no input schema or a reference schema name (for advanced users). See above documentation to understand what the refrence schema stand for. If the reference schema is not provided, the default one will be used. If the reference schema does not exist, it will be created. If it exists, it will be used as is and any provided version number will be ignored.
'version' string: a version number (optional, default to ::DEFAULT_CHADO_VERSION)
'cleanup' bool: a cleanup flag that tells if existing database objects no present in the reference schema should be removed (cleanup = TRUE) or not (cleanup = FALSE). Warning: if set to TRUE, uncleaned elements may prevent some parts of the schema to be upgraded and therefore, the upgrade process has more chances to fail. If you have data that are not part of the official Chado schema but you want to keep, you may try to set this flag to FALSE to try to keep them and avoid having to put them back manully in a cleaned upgraded version. Default to TRUE (ie. things will be cleaned up).
'filename' string: when a path to an unexisting file name is provided, NO upgrade will be performed. Instead, every SQL query part of the upgrade will be written into that file. This SQL file can be later used to upgrade the schema manually. However, please note that a reference schema will be created if needed and the queries have been designed to work using the provided schema names. Any change on schema names of the schema to upgrade or the reference schema will lead to issues when the SQL queries will be run. The file path can be absolute (starting with a '/') or relative to the site 'files' directory (or private directory if it the the default). Default: no file path.

Example:

[
  'output_schemas' => ['chado'],
  'version' => '1.3',
  'cleanup' => TRUE,
  'filename' => 'upgrade_queries.sql',
]

Returns: bool TRUE if the task was performed with success and FALSE if the task was completed but without the expected success.

Exceptions

Drupal

Reimplemented from Drupal\tripal_biodb\Task\BioTaskBase.

◆ prepareAggregateFunctionUpgrade()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareAggregateFunctionUpgrade ( )

protected

Upgrade aggregate functions.

◆ prepareCommentUpgrade()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareCommentUpgrade ( )

protected

Upgrade comment.

◆ prepareDropAllViews()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareDropAllViews ( )

protected

Drop all views of schema to upgrade.

◆ prepareDropColumnDefaults()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareDropColumnDefaults ( )

protected

Remove table column defaults.

Since column defaults may use functions that need to be upgraded, we remove those default in order to drop old functions without removing column content.

◆ prepareDropFunctions()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareDropFunctions ( )

protected

Drop functions.

◆ prepareFunctionUpgrade()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareFunctionUpgrade ( )

protected

Upgrade functions.

◆ preparePrototypeFunctions()

Drupal\tripal_chado\Task\ChadoUpgrader::preparePrototypeFunctions ( )

protected

Create prototype functions.

Replace existing functions with same signature by protoype functions. Prototype functions are functions with an empty body. Those functions will be filled later with the upgraded content. The idea here is to be able to link those functions in other database objects without having to deal with function inter-dependencies (i.e. empty body, so no dependency inside) and keep the same function reference when it will be upgraded.

◆ prepareSequenceAssociation()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareSequenceAssociation ( )

protected

Associate sequences.

◆ prepareUpgradeSequences()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareUpgradeSequences ( )

protected

Upgrade schema sequences.

◆ prepareUpgradeTableDefauls()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareUpgradeTableDefauls ( )

protected

Upgrade table column defaults.

◆ prepareUpgradeTables()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareUpgradeTables ( )

protected

Upgrade schema tables.

Note: Other modules can hook into this functionality by implementing HOOK_tripal_chado_column_upgrade OR HOOK_tripal_chado_column_upgrade_1_3. This allows other modules to specify column-specific upgrade procedures. First level keys are table names, second level keys are column names and values are array of 2 keys: 'update' = a function to run to process update and return SQL queries 'skip' = an array of table name as keys and column names to skip as sub-keys. If no column names are specified, the whole table is skipped. For example,

function example_tripal_chado_column_upgrade(&$chado_column_upgrade) {
  $chado_column_upgrade = [
  'analysis' => [
    'analysis_id' => [
      'update' => function ($chado_schema, $ref_chado_schema, $cleanup) {
        $sql_queries = [];
        $sql_queries[] =
          "ALTER $ref_chado_schema.analysis ALTER COLUMN analysis_id ...";
        $sql_queries[] =
          "CREATE TABLE $ref_chado_schema.analysis_cvterm ...";
        $sql_queries[] =
          "INSERT INTO $ref_chado_schema.analysis_cvterm ...";
        return $sql_queries;
      },
      'skip' => [
        'analysis' => [
          'analysis_id' => [],
        ],
        'analysis_cvterm' => [],
      ],
    ],
  ],
];
}

◆ prepareUpgradeTypes()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareUpgradeTypes ( )

protected

Upgrade schema types.

◆ prepareUpgradeViews()

Drupal\tripal_chado\Task\ChadoUpgrader::prepareUpgradeViews ( )

protected

Upgrade views.

◆ processUpgradeQueries()

Drupal\tripal_chado\Task\ChadoUpgrader::processUpgradeQueries ( )

protected

Process upgrades.

Execute SQL queries or save them into a SQL instead if $filename is set. Queries are ordered according to priorities and what must be run in the end.

◆ reinitSchema()

Drupal\tripal_chado\Task\ChadoUpgrader::reinitSchema ( )

protected

Add missing initialization data.

◆ setProgress()

Drupal\tripal_chado\Task\ChadoUpgrader::setProgress ( float $value )

protected

Set progress value.

Parameters

float $value New progress value.

◆ setupReferenceSchema()

Drupal\tripal_chado\Task\ChadoUpgrader::setupReferenceSchema ( )

protected

Setups the refrence schema.

◆ validateParameters()

Drupal\tripal_chado\Task\ChadoUpgrader::validateParameters ( )

Validate task parameters.

Parameter array provided to the class constructor must include one output schema and it may include an input schema as reference, a version number, a cleanup flag and an output file name:

[
  'output_schemas' => ['chado'],
  'version' => '1.3',
  'cleanup' => TRUE,
  'filename' => 'upgrade_queries.sql',
]

Exceptions

Implements Drupal\tripal_biodb\Task\BioTaskInterface.

Member Data Documentation

◆ $upgradeQueries

Drupal\tripal_chado\Task\ChadoUpgrader::$upgradeQueries

protected

Upgrade SQL queries.

◆ CHADO_OBJECT_PRIORITY_13

const Drupal\tripal_chado\Task\ChadoUpgrader::CHADO_OBJECT_PRIORITY_13

Initial value:

= [
    'db',
    'dbxref',
    'cv',
    'cvterm',
    'cvtermpath',
    'pub',
    'synonym',
    'feature',
    'feature_cvterm',
    'feature_dbxref',
    'feature_synonym',
    'featureprop',
    'feature_pub',
    'gffatts',
  ]

Defines a priority order to process some Chado objects to upgrade.

◆ CHADO_REF_SCHEMA_13

const Drupal\tripal_chado\Task\ChadoUpgrader::CHADO_REF_SCHEMA_13 = '_chado_13_template'

Name of the reference schema.

This name can be overriden by extending classes.

◆ DEFAULT_CHADO_VERSION

const Drupal\tripal_chado\Task\ChadoUpgrader::DEFAULT_CHADO_VERSION = '1.3'

Default version.

◆ TASK_NAME

const Drupal\tripal_chado\Task\ChadoUpgrader::TASK_NAME = 'upgrader'

Name of the task.

The documentation for this class was generated from the following file:

tripal_chado/src/Task/ChadoUpgrader.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ getProgress()

◆ getStatus()

◆ performTask()

◆ prepareAggregateFunctionUpgrade()

◆ prepareCommentUpgrade()

◆ prepareDropAllViews()

◆ prepareDropColumnDefaults()

◆ prepareDropFunctions()

◆ prepareFunctionUpgrade()

◆ preparePrototypeFunctions()

◆ prepareSequenceAssociation()

◆ prepareUpgradeSequences()

◆ prepareUpgradeTableDefauls()

◆ prepareUpgradeTables()

◆ prepareUpgradeTypes()

◆ prepareUpgradeViews()

◆ processUpgradeQueries()

◆ reinitSchema()

◆ setProgress()

◆ setupReferenceSchema()

◆ validateParameters()

Member Data Documentation

◆ $upgradeQueries

◆ CHADO_OBJECT_PRIORITY_13

◆ CHADO_REF_SCHEMA_13

◆ DEFAULT_CHADO_VERSION

◆ TASK_NAME