722 lines
22 KiB
PHP
722 lines
22 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace PhpMyAdmin\Dbal;
|
|
|
|
use PhpMyAdmin\ConfigStorage\Relation;
|
|
use PhpMyAdmin\DatabaseInterface;
|
|
use PhpMyAdmin\FieldMetadata;
|
|
use PhpMyAdmin\SystemDatabase;
|
|
use PhpMyAdmin\Table;
|
|
|
|
/**
|
|
* Main interface for database interactions
|
|
*/
|
|
interface DbalInterface
|
|
{
|
|
public const FETCH_NUM = 'NUM';
|
|
public const FETCH_ASSOC = 'ASSOC';
|
|
|
|
/**
|
|
* runs a query
|
|
*
|
|
* @param string $query SQL query to execute
|
|
* @param mixed $link optional database link to use
|
|
* @param int $options optional query options
|
|
* @param bool $cache_affected_rows whether to cache affected rows
|
|
*/
|
|
public function query(
|
|
string $query,
|
|
$link = DatabaseInterface::CONNECT_USER,
|
|
int $options = 0,
|
|
bool $cache_affected_rows = true
|
|
): ResultInterface;
|
|
|
|
/**
|
|
* runs a query and returns the result
|
|
*
|
|
* @param string $query query to run
|
|
* @param mixed $link link type
|
|
* @param int $options query options
|
|
* @param bool $cache_affected_rows whether to cache affected row
|
|
*
|
|
* @return mixed
|
|
*/
|
|
public function tryQuery(
|
|
string $query,
|
|
$link = DatabaseInterface::CONNECT_USER,
|
|
int $options = 0,
|
|
bool $cache_affected_rows = true
|
|
);
|
|
|
|
/**
|
|
* Send multiple SQL queries to the database server and execute the first one
|
|
*
|
|
* @param string $multiQuery multi query statement to execute
|
|
* @param int $linkIndex index of the opened database link
|
|
*/
|
|
public function tryMultiQuery(
|
|
string $multiQuery = '',
|
|
$linkIndex = DatabaseInterface::CONNECT_USER
|
|
): bool;
|
|
|
|
/**
|
|
* returns array with table names for given db
|
|
*
|
|
* @param string $database name of database
|
|
* @param mixed $link mysql link resource|object
|
|
*
|
|
* @return array tables names
|
|
*/
|
|
public function getTables(string $database, $link = DatabaseInterface::CONNECT_USER): array;
|
|
|
|
/**
|
|
* returns array of all tables in given db or dbs
|
|
* this function expects unquoted names:
|
|
* RIGHT: my_database
|
|
* WRONG: `my_database`
|
|
* WRONG: my\_database
|
|
* if $tbl_is_group is true, $table is used as filter for table names
|
|
*
|
|
* <code>
|
|
* $dbi->getTablesFull('my_database');
|
|
* $dbi->getTablesFull('my_database', 'my_table'));
|
|
* $dbi->getTablesFull('my_database', 'my_tables_', true));
|
|
* </code>
|
|
*
|
|
* @param string $database database
|
|
* @param string|array $table table name(s)
|
|
* @param bool $tbl_is_group $table is a table group
|
|
* @param int $limit_offset zero-based offset for the count
|
|
* @param bool|int $limit_count number of tables to return
|
|
* @param string $sort_by table attribute to sort by
|
|
* @param string $sort_order direction to sort (ASC or DESC)
|
|
* @param string|null $table_type whether table or view
|
|
* @param mixed $link link type
|
|
*
|
|
* @return array list of tables in given db(s)
|
|
*
|
|
* @todo move into Table
|
|
*/
|
|
public function getTablesFull(
|
|
string $database,
|
|
$table = '',
|
|
bool $tbl_is_group = false,
|
|
int $limit_offset = 0,
|
|
$limit_count = false,
|
|
string $sort_by = 'Name',
|
|
string $sort_order = 'ASC',
|
|
?string $table_type = null,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Get VIEWs in a particular database
|
|
*
|
|
* @param string $db Database name to look in
|
|
*
|
|
* @return Table[] Set of VIEWs inside the database
|
|
*/
|
|
public function getVirtualTables(string $db): array;
|
|
|
|
/**
|
|
* returns array with databases containing extended infos about them
|
|
*
|
|
* @param string|null $database database
|
|
* @param bool $force_stats retrieve stats also for MySQL < 5
|
|
* @param int $link link type
|
|
* @param string $sort_by column to order by
|
|
* @param string $sort_order ASC or DESC
|
|
* @param int $limit_offset starting offset for LIMIT
|
|
* @param bool|int $limit_count row count for LIMIT or true
|
|
* for $GLOBALS['cfg']['MaxDbList']
|
|
*
|
|
* @return array
|
|
*
|
|
* @todo move into ListDatabase?
|
|
*/
|
|
public function getDatabasesFull(
|
|
?string $database = null,
|
|
bool $force_stats = false,
|
|
$link = DatabaseInterface::CONNECT_USER,
|
|
string $sort_by = 'SCHEMA_NAME',
|
|
string $sort_order = 'ASC',
|
|
int $limit_offset = 0,
|
|
$limit_count = false
|
|
): array;
|
|
|
|
/**
|
|
* returns detailed array with all columns for sql
|
|
*
|
|
* @param string $sql_query target SQL query to get columns
|
|
* @param array $view_columns alias for columns
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getColumnMapFromSql(string $sql_query, array $view_columns = []): array;
|
|
|
|
/**
|
|
* returns detailed array with all columns for given table in database,
|
|
* or all tables/databases
|
|
*
|
|
* @param string|null $database name of database
|
|
* @param string|null $table name of table to retrieve columns from
|
|
* @param string|null $column name of specific column
|
|
* @param mixed $link mysql link resource
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getColumnsFull(
|
|
?string $database = null,
|
|
?string $table = null,
|
|
?string $column = null,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Returns description of a $column in given table
|
|
*
|
|
* @param string $database name of database
|
|
* @param string $table name of table to retrieve columns from
|
|
* @param string $column name of column
|
|
* @param bool $full whether to return full info or only column names
|
|
* @param int $link link type
|
|
*
|
|
* @return array flat array description
|
|
*/
|
|
public function getColumn(
|
|
string $database,
|
|
string $table,
|
|
string $column,
|
|
bool $full = false,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Returns descriptions of columns in given table
|
|
*
|
|
* @param string $database name of database
|
|
* @param string $table name of table to retrieve columns from
|
|
* @param bool $full whether to return full info or only column names
|
|
* @param int $link link type
|
|
*
|
|
* @return array<string, array> array indexed by column names
|
|
*/
|
|
public function getColumns(
|
|
string $database,
|
|
string $table,
|
|
bool $full = false,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Returns all column names in given table
|
|
*
|
|
* @param string $database name of database
|
|
* @param string $table name of table to retrieve columns from
|
|
* @param mixed $link mysql link resource
|
|
*
|
|
* @return string[]
|
|
*/
|
|
public function getColumnNames(
|
|
string $database,
|
|
string $table,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Returns indexes of a table
|
|
*
|
|
* @param string $database name of database
|
|
* @param string $table name of the table whose indexes are to be retrieved
|
|
* @param mixed $link mysql link resource
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getTableIndexes(
|
|
string $database,
|
|
string $table,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* returns value of given mysql server variable
|
|
*
|
|
* @param string $var mysql server variable name
|
|
* @param int $type DatabaseInterface::GETVAR_SESSION |
|
|
* DatabaseInterface::GETVAR_GLOBAL
|
|
* @param int $link mysql link resource|object
|
|
*
|
|
* @return false|string|null value for mysql server variable
|
|
*/
|
|
public function getVariable(
|
|
string $var,
|
|
int $type = DatabaseInterface::GETVAR_SESSION,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
);
|
|
|
|
/**
|
|
* Sets new value for a variable if it is different from the current value
|
|
*
|
|
* @param string $var variable name
|
|
* @param string $value value to set
|
|
* @param int $link mysql link resource|object
|
|
*/
|
|
public function setVariable(string $var, string $value, $link = DatabaseInterface::CONNECT_USER): bool;
|
|
|
|
/**
|
|
* Function called just after a connection to the MySQL database server has
|
|
* been established. It sets the connection collation, and determines the
|
|
* version of MySQL which is running.
|
|
*/
|
|
public function postConnect(): void;
|
|
|
|
/**
|
|
* Sets collation connection for user link
|
|
*
|
|
* @param string $collation collation to set
|
|
*/
|
|
public function setCollation(string $collation): void;
|
|
|
|
/**
|
|
* Function called just after a connection to the MySQL database server has
|
|
* been established. It sets the connection collation, and determines the
|
|
* version of MySQL which is running.
|
|
*/
|
|
public function postConnectControl(Relation $relation): void;
|
|
|
|
/**
|
|
* returns a single value from the given result or query,
|
|
* if the query or the result has more than one row or field
|
|
* the first field of the first row is returned
|
|
*
|
|
* <code>
|
|
* $sql = 'SELECT `name` FROM `user` WHERE `id` = 123';
|
|
* $user_name = $dbi->fetchValue($sql);
|
|
* // produces
|
|
* // $user_name = 'John Doe'
|
|
* </code>
|
|
*
|
|
* @param string $query The query to execute
|
|
* @param int|string $field field to fetch the value from,
|
|
* starting at 0, with 0 being
|
|
* default
|
|
* @param int $link link type
|
|
*
|
|
* @return string|false|null value of first field in first row from result
|
|
* or false if not found
|
|
*/
|
|
public function fetchValue(
|
|
string $query,
|
|
$field = 0,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
);
|
|
|
|
/**
|
|
* Returns only the first row from the result or null if result is empty.
|
|
*
|
|
* <code>
|
|
* $sql = 'SELECT * FROM `user` WHERE `id` = 123';
|
|
* $user = $dbi->fetchSingleRow($sql);
|
|
* // produces
|
|
* // $user = array('id' => 123, 'name' => 'John Doe')
|
|
* </code>
|
|
*
|
|
* @param string $query The query to execute
|
|
* @param string $type NUM|ASSOC returned array should either numeric
|
|
* associative or both
|
|
* @param int $link link type
|
|
* @psalm-param self::FETCH_NUM|self::FETCH_ASSOC $type
|
|
*/
|
|
public function fetchSingleRow(
|
|
string $query,
|
|
string $type = DbalInterface::FETCH_ASSOC,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): ?array;
|
|
|
|
/**
|
|
* returns all rows in the resultset in one array
|
|
*
|
|
* <code>
|
|
* $sql = 'SELECT * FROM `user`';
|
|
* $users = $dbi->fetchResult($sql);
|
|
* // produces
|
|
* // $users[] = array('id' => 123, 'name' => 'John Doe')
|
|
*
|
|
* $sql = 'SELECT `id`, `name` FROM `user`';
|
|
* $users = $dbi->fetchResult($sql, 'id');
|
|
* // produces
|
|
* // $users['123'] = array('id' => 123, 'name' => 'John Doe')
|
|
*
|
|
* $sql = 'SELECT `id`, `name` FROM `user`';
|
|
* $users = $dbi->fetchResult($sql, 0);
|
|
* // produces
|
|
* // $users['123'] = array(0 => 123, 1 => 'John Doe')
|
|
*
|
|
* $sql = 'SELECT `id`, `name` FROM `user`';
|
|
* $users = $dbi->fetchResult($sql, 'id', 'name');
|
|
* // or
|
|
* $users = $dbi->fetchResult($sql, 0, 1);
|
|
* // produces
|
|
* // $users['123'] = 'John Doe'
|
|
*
|
|
* $sql = 'SELECT `name` FROM `user`';
|
|
* $users = $dbi->fetchResult($sql);
|
|
* // produces
|
|
* // $users[] = 'John Doe'
|
|
*
|
|
* $sql = 'SELECT `group`, `name` FROM `user`'
|
|
* $users = $dbi->fetchResult($sql, array('group', null), 'name');
|
|
* // produces
|
|
* // $users['admin'][] = 'John Doe'
|
|
*
|
|
* $sql = 'SELECT `group`, `name` FROM `user`'
|
|
* $users = $dbi->fetchResult($sql, array('group', 'name'), 'id');
|
|
* // produces
|
|
* // $users['admin']['John Doe'] = '123'
|
|
* </code>
|
|
*
|
|
* @param string $query query to execute
|
|
* @param string|int|array $key field-name or offset
|
|
* used as key for
|
|
* array or array of
|
|
* those
|
|
* @param string|int $value value-name or offset
|
|
* used as value for
|
|
* array
|
|
* @param int $link link type
|
|
*
|
|
* @return array resultrows or values indexed by $key
|
|
*/
|
|
public function fetchResult(
|
|
string $query,
|
|
$key = null,
|
|
$value = null,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* Get supported SQL compatibility modes
|
|
*
|
|
* @return array supported SQL compatibility modes
|
|
*/
|
|
public function getCompatibilities(): array;
|
|
|
|
/**
|
|
* returns warnings for last query
|
|
*
|
|
* @param int $link link type
|
|
*
|
|
* @return array warnings
|
|
*/
|
|
public function getWarnings($link = DatabaseInterface::CONNECT_USER): array;
|
|
|
|
/**
|
|
* returns an array of PROCEDURE or FUNCTION names for a db
|
|
*
|
|
* @param string $db db name
|
|
* @param string $which PROCEDURE | FUNCTION
|
|
* @param int $link link type
|
|
*
|
|
* @return array the procedure names or function names
|
|
*/
|
|
public function getProceduresOrFunctions(
|
|
string $db,
|
|
string $which,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): array;
|
|
|
|
/**
|
|
* returns the definition of a specific PROCEDURE, FUNCTION, EVENT or VIEW
|
|
*
|
|
* @param string $db db name
|
|
* @param string $which PROCEDURE | FUNCTION | EVENT | VIEW
|
|
* @param string $name the procedure|function|event|view name
|
|
* @param int $link link type
|
|
*
|
|
* @return string|null the definition
|
|
*/
|
|
public function getDefinition(
|
|
string $db,
|
|
string $which,
|
|
string $name,
|
|
$link = DatabaseInterface::CONNECT_USER
|
|
): ?string;
|
|
|
|
/**
|
|
* returns details about the PROCEDUREs or FUNCTIONs for a specific database
|
|
* or details about a specific routine
|
|
*
|
|
* @param string $db db name
|
|
* @param string|null $which PROCEDURE | FUNCTION or null for both
|
|
* @param string $name name of the routine (to fetch a specific routine)
|
|
*
|
|
* @return array information about ROCEDUREs or FUNCTIONs
|
|
*/
|
|
public function getRoutines(string $db, ?string $which = null, string $name = ''): array;
|
|
|
|
/**
|
|
* returns details about the EVENTs for a specific database
|
|
*
|
|
* @param string $db db name
|
|
* @param string $name event name
|
|
*
|
|
* @return array information about EVENTs
|
|
*/
|
|
public function getEvents(string $db, string $name = ''): array;
|
|
|
|
/**
|
|
* returns details about the TRIGGERs for a specific table or database
|
|
*
|
|
* @param string $db db name
|
|
* @param string $table table name
|
|
* @param string $delimiter the delimiter to use (may be empty)
|
|
*
|
|
* @return array information about triggers (may be empty)
|
|
*/
|
|
public function getTriggers(string $db, string $table = '', string $delimiter = '//'): array;
|
|
|
|
/**
|
|
* gets the current user with host
|
|
*
|
|
* @return string the current user i.e. user@host
|
|
*/
|
|
public function getCurrentUser(): string;
|
|
|
|
/**
|
|
* Checks if current user is superuser
|
|
*/
|
|
public function isSuperUser(): bool;
|
|
|
|
public function isGrantUser(): bool;
|
|
|
|
public function isCreateUser(): bool;
|
|
|
|
public function isConnected(): bool;
|
|
|
|
/**
|
|
* Get the current user and host
|
|
*
|
|
* @return array array of username and hostname
|
|
*/
|
|
public function getCurrentUserAndHost(): array;
|
|
|
|
/**
|
|
* Returns value for lower_case_table_names variable
|
|
*
|
|
* @return string
|
|
*/
|
|
public function getLowerCaseNames();
|
|
|
|
/**
|
|
* connects to the database server
|
|
*
|
|
* @param int $mode Connection mode on of CONNECT_USER, CONNECT_CONTROL
|
|
* or CONNECT_AUXILIARY.
|
|
* @param array|null $server Server information like host/port/socket/persistent
|
|
* @param int|null $target How to store connection link, defaults to $mode
|
|
*
|
|
* @return mixed false on error or a connection object on success
|
|
*/
|
|
public function connect(int $mode, ?array $server = null, ?int $target = null);
|
|
|
|
/**
|
|
* selects given database
|
|
*
|
|
* @param string|DatabaseName $dbname database name to select
|
|
* @param int $link link type
|
|
*/
|
|
public function selectDb($dbname, $link = DatabaseInterface::CONNECT_USER): bool;
|
|
|
|
/**
|
|
* Check if there are any more query results from a multi query
|
|
*
|
|
* @param int $link link type
|
|
*/
|
|
public function moreResults($link = DatabaseInterface::CONNECT_USER): bool;
|
|
|
|
/**
|
|
* Prepare next result from multi_query
|
|
*
|
|
* @param int $link link type
|
|
*/
|
|
public function nextResult($link = DatabaseInterface::CONNECT_USER): bool;
|
|
|
|
/**
|
|
* Store the result returned from multi query
|
|
*
|
|
* @param int $link link type
|
|
*
|
|
* @return mixed false when empty results / result set when not empty
|
|
*/
|
|
public function storeResult($link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* Returns a string representing the type of connection used
|
|
*
|
|
* @param int $link link type
|
|
*
|
|
* @return string|bool type of connection used
|
|
*/
|
|
public function getHostInfo($link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* Returns the version of the MySQL protocol used
|
|
*
|
|
* @param int $link link type
|
|
*
|
|
* @return int|bool version of the MySQL protocol used
|
|
*/
|
|
public function getProtoInfo($link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* returns a string that represents the client library version
|
|
*
|
|
* @return string MySQL client library version
|
|
*/
|
|
public function getClientInfo(): string;
|
|
|
|
/**
|
|
* Returns last error message or an empty string if no errors occurred.
|
|
*
|
|
* @param int $link link type
|
|
*/
|
|
public function getError($link = DatabaseInterface::CONNECT_USER): string;
|
|
|
|
/**
|
|
* returns the number of rows returned by last query
|
|
* used with tryQuery as it accepts false
|
|
*
|
|
* @param string $query query to run
|
|
*
|
|
* @return string|int
|
|
* @psalm-return int|numeric-string
|
|
*/
|
|
public function queryAndGetNumRows(string $query);
|
|
|
|
/**
|
|
* returns last inserted auto_increment id for given $link
|
|
* or $GLOBALS['userlink']
|
|
*
|
|
* @param int $link link type
|
|
*
|
|
* @return int
|
|
*/
|
|
public function insertId($link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* returns the number of rows affected by last query
|
|
*
|
|
* @param int $link link type
|
|
* @param bool $get_from_cache whether to retrieve from cache
|
|
*
|
|
* @return int|string
|
|
* @psalm-return int|numeric-string
|
|
*/
|
|
public function affectedRows($link = DatabaseInterface::CONNECT_USER, bool $get_from_cache = true);
|
|
|
|
/**
|
|
* returns metainfo for fields in $result
|
|
*
|
|
* @param ResultInterface $result result set identifier
|
|
*
|
|
* @return FieldMetadata[] meta info for fields in $result
|
|
*/
|
|
public function getFieldsMeta(ResultInterface $result): array;
|
|
|
|
/**
|
|
* returns properly escaped string for use in MySQL queries
|
|
*
|
|
* @param string $str string to be escaped
|
|
* @param mixed $link optional database link to use
|
|
*
|
|
* @return string a MySQL escaped string
|
|
*/
|
|
public function escapeString(string $str, $link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* returns properly escaped string for use in MySQL LIKE clauses
|
|
*
|
|
* @param string $str string to be escaped
|
|
* @param int $link optional database link to use
|
|
*
|
|
* @return string a MySQL escaped LIKE string
|
|
*/
|
|
public function escapeMysqlLikeString(string $str, int $link = DatabaseInterface::CONNECT_USER);
|
|
|
|
/**
|
|
* Checks if this database server is running on Amazon RDS.
|
|
*/
|
|
public function isAmazonRds(): bool;
|
|
|
|
/**
|
|
* Gets SQL for killing a process.
|
|
*
|
|
* @param int $process Process ID
|
|
*/
|
|
public function getKillQuery(int $process): string;
|
|
|
|
/**
|
|
* Get the phpmyadmin database manager
|
|
*/
|
|
public function getSystemDatabase(): SystemDatabase;
|
|
|
|
/**
|
|
* Get a table with database name and table name
|
|
*
|
|
* @param string $db_name DB name
|
|
* @param string $table_name Table name
|
|
*/
|
|
public function getTable(string $db_name, string $table_name): Table;
|
|
|
|
/**
|
|
* returns collation of given db
|
|
*
|
|
* @param string $db name of db
|
|
*
|
|
* @return string collation of $db
|
|
*/
|
|
public function getDbCollation(string $db): string;
|
|
|
|
/**
|
|
* returns default server collation from show variables
|
|
*/
|
|
public function getServerCollation(): string;
|
|
|
|
/**
|
|
* Server version as number
|
|
*/
|
|
public function getVersion(): int;
|
|
|
|
/**
|
|
* Server version
|
|
*/
|
|
public function getVersionString(): string;
|
|
|
|
/**
|
|
* Server version comment
|
|
*/
|
|
public function getVersionComment(): string;
|
|
|
|
/**
|
|
* Whether connection is MariaDB
|
|
*/
|
|
public function isMariaDB(): bool;
|
|
|
|
/**
|
|
* Whether connection is Percona
|
|
*/
|
|
public function isPercona(): bool;
|
|
|
|
/**
|
|
* Prepare an SQL statement for execution.
|
|
*
|
|
* @param string $query The query, as a string.
|
|
* @param int $link Link type.
|
|
*
|
|
* @return object|false A statement object or false.
|
|
*/
|
|
public function prepare(string $query, $link = DatabaseInterface::CONNECT_USER);
|
|
}
|