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_schema	Source schema to clone.
string	$target_schema	Destination schema that will be created and filled with a copy of $source_schema.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_name	Name of schema to create.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_name	Schema name.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_regex	The regular expression to remove from the list if it is there.
bool	$free_all_matching	If 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 ?,$db A 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_name	Schema name.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_config Forces 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_name	The name of the schema to validate.
bool	$ignore_reservation	If TRUE, reserved schema names are considered as valid. Default: FALSE
bool	$reload_config	Forces 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_name The 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_ddl A 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_ddl A 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_id	Object name to quote if needed.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_name	The old schema name to rename.
string	$new_schema_name	New name to use.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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_regex	A 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	$description	The 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_file	Path to an SQL file.
array	$replacements	An 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	?,$db	A 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_name	Schema name.
\Drupal\Core\Database\Driver\pgsql\Connection	?,$db	A 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:

tripal/src/TripalDBX/TripalDbx.php

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ cloneSchema()

◆ createSchema()

◆ dropSchema()

◆ freeSchemaPattern()

◆ getDatabaseSize()

◆ getDrupalSchemaName()

◆ getReservedSchemaPattern()

◆ getSchemaSize()

◆ initSchemaReservation()

◆ isInvalidSchemaName()

◆ isSchemaReserved()

◆ parseTableDdl()

◆ parseTableDdlToDrupal()

◆ quoteDbObjectId()

◆ renameSchema()

◆ reserveSchemaPattern()

◆ runSqlFile()

◆ schemaExists()

Member Data Documentation

◆ SCHEMA_NAME_REGEXP

◆ TABLE_NAME_REGEXP