Tripal
Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Attributes | List of all members
Drupal\tripal\TripalDBX\TripalDbx Class Reference

Public Member Functions

 getDrupalSchemaName ()
 
 isInvalidSchemaName (string $schema_name, bool $ignore_reservation=FALSE, bool $reload_config=FALSE)
 
 reserveSchemaPattern (string $pat_regex, string $description='')
 
 getReservedSchemaPattern ()
 
 freeSchemaPattern (string $pat_regex, bool $free_all_matching=FALSE)
 
 isSchemaReserved (string $schema_name)
 
 quoteDbObjectId (string $object_id, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 schemaExists (string $schema_name, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 createSchema (string $schema_name, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 cloneSchema (string $source_schema, string $target_schema, ?object $db=NULL)
 
 renameSchema (string $old_schema_name, string $new_schema_name, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 dropSchema (string $schema_name, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 getSchemaSize (string $schema_name, ?\Drupal\Core\Database\Driver\pgsql\Connection $db=NULL)
 
 getDatabaseSize (?\Drupal\Core\Database\Connection $db=NULL)
 
 runSqlFile (string $sql_file, array $replacements, ?\Drupal\Core\Database\Connection $db=NULL)
 
 parseTableDdl (string $table_ddl)
 
 parseTableDdlToDrupal (string $table_ddl)
 

Public Attributes

const SCHEMA_NAME_REGEXP
 
const TABLE_NAME_REGEXP
 

Protected Member Functions

 initSchemaReservation (bool $reload_config=FALSE)
 

Static Protected Attributes

static $drupalSchema
 
static $reservedSchemaPatterns
 

Detailed Description

Tripal DBX

This class provides methods which form the Tripal DBX API. Specifically, this API focuses on extending Drupal to better handle cross database and cross schema querying.

This class should be accessed through the tripal.dbx service and NOT initiated directly. For example, $tripaldbx = \Drupal::service('tripal.dbx');

Additional Note: This class makes use of static member variables/properties to avoid using global variables.

Member Function Documentation

◆ cloneSchema()

Drupal\tripal\TripalDBX\TripalDbx::cloneSchema ( string  $source_schema,
string  $target_schema,
?object  $db = NULL 
)

Clones a schema into new (unexisting) one.

The target schema must not exist.

$source_schema_name = 'source';
$target_schema_name = 'target';
$tripaldbx = \Drupal::service('tripal.dbx');
$tripaldbx->cloneSchema($source_schema_name, $target_schema_name);
Parameters
string$source_schemaSource schema to clone.
string$target_schemaDestination schema that will be created and filled with a copy of $source_schema.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or TripalDBX connection object. If NULL, current Drupal database is used.
Exceptions

◆ createSchema()

Drupal\tripal\TripalDBX\TripalDbx::createSchema ( string  $schema_name,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Creates the given schema.

The schema to create must not exist. If an error occurs, an exception is thrown.

Use:

$schema_name = 'name_to_create';
$tripaldbx = \Drupal::service('tripal.dbx');
$tripaldbx->createSchema($schema_name);
Parameters
string$schema_nameName of schema to create.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or TripalDBX connection object. If NULL, current Drupal database is used.
Exceptions

◆ dropSchema()

Drupal\tripal\TripalDBX\TripalDbx::dropSchema ( string  $schema_name,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Removes the given schema.

The schema to remove must exist. If an error occurs, an exception is thrown.

$schema_name = 'schema_to_delete';
$tripaldbx = \Drupal::service('tripal.dbx');
$tripaldbx->dropSchema($schema_name);
Parameters
?string$schema_name Name of schema to remove.
string$schema_nameSchema name.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or Tripal DBX connection object. If NULL, current Drupal database is used.
Exceptions

◆ freeSchemaPattern()

Drupal\tripal\TripalDBX\TripalDbx::freeSchemaPattern ( string  $pat_regex,
bool  $free_all_matching = FALSE 
)

Removes a schema name reservation pattern from the list.

Parameters
string$pat_regexThe regular expression to remove from the list if it is there.
bool$free_all_matchingIf TRUE, the provided pattern will be considered as a regular string with no special characters meaning and any current pattern matching that string will be removed form current reservation list.
Returns
array Returns an associative array containing the removed patterns as keys and their associated descriptions as values. An empty array if no pattern has been removed.

◆ getDatabaseSize()

Drupal\tripal\TripalDBX\TripalDbx::getDatabaseSize ( ?\Drupal\Core\Database\Connection  $db = NULL)

Returns the size in bytes of a TripalDBX managed database.

$tripaldbx = \Drupal::service('tripal.dbx');
$db_size = $tripaldbx->getDatabaseSize();
Parameters
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or Tripal DBX connection object.
Returns
int The size in bytes of the database or 0 if the size is not available.

◆ getDrupalSchemaName()

Drupal\tripal\TripalDBX\TripalDbx::getDrupalSchemaName ( )

Get Drupal schema name.

This function may return an empty string if the Drupal schema was not found. It can happen if Drupal is stored in a different database (and using a different connection) than the Chado (or biological schema) one.

Use:

$tripaldbx = \Drupal::service('tripal.dbx');
$drupal_schema = $tripaldbx->getDrupalSchemaName();
Returns
string The name of the schema used by Drupal installation or an empty string if not found/available.

◆ getReservedSchemaPattern()

Drupal\tripal\TripalDBX\TripalDbx::getReservedSchemaPattern ( )

Returns the list of reserved schema name pattern.

Returns
array The list of reserved patterns as keys and their associated descriptions as values.

◆ getSchemaSize()

Drupal\tripal\TripalDBX\TripalDbx::getSchemaSize ( string  $schema_name,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Returns the size in bytes of a PostgreSQL schema.

$schema_name = 'schema';
$tripaldbx = \Drupal::service('tripal.dbx');
$schema_size = $tripaldbx->getSchemaSize($schema_name);
Parameters
string$schema_nameSchema name.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or Tripal DBX connection object. If NULL, current Drupal database is used.
Returns
integer The size in bytes of the schema or 0 if the size is not available.
Exceptions

◆ initSchemaReservation()

Drupal\tripal\TripalDBX\TripalDbx::initSchemaReservation ( bool  $reload_config = FALSE)
protected

Initializes schema reservations.

Parameters
bool$reload_configForces config reloading. Default: FALSE

◆ isInvalidSchemaName()

Drupal\tripal\TripalDBX\TripalDbx::isInvalidSchemaName ( string  $schema_name,
bool  $ignore_reservation = FALSE,
bool  $reload_config = FALSE 
)

Check that the given schema name is a valid schema name.

Schema name validation can be altered through the configuration variable reserved_schema_patterns of tripaldbx.settings. This configuration variable contains a list of regex with their description, used to reserve schema name patterns. For instance, the key '_chado*' with the value 'external (non-Drupal) chado instances' will make this function returns a issue message saying that the pattern is reserved for 'external (non-Drupal) chado instances' when a schema name '_chado_beta' is checked.

Extending modules willing to reserve schema names should use something similar to the following code in their "<module name>.install" file:

function <module name>_install($is_syncing) {
// Reserves 'myschema' schema in 'reserved_schema_patterns' settings.
$config = \Drupal::service('config.factory')
->getEditable('tripaldbx.settings');
$reserved_schema_patterns = $config->get('reserved_schema_patterns') ?? [];
$reserved_schema_patterns['myschema'] = 'my schema';
$config->set('reserved_schema_patterns', $reserved_schema_patterns)->save();
}
function <module name>_uninstall() {
// Unreserves 'myschema' schemas in 'reserved_schema_patterns' settings.
$config = \Drupal::service('config.factory')
->getEditable('tripaldbx.settings')
;
$reserved_schema_patterns = $config->get('reserved_schema_patterns') ?? [];
unset($reserved_schema_patterns['myschema']);
$config->set('reserved_schema_patterns', $reserved_schema_patterns)->save();
}

Use:

$schema_name = 'name_to_check';
$tripaldbx = \Drupal::service('tripal.dbx');
if ($issue = $tripaldbx->isInvalidSchemaName($schema_name)) {
throw new \Exception('Invalid schema name: ' . $issue);
}
Parameters
string$schema_nameThe name of the schema to validate.
bool$ignore_reservationIf TRUE, reserved schema names are considered as valid. Default: FALSE
bool$reload_configForces schema reserved names config reloading. Default: FALSE
Returns
string An empty string if the schema name is valid or a string describing the issue in the name otherwise.

◆ isSchemaReserved()

Drupal\tripal\TripalDBX\TripalDbx::isSchemaReserved ( string  $schema_name)

Tells if a schema name is reserved or not.

Parameters
string$schema_nameThe name of the schema to check.
Returns
bool|array FALSE if the given schema name is not reserved, otherwise it will return an array with the reservation pattern matching the name as keys and their associated descriptions as values.

◆ parseTableDdl()

Drupal\tripal\TripalDBX\TripalDbx::parseTableDdl ( string  $table_ddl)

Turns a table DDL string into a more usable structure.

Parameters
string$table_ddlA string containing table definition as returned by \Drupal\tripal\TripalDBX\TripalDbxSchema::getTableDdl().
Returns
array An associative array with the following structure:
[
'columns' => [
<column name> => [
'type' => <PostgreSQL column type>,
'not null' => <TRUE if column cannot be NULL, FALSE otherwise>,
'default' => <column default value or NULL for no default>,
],
...
],
'constraints' => [
<constraint name> => <constraint definition>,
...
],
'indexes' => [
<index name> => [
'query' => <index creation query>,
'name' => <index name>,
'table' => <'table.column' names owning the index>,
'using' => <index type/structure>,
],
...
],
'comment' => <table description>,
'dependencies' => [
<foreign table name> => [
<this table column name> => <foreign table column name>,
...
],
...
],
];

◆ parseTableDdlToDrupal()

Drupal\tripal\TripalDBX\TripalDbx::parseTableDdlToDrupal ( string  $table_ddl)

Parses a table DDL and returns a Drupal schema definition.

An exception is thrown if the table is not found.

Parameters
string$table_ddlA string containing table definition as returned by \Drupal\tripal\TripalDBX\TripalDbxSchema::getTableDdl().
Returns
array An array with details of the table reflecting what is in database.
See also
https://www.drupal.org/docs/7/api/schema-api/data-types/data-types-overview
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Database!database.api.php/group/schemaapi/9.3.x

◆ quoteDbObjectId()

Drupal\tripal\TripalDBX\TripalDbx::quoteDbObjectId ( string  $object_id,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Returns a PostgreSQL quoted object name.

Use PostgreSQL to quote an object identifier if needed for SQL queries. For instance, a schema or a table name using special characters may need to be quoted if used in SQL queries.

For instance, with a schema called "schema" and a table "co$t", a query should look like:

SELECT * FROM schema."co$t";

while with a schema called "schéma" and a table "cost", a query should look like:

SELECT * FROM "schéma".cost;

Inappropriate object quoting would lead to SQL errors. This function has to be called for each object separately (one time for the schema and one time for the table in above examples) and it only adds quote when necessary.

Parameters
string$object_idObject name to quote if needed.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or TripalDBX connection object. If NULL, current Drupal database is used.
Returns
string The quoted object name or the initial name if no quote needed.

◆ renameSchema()

Drupal\tripal\TripalDBX\TripalDbx::renameSchema ( string  $old_schema_name,
string  $new_schema_name,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Renames a schema.

The new schema name must not be used by an existing schema. If an error occurs, an exception is thrown.

$old_schema_name = 'old';
$new_schema_name = 'new';
$tripaldbx = \Drupal::service('tripal.dbx');
$tripaldbx->renameSchema($old_schema_name, $new_schema_name);
Parameters
string$old_schema_nameThe old schema name to rename.
string$new_schema_nameNew name to use.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or Tripal DBX connection object. If NULL, current Drupal database is used.
Exceptions

◆ reserveSchemaPattern()

Drupal\tripal\TripalDBX\TripalDbx::reserveSchemaPattern ( string  $pat_regex,
string  $description = '' 
)

Adds a schema name pattern for reservation.

Schema names matching the given pattern will be considered invalid by ::isInvalidSchemaName and will not be allowed in TripalDbxConnection or TripalDbxSchema objects.

Parameters
string$pat_regexA simple schema name or a regular expression. Do not include regex delimiters nor starting '^' and ending '$' in the expression as they will be automatically added by the check system. Note that the '*' sign not preceded by a dot will be replaced by '.*'. It simplifies the way schema patterns can be defined by non-regex aware persons. If you need to use the '*' quantifier for a specific character, replace it by '{0,}'. ex.: 'internal_schemax{0,}' would match 'internal_schema' and 'internal_schemaxxx' while 'internal_schemax*' would also match 'internal_schemaxabcd'.
string$descriptionThe description of the reservation that may be displayed to users when a schema name is denied.
Exceptions

◆ runSqlFile()

Drupal\tripal\TripalDBX\TripalDbx::runSqlFile ( string  $sql_file,
array  $replacements,
?\Drupal\Core\Database\Connection  $db = NULL 
)

Run an SQL file.

Parameters
string$sql_filePath to an SQL file.
array$replacementsAn array of search-and-replace values used with preg_replace() to replace placeholders in the SQL file with replacement values. The 'search' values will be searched and replaced with the 'replace' values. Default: [] (no replacements).
\Drupal\Core\Database\Connection?,$dbA connection to the database you want to run the SQL file on.

◆ schemaExists()

Drupal\tripal\TripalDBX\TripalDbx::schemaExists ( string  $schema_name,
?\Drupal\Core\Database\Driver\pgsql\Connection  $db = NULL 
)

Check that the given schema exists.

Use:

$schema_name = 'name_to_test';
$tripaldbx = \Drupal::service('tripal.dbx');
if ($tripaldbx->schemaExists($schema_name)) {
// Schema exists.
}
Parameters
string$schema_nameSchema name.
\Drupal\Core\Database\Driver\pgsql\Connection?,$dbA Drupal PostgreSQL or TripalDBX connection object. If NULL, current Drupal database is used.
Returns
bool TRUE/FALSE depending upon whether or not the schema exists.

Member Data Documentation

◆ SCHEMA_NAME_REGEXP

const Drupal\tripal\TripalDBX\TripalDbx::SCHEMA_NAME_REGEXP
Initial value:
=
'[a-zA-Z_\\xA0-\\xFF][a-zA-Z_\\xA0-\\xFF0-9]{0,63}'

Schema name validation regular expression.

Schema name must be all lowercase with no special characters with the exception of underscores and diacritical marks (which can be uppercase). ref.: https://www.postgresql.org/docs/9.5/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS It should also not contain any space and must not begin with "pg_". Note: capital letter could be used but are silently converted to lowercase by PostgreSQL. Here, we want to avoid ambiguity so we forbid uppercase. We also prevent the use of dollar sign in names '$' while it should be valid, in order to stick to SQL standard and prevent issues with PHP string interpolation.

◆ TABLE_NAME_REGEXP

const Drupal\tripal\TripalDBX\TripalDbx::TABLE_NAME_REGEXP
Initial value:
=
'[a-zA-Z_\\xA0-\\xFF][a-zA-Z_\\xA0-\\xFF0-9]{0,63}'

Table name validation regular expression.

Table name must be all lowercase with no special characters with the exception of underscores and diacritical marks (which can be uppercase). ref.: https://www.postgresql.org/docs/9.5/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS It should also not contain any space and must not begin with "pg_". Note: capital letter could be used but are silently converted to lowercase by PostgreSQL. Here, we want to avoid ambiguity so we forbid uppercase. We also prevent the use of dollar sign in names '$' while it should be valid, in order to stick to SQL standard and prevent issues with PHP string interpolation.


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