Tripal
|
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 |
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.
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.
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. |
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:
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. |
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.
?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. |
Drupal\tripal\TripalDBX\TripalDbx::freeSchemaPattern | ( | string | $pat_regex, |
bool | $free_all_matching = FALSE |
||
) |
Removes a schema name reservation pattern from the list.
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. |
Drupal\tripal\TripalDBX\TripalDbx::getDatabaseSize | ( | ?\Drupal\Core\Database\Connection | $db = NULL | ) |
Returns the size in bytes of a TripalDBX managed database.
\Drupal\Core\Database\Driver\pgsql\Connection | ?,$db | A Drupal PostgreSQL or Tripal DBX connection object. |
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:
Drupal\tripal\TripalDBX\TripalDbx::getReservedSchemaPattern | ( | ) |
Returns the list of reserved schema name pattern.
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.
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. |
|
protected |
Initializes schema reservations.
bool | $reload_config | Forces config reloading. Default: FALSE |
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:
Use:
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 |
Drupal\tripal\TripalDBX\TripalDbx::isSchemaReserved | ( | string | $schema_name | ) |
Tells if a schema name is reserved or not.
string | $schema_name | The name of the schema to check. |
Drupal\tripal\TripalDBX\TripalDbx::parseTableDdl | ( | string | $table_ddl | ) |
Turns a table DDL string into a more usable structure.
string | $table_ddl | A string containing table definition as returned by \Drupal\tripal\TripalDBX\TripalDbxSchema::getTableDdl(). |
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.
string | $table_ddl | A string containing table definition as returned by \Drupal\tripal\TripalDBX\TripalDbxSchema::getTableDdl(). |
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:
while with a schema called "schéma" and a table "cost", a query should look like:
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.
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. |
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.
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. |
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.
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. |
Drupal\tripal\TripalDBX\TripalDbx::runSqlFile | ( | string | $sql_file, |
array | $replacements, | ||
?\Drupal\Core\Database\Connection | $db = NULL |
||
) |
Run an SQL file.
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. |
Drupal\tripal\TripalDBX\TripalDbx::schemaExists | ( | string | $schema_name, |
?\Drupal\Core\Database\Driver\pgsql\Connection | $db = NULL |
||
) |
Check that the given schema exists.
Use:
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. |
const Drupal\tripal\TripalDBX\TripalDbx::SCHEMA_NAME_REGEXP |
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.
const Drupal\tripal\TripalDBX\TripalDbx::TABLE_NAME_REGEXP |
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.