Abstract class representing moodle database interface. More...

Inheritance diagram for moodle_database:

Public Member Functions
	__construct ($external=false)
	Constructor - Instantiates the database, specifying if it's external (connect to other systems) or not (Moodle DB). More...

	__destruct ()
	Destructor - cleans up and flushes everything needed.

	change_database_structure ($sql, $tablenames=null)
	Do NOT use in code, this is for use by database_manager only! More...

	change_db_encoding ()
	Attempts to change db encoding to UTF-8 encoding if possible. More...

	commit_delegated_transaction (moodle_transaction $transaction)
	Indicates delegated transaction finished successfully. More...

	connect ($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions=null)
	Connects to the database. More...

	count_records ($table, array $conditions=null)
	Count the records in a table where all the given conditions met. More...

	count_records_select ($table, $select, array $params=null, $countitem="COUNT('x')")
	Count the records in a table which match a particular WHERE clause. More...

	count_records_sql ($sql, array $params=null)
	Get the result of a SQL SELECT COUNT(...) query. More...

	create_database ($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null)
	Attempt to create the database. More...

	delete_records ($table, array $conditions=null)
	Delete the records from a table where all the given conditions met. More...

	delete_records_list ($table, $field, array $values)
	Delete the records from a table where one field match one list of values. More...

	delete_records_select ($table, $select, array $params=null)
	Delete one or more records from a table which match a particular WHERE clause. More...

	delete_records_subquery (string $table, string $field, string $alias, string $subquery, array $params=[])
	Deletes records from a table using a subquery. More...

	diagnose ()
	Diagnose database and tables, this function is used to verify database and driver settings, db engine types, etc. More...

	dispose ()
	Closes the database connection and releases all resources and memory (especially circular memory references). More...

	driver_installed ()
	Detects if all needed PHP stuff are installed for DB connectivity. More...

	execute ($sql, array $params=null)
	Executes a general sql query. More...

	export_dbconfig ()
	Returns the db related part of config.php. More...

	export_table_recordset ($table)
	Get all records from a table. More...

	fix_sql_params ($sql, array $params=null)
	Normalizes sql query parameters and verifies parameters. More...

	force_transaction_rollback ()
	Force rollback of all delegated transaction. More...

	get_columns ($table, $usecache=true)
	Returns detailed information about columns in table. More...

	get_configuration_help ()
	Returns the localised database configuration help. More...

	get_configuration_hints ()
	Returns the localised database description Note: can be used before connect() More...

	get_dbfamily ()
	Returns the database family type. More...

	get_dbvendor ()
	Returns the database vendor. More...

	get_debug ()
	Returns debug status. More...

	get_field ($table, $return, array $conditions, $strictness=IGNORE_MISSING)
	Get a single field value from a table record where all the given conditions met. More...

	get_field_select ($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING)
	Get a single field value from a table record which match a particular WHERE clause. More...

	get_field_sql ($sql, array $params=null, $strictness=IGNORE_MISSING)
	Get a single field value (first field) using a SQL statement. More...

	get_fieldset_select ($table, $return, $select, array $params=null)
	Selects records and return values of chosen field as an array which match a particular WHERE clause. More...

	get_fieldset_sql ($sql, array $params=null)
	Selects records and return values (first field) as an array using a SQL statement. More...

	get_in_or_equal ($items, $type=SQL_PARAMS_QM, $prefix='param', $equal=true, $onemptyitems=false)
	Constructs 'IN()' or '=' sql fragment. More...

	get_indexes ($table)
	Return table indexes - everything lowercased. More...

	get_last_error ()
	Returns the last error reported by the database engine. More...

	get_manager ()
	Returns the sql generator used for db manipulation. More...

	get_name ()
	Returns the localised database type name Note: can be used before connect() More...

	get_prefix ()
	Returns database table prefix Note: can be used before connect() More...

	get_record ($table, array $conditions, $fields=' *', $strictness=IGNORE_MISSING)
	Get a single database record as an object where all the given conditions met. More...

	get_record_select ($table, $select, array $params=null, $fields=' *', $strictness=IGNORE_MISSING)
	Get a single database record as an object which match a particular WHERE clause. More...

	get_record_sql ($sql, array $params=null, $strictness=IGNORE_MISSING)
	Get a single database record as an object using a SQL statement. More...

	get_records ($table, array $conditions=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as an array of objects where all the given conditions met. More...

	get_records_list ($table, $field, array $values, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as an array of objects where one field match one list of values. More...

	get_records_menu ($table, array $conditions=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get the first two columns from a number of records as an associative array where all the given conditions met. More...

	get_records_select ($table, $select, array $params=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as an array of objects which match a particular WHERE clause. More...

	get_records_select_menu ($table, $select, array $params=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get the first two columns from a number of records as an associative array which match a particular WHERE clause. More...

	get_records_sql ($sql, array $params=null, $limitfrom=0, $limitnum=0)
	Get a number of records as an array of objects using a SQL statement. More...

	get_records_sql_menu ($sql, array $params=null, $limitfrom=0, $limitnum=0)
	Get the first two columns from a number of records as an associative array using a SQL statement. More...

	get_recordset ($table, array $conditions=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as a moodle_recordset where all the given conditions met. More...

	get_recordset_list ($table, $field, array $values, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as a moodle_recordset where one field match one list of values. More...

	get_recordset_select ($table, $select, array $params=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Get a number of records as a moodle_recordset which match a particular WHERE clause. More...

	get_recordset_sql ($sql, array $params=null, $limitfrom=0, $limitnum=0)
	Get a number of records as a moodle_recordset using a SQL statement. More...

	get_server_info ()
	Returns database server info array. More...

	get_session_lock ($rowid, $timeout)
	Obtains the session lock. More...

	get_tables ($usecache=true)
	Return tables in database WITHOUT current prefix. More...

	get_transaction_start_backtrace ()
	Returns transaction trace for debugging purposes. More...

	import_record ($table, $dataobject)
	Import a record into a table, id field is required. More...

	insert_record ($table, $dataobject, $returnid=true, $bulk=false)
	Insert a record into a table and return the "id" field if required. More...

	insert_record_raw ($table, $params, $returnid=true, $bulk=false, $customsequence=false)
	Insert new record into database, as fast as possible, no safety checks, lobs not supported. More...

	insert_records ($table, $dataobjects)
	Insert multiple records into database as fast as possible. More...

	is_fulltext_search_supported ()
	Whether the database is able to support full-text search or not. More...

	is_transaction_started ()
	Returns true if a transaction is in progress. More...

	perf_get_queries ()
	Returns the number of queries done by this database. More...

	perf_get_queries_time ()
	Time waiting for the database engine to finish running all queries. More...

	perf_get_reads ()
	Returns the number of reads done by this database. More...

	perf_get_writes ()
	Returns the number of writes done by this database. More...

	query_log ($error=false)
	This logs the last query based on 'logall', 'logslow' and 'logerrors' options configured via $CFG->dboptions . More...

	record_exists ($table, array $conditions)
	Test whether a record exists in a table where all the given conditions met. More...

	record_exists_select ($table, $select, array $params=null)
	Test whether any records exists in a table which match a particular WHERE clause. More...

	record_exists_sql ($sql, array $params=null)
	Test whether a SQL SELECT statement returns any records. More...

	release_session_lock ($rowid)
	Releases the session lock. More...

	replace_all_text ($table, database_column_info $column, $search, $replace)
	Replace given text in all rows of column. More...

	replace_all_text_supported ()
	Does this driver support tool_replace? More...

	reset_caches ($tablenames=null)
	Resets the internal column details cache. More...

	rollback_delegated_transaction (moodle_transaction $transaction, $e)
	Call when delegated transaction failed, this rolls back all delegated transactions up to the top most level. More...

	session_lock_supported ()
	Is session lock supported in this driver? More...

	set_debug ($state)
	Enable/disable very detailed debugging. More...

	set_field ($table, $newfield, $newvalue, array $conditions=null)
	Set a single field in every table record where all the given conditions met. More...

	set_field_select ($table, $newfield, $newvalue, $select, array $params=null)
	Set a single field in every table record which match a particular WHERE clause. More...

	set_logging ($state)
	Enable/disable detailed sql logging. More...

	setup_is_unicodedb ()
	Checks to see if the database is in unicode mode? More...

	sql_bitand ($int1, $int2)
	Returns the SQL text to be used in order to perform one bitwise AND operation between 2 integers. More...

	sql_bitnot ($int1)
	Returns the SQL text to be used in order to perform one bitwise NOT operation with 1 integer. More...

	sql_bitor ($int1, $int2)
	Returns the SQL text to be used in order to perform one bitwise OR operation between 2 integers. More...

	sql_bitxor ($int1, $int2)
	Returns the SQL text to be used in order to perform one bitwise XOR operation between 2 integers. More...

	sql_cast_2signed ($fieldname)
	Returns the SQL to be used in order to an UNSIGNED INTEGER column to SIGNED. More...

	sql_cast_char2int ($fieldname, $text=false)
	Returns the SQL to be used in order to CAST one CHAR column to INTEGER. More...

	sql_cast_char2real ($fieldname, $text=false)
	Returns the SQL to be used in order to CAST one CHAR column to REAL number. More...

	sql_ceil ($fieldname)
	Returns the cross db correct CEIL (ceiling) expression applied to fieldname. More...

	sql_compare_text ($fieldname, $numchars=32)
	Returns the SQL text to be used to compare one TEXT (clob) column with one varchar column, because some RDBMS doesn't support such direct comparisons. More...

	sql_concat ()
	Returns the proper SQL to do CONCAT between the elements(fieldnames) passed. More...

	sql_concat_join ($separator="' '", $elements=array())
	Returns the proper SQL to do CONCAT between the elements passed with a given separator. More...

	sql_empty ()
	This used to return empty string replacement character. More...

	sql_equal ($fieldname, $param, $casesensitive=true, $accentsensitive=true, $notequal=false)
	Returns an equal (=) or not equal (<>) part of a query. More...

	sql_fullname ($first='firstname', $last='lastname')
	Returns the proper SQL (for the dbms in use) to concatenate $firstname and $lastname. More...

	sql_intersect ($selects, $fields)
	Returns the SQL that allows to find intersection of two or more queries. More...

	sql_isempty ($tablename, $fieldname, $nullablefield, $textfield)
	Returns the proper SQL to know if one field is empty. More...

	sql_isnotempty ($tablename, $fieldname, $nullablefield, $textfield)
	Returns the proper SQL to know if one field is not empty. More...

	sql_length ($fieldname)
	Returns the SQL text to be used to calculate the length in characters of one expression. More...

	sql_like ($fieldname, $param, $casesensitive=true, $accentsensitive=true, $notlike=false, $escapechar='\\')
	Returns 'LIKE' part of a query. More...

	sql_like_escape ($text, $escapechar='\\')
	Escape sql LIKE special characters like '_' or ''. More...

	sql_modulo ($int1, $int2)
	Returns the SQL text to be used in order to perform module '' operation - remainder after division. More...

	sql_null_from_clause ()
	Returns the FROM clause required by some DBs in all SELECT statements. More...

	sql_order_by_text ($fieldname, $numchars=32)
	Returns the SQL text to be used to order by one TEXT (clob) column, because some RDBMS doesn't support direct ordering of such fields. More...

	sql_position ($needle, $haystack)
	Returns the SQL for returning searching one string for the location of another. More...

	sql_regex ($positivematch=true, $casesensitive=false)
	Returns the driver specific syntax (SQL part) for matching regex positively or negatively (inverted matching). More...

	sql_regex_supported ()
	Returns true if this database driver supports regex syntax when searching. More...

	sql_substr ($expr, $start, $length=false)
	Returns the proper substr() SQL text used to extract substrings from DB NOTE: this was originally returning only function name. More...

	start_delegated_transaction ()
	On DBs that support it, switch to transaction mode and begin a transaction you'll need to ensure you call allow_commit() on the returned object or your changes will be lost. More...

	transactions_forbidden ()
	This is a test that throws an exception if transaction in progress. More...

	update_record ($table, $dataobject, $bulk=false)
	Update a record in a table. More...

	update_record_raw ($table, $params, $bulk=false)
	Update record in database, as fast as possible, no safety checks, lobs not supported. More...

	update_temp_table_stats ()
	Analyze the data in temporary tables to force statistics collection after bulk data loads. More...

Static Public Member Functions
static	get_driver_instance ($type, $library, $external=false)
	Loads and returns a database instance with the specified type and library. More...

Protected Member Functions
	allowed_param_types ()
	Returns supported query parameter types. More...

	begin_transaction ()
	Driver specific start of real database transaction, this can not be used directly in code. More...

	commit_transaction ()
	Driver specific commit of real database transaction, this can not be used directly in code. More...

	detect_objects ($value)
	Detects object parameters and throws exception if found. More...

	fix_table_name ($tablename)
	Adds the prefix to the table name. More...

	fix_table_names ($sql)
	Converts short table name {tablename} to the real prefixed table name in given sql. More...

	get_dblibrary ()
	Returns the general database library name Note: can be used before connect() More...

	get_dbtype ()
	Returns a more specific database driver type Note: can be used before connect() More...

	get_metacache ()
	Handle the creation and caching of the databasemeta information for all databases. More...

	get_settings_hash ()
	Returns a hash for the settings used during connection. More...

	get_temp_tables_cache ()
	Handle the creation and caching of the temporary tables. More...

	normalise_limit_from_num ($limitfrom, $limitnum)
	Ensures that limit params are numeric and positive integers, to be passed to the database. More...

	normalise_value ($column, $value)
	Normalise values based on varying RDBMS's dependencies (booleans, LOBs...) More...

	print_debug ($sql, array $params=null, $obj=null)
	Prints sql debug info. More...

	print_debug_time ()
	Prints the time a query took to run. More...

	query_end ($result)
	This should be called immediately after each db query. More...

	query_log_allow ()
	Restore old logging behavior.

	query_log_prevent ()
	Disable logging temporarily.

	query_start ($sql, array $params=null, $type, $extrainfo=null)
	This should be called before each db query. More...

	query_time ()
	Returns the time elapsed since the query started. More...

	rollback_transaction ()
	Driver specific abort of real database transaction, this can not be used directly in code. More...

	store_settings ($dbhost, $dbuser, $dbpass, $dbname, $prefix, array $dboptions=null)
	Store various database settings. More...

	transactions_supported ()
	Checks and returns true if transactions are supported. More...

	where_clause ($table, array $conditions=null)
	Returns the SQL WHERE conditions. More...

	where_clause_list ($field, array $values)
	Returns SQL WHERE conditions for the ..._list group of methods. More...

Protected Attributes
database_manager	$database_manager
	db manager which allows db structure modifications.

string	$dbhost
	db host name.

string	$dbname
	db name.

array	$dboptions
	Database or driver specific options, such as sockets or TCP/IP db connections.

string	$dbpass
	db host password.

string	$dbuser
	db host user.

int	$debug = 0
	Debug level.

bool	$disposed
	flag marking database instance as disposed

bool	$external
	True means non-moodle external database used.

string	$last_extrainfo
	Last extra info.

array	$last_params
	Last query parameters.

string	$last_sql
	Last used query sql.

float	$last_time
	Last time in seconds with millisecond precision.

int	$last_type
	Last query type.

cache_application	$metacache
	for column info

cache_request	$metacachetemp
	for column info on temp tables

string	$prefix
	Prefix added to table names.

float	$queriestime = 0
	Time queries took to finish, seconds with microseconds.

int	$reads = 0
	The database reads (performance counter).

boolean	$skiplogging = false
	variable use to temporarily disable logging.

array	$tables = null
	Cache of table info.

moodle_temptables	$temptables
	temptables manager to provide cross-db support for temp tables.

bool	$used_for_db_sessions = false
	True if the db is used for db sessions.

int	$writes = 0
	The database writes (performance counter).

Detailed Description

Abstract class representing moodle database interface.

@externalurl http://docs.moodle.org/dev/DML_functions

Copyright: 2008 Petr Skoda (http://skodak.org)

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

moodle_database::__construct ( $external = false )

Constructor - Instantiates the database, specifying if it's external (connect to other systems) or not (Moodle DB).

Note that this affects the decision of whether prefix checks must be performed or not.

Parameters

bool $external True means that an external database is used.

Reimplemented in sqlsrv_native_moodle_database, and pdo_moodle_database.

Member Function Documentation

◆ allowed_param_types()

moodle_database::allowed_param_types ( )

abstractprotected

Returns supported query parameter types.

Return values

int	bitmask of accepted SQL_PARAMS_*

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ begin_transaction()

moodle_database::begin_transaction ( )

abstractprotected

Driver specific start of real database transaction, this can not be used directly in code.

Return values

void

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ change_database_structure()

moodle_database::change_database_structure	(	$sql,
		$tablenames = `null`
	)

abstract

Do NOT use in code, this is for use by database_manager only!

Parameters

string \| array	$sql	query or array of queries
array \| null	$tablenames	an array of xmldb table names affected by this request.

Return values

bool true

Exceptions

ddl_change_structure_exception A DDL specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ change_db_encoding()

moodle_database::change_db_encoding ( )

Attempts to change db encoding to UTF-8 encoding if possible.

Return values

bool	True is successful.

◆ commit_delegated_transaction()

moodle_database::commit_delegated_transaction ( moodle_transaction $transaction )

Indicates delegated transaction finished successfully.

The real database transaction is committed only if all delegated transactions committed.

Parameters

moodle_transaction $transaction The transaction to commit

Return values

void

Exceptions

dml_transaction_exception Creates and throws transaction related exceptions.

◆ commit_transaction()

moodle_database::commit_transaction ( )

abstractprotected

Driver specific commit of real database transaction, this can not be used directly in code.

Return values

void

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ connect()

moodle_database::connect	(		$dbhost,
			$dbuser,
			$dbpass,
			$dbname,
			$prefix,
		array	$dboptions = `null`
	)

abstract

Connects to the database.

Must be called before other methods.

Parameters

string	$dbhost	The database host.
string	$dbuser	The database user to connect as.
string	$dbpass	The password to use when connecting to the database.
string	$dbname	The name of the database being connected to.
mixed	$prefix	string means moodle db prefix, false used for external databases where prefix not used
array	$dboptions	driver specific options

Return values

bool true

Exceptions

dml_connection_exception if error

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ count_records()

moodle_database::count_records	(		$table,
		array	$conditions = `null`
	)

Count the records in a table where all the given conditions met.

Parameters

string	$table	The table to query.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between

Return values

int	The count of records returned from the specified criteria.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ count_records_select()

moodle_database::count_records_select	(		$table,
			$select,
		array	$params = `null`,
			$countitem = `"COUNT('x')"`
	)

Count the records in a table which match a particular WHERE clause.

Parameters

string	$table	The database table to be checked against.
string	$select	A fragment of SQL to be used in a WHERE clause in the SQL call.
array	$params	array of sql parameters
string	$countitem	The count string to be used in the SQL call. Default is COUNT('x').

Return values

int	The count of records returned from the specified criteria.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ count_records_sql()

moodle_database::count_records_sql	(		$sql,
		array	$params = `null`
	)

Get the result of a SQL SELECT COUNT(...) query.

Given a query that counts rows, return that count. (In fact, given any query, return the first field of the first record returned. However, this method should only be used for the intended purpose.) If an error occurs, 0 is returned.

Parameters

string	$sql	The SQL string you wish to be executed.
array	$params	array of sql parameters

Return values

int the count

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ create_database()

moodle_database::create_database	(		$dbhost,
			$dbuser,
			$dbpass,
			$dbname,
		array	$dboptions = `null`
	)

Attempt to create the database.

Parameters

string	$dbhost	The database host.
string	$dbuser	The database user to connect as.
string	$dbpass	The password to use when connecting to the database.
string	$dbname	The name of the database being connected to.
array	$dboptions	An array of optional database options (eg: dbport)

Return values

bool	success True for successful connection. False otherwise.

Reimplemented in mysqli_native_moodle_database.

◆ delete_records()

moodle_database::delete_records	(		$table,
		array	$conditions = `null`
	)

Delete the records from a table where all the given conditions met.

If conditions not specified, table is truncated.

Parameters

string	$table	the table to delete from.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between

Return values

bool true.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ delete_records_list()

moodle_database::delete_records_list	(		$table,
			$field,
		array	$values
	)

Delete the records from a table where one field match one list of values.

Parameters

string	$table	the table to delete from.
string	$field	The field to search
array	$values	array of values

Return values

bool true.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ delete_records_select()

moodle_database::delete_records_select	(		$table,
			$select,
		array	$params = `null`
	)

abstract

Delete one or more records from a table which match a particular WHERE clause.

Parameters

string	$table	The database table to be checked against.
string	$select	A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
array	$params	array of sql parameters

Return values

bool true.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ delete_records_subquery()

moodle_database::delete_records_subquery	(	string	$table,
		string	$field,
		string	$alias,
		string	$subquery,
		array	$params = `[]`
	)

Deletes records from a table using a subquery.

The subquery should return a list of values in a single column, which match one field from the table being deleted.

The $alias parameter must be set to the name of the single column in your subquery result (e.g. if the subquery is 'SELECT id FROM whatever', then it should be 'id'). This is not needed on most databases, but MySQL requires it.

(On database where the subquery is inefficient, it is implemented differently.)

Parameters

string	$table	Table to delete from
string	$field	Field in table to match
string	$alias	Name of single column in subquery e.g. 'id'
string	$subquery	Subquery that will return values of the field to delete
array	$params	Parameters for subquery

Exceptions

dml_exception If there is any error

Since: Moodle 3.8.6

Reimplemented in mysqli_native_moodle_database.

◆ detect_objects()

moodle_database::detect_objects ( $value )

protected

Detects object parameters and throws exception if found.

Parameters

mixed $value

Return values

void

Exceptions

coding_exception if object detected

◆ diagnose()

moodle_database::diagnose ( )

Diagnose database and tables, this function is used to verify database and driver settings, db engine types, etc.

Return values

string null means everything ok, string means problem found.

Reimplemented in sqlsrv_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ dispose()

moodle_database::dispose ( )

Closes the database connection and releases all resources and memory (especially circular memory references).

Do NOT use connect() again, create a new instance if needed.

Return values

void

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ driver_installed()

moodle_database::driver_installed ( )

abstract

Detects if all needed PHP stuff are installed for DB connectivity.

Note: can be used before connect()

Return values

mixed True if requirements are met, otherwise a string if something isn't installed.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ execute()

moodle_database::execute	(		$sql,
		array	$params = `null`
	)

abstract

Executes a general sql query.

Should be used only when no other method suitable. Do NOT use this to make changes in db structure, use database_manager methods instead!

Parameters

string	$sql	query
array	$params	query parameters

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ export_dbconfig()

moodle_database::export_dbconfig ( )

Returns the db related part of config.php.

Return values

stdClass

◆ export_table_recordset()

moodle_database::export_table_recordset ( $table )

Get all records from a table.

This method works around potential memory problems and may improve performance, this method may block access to table until the recordset is closed.

Parameters

string $table Name of database table.

Return values

moodle_recordset A moodle_recordset instance get_recordset.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in mysqli_native_moodle_database.

◆ fix_sql_params()

moodle_database::fix_sql_params	(		$sql,
		array	$params = `null`
	)

Normalizes sql query parameters and verifies parameters.

Parameters

string	$sql	The query or part of it.
array	$params	The query parameters.

Return values

array (sql, params, type of params)

◆ fix_table_name()

moodle_database::fix_table_name ( $tablename )

protected

Adds the prefix to the table name.

Parameters

string $tablename The table name

Return values

string The prefixed table name

Reimplemented in mysqli_native_moodle_database.

◆ fix_table_names()

moodle_database::fix_table_names ( $sql )

protected

Converts short table name {tablename} to the real prefixed table name in given sql.

Parameters

string $sql The sql to be operated on.

Return values

string The sql with tablenames being prefixed with $CFG->prefix

Reimplemented in sqlsrv_native_moodle_database, and oci_native_moodle_database.

◆ force_transaction_rollback()

moodle_database::force_transaction_rollback ( )

Force rollback of all delegated transaction.

Does not throw any exceptions and does not log anything.

This method should be used only from default exception handlers and other core code.

Return values

void

◆ get_columns()

moodle_database::get_columns	(	$table,
		$usecache = `true`
	)

abstract

Returns detailed information about columns in table.

This information is cached internally.

Parameters

string	$table	The table's name.
bool	$usecache	Flag to use internal cacheing. The default is true.

Return values

database_column_info[] of database_column_info objects indexed with column names

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_configuration_help()

moodle_database::get_configuration_help ( )

abstract

Returns the localised database configuration help.

Note: can be used before connect()

Return values

string

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ get_configuration_hints()

moodle_database::get_configuration_hints ( )

Returns the localised database description Note: can be used before connect()

Deprecated:: since 2.6

Return values

string

◆ get_dbfamily()

moodle_database::get_dbfamily ( )

abstract

Returns the database family type.

(This sort of describes the SQL 'dialect') Note: can be used before connect()

Return values

string The db family name (mysql, postgres, mssql, oracle, etc.)

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_dblibrary()

moodle_database::get_dblibrary ( )

abstractprotected

Returns the general database library name Note: can be used before connect()

Return values

string The db library type - pdo, native etc.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_dbtype()

moodle_database::get_dbtype ( )

abstractprotected

Returns a more specific database driver type Note: can be used before connect()

Return values

string The db type mysqli, pgsql, oci, mssql, sqlsrv

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ get_dbvendor()

moodle_database::get_dbvendor ( )

Returns the database vendor.

Note: can be used before connect()

Return values

string The db vendor name, usually the same as db family name.

Reimplemented in mariadb_native_moodle_database.

◆ get_debug()

moodle_database::get_debug ( )

Returns debug status.

Return values

bool::$state

◆ get_driver_instance()

static moodle_database::get_driver_instance	(	$type,
		$library,
		$external = `false`
	)

static

Loads and returns a database instance with the specified type and library.

The loaded class is within lib/dml directory and of the form: $type.'_'.$library.'_moodle_database'

Parameters

string	$type	Database driver's type. (eg: mysqli, pgsql, mssql, sqldrv, oci, etc.)
string	$library	Database driver's library (native, pdo, etc.)
bool	$external	True if this is an external database.

Return values

moodle_database driver object or null if error, for example of driver object see mysqli_native_moodle_database

◆ get_field()

moodle_database::get_field	(		$table,
			$return,
		array	$conditions,
			$strictness = `IGNORE_MISSING`
	)

Get a single field value from a table record where all the given conditions met.

Parameters

string	$table	the table to query.
string	$return	the field to return the value of.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means throw exception if no record or multiple records found

Return values

mixed the specified value false if not found

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_field_select()

moodle_database::get_field_select	(		$table,
			$return,
			$select,
		array	$params = `null`,
			$strictness = `IGNORE_MISSING`
	)

Get a single field value from a table record which match a particular WHERE clause.

Parameters

string	$table	the table to query.
string	$return	the field to return the value of.
string	$select	A fragment of SQL to be used in a where clause returning one row with one column
array	$params	array of sql parameters
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means throw exception if no record or multiple records found

Return values

mixed the specified value false if not found

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_field_sql()

moodle_database::get_field_sql	(		$sql,
		array	$params = `null`,
			$strictness = `IGNORE_MISSING`
	)

Get a single field value (first field) using a SQL statement.

Parameters

string	$sql	The SQL query returning one row with one column
array	$params	array of sql parameters
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means throw exception if no record or multiple records found

Return values

mixed the specified value false if not found

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_fieldset_select()

moodle_database::get_fieldset_select	(		$table,
			$return,
			$select,
		array	$params = `null`
	)

Selects records and return values of chosen field as an array which match a particular WHERE clause.

Parameters

string	$table	the table to query.
string	$return	the field we are intered in
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	array of sql parameters

Return values

array of values

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_fieldset_sql()

moodle_database::get_fieldset_sql	(		$sql,
		array	$params = `null`
	)

abstract

Selects records and return values (first field) as an array using a SQL statement.

Parameters

string	$sql	The SQL query
array	$params	array of sql parameters

Return values

array of values

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_in_or_equal()

moodle_database::get_in_or_equal	(	$items,
		$type = `SQL_PARAMS_QM`,
		$prefix = `'param'`,
		$equal = `true`,
		$onemptyitems = `false`
	)

Constructs 'IN()' or '=' sql fragment.

Parameters

mixed	$items	A single value or array of values for the expression.
int	$type	Parameter bounding type : SQL_PARAMS_QM or SQL_PARAMS_NAMED.
string	$prefix	Named parameter placeholder prefix (a unique counter value is appended to each parameter name).
bool	$equal	True means we want to equate to the constructed expression, false means we don't want to equate to it.
mixed	$onemptyitems	This defines the behavior when the array of items provided is empty. Defaults to false, meaning throw exceptions. Other values will become part of the returned SQL fragment.

Exceptions

coding_exception | dml_exception

Return values

array A list containing the constructed sql fragment and an array of parameters.

Reimplemented in oci_native_moodle_database.

◆ get_indexes()

moodle_database::get_indexes ( $table )

abstract

Return table indexes - everything lowercased.

Parameters

string $table The table we want to get indexes from.

Return values

array An associative array of indexes containing 'unique' flag and 'columns' being indexed

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_last_error()

moodle_database::get_last_error ( )

abstract

Returns the last error reported by the database engine.

Return values

string The error message.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_manager()

moodle_database::get_manager ( )

Returns the sql generator used for db manipulation.

Used mostly in upgrade.php scripts.

Return values

database_manager The instance used to perform ddl operations.

See also: lib/ddl/database_manager.php

◆ get_metacache()

moodle_database::get_metacache ( )

protected

Handle the creation and caching of the databasemeta information for all databases.

Return values

cache_application The databasemeta cachestore to complete operations on.

◆ get_name()

moodle_database::get_name ( )

abstract

Returns the localised database type name Note: can be used before connect()

Return values

string

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ get_prefix()

moodle_database::get_prefix ( )

Returns database table prefix Note: can be used before connect()

Return values

string The prefix used in the database.

◆ get_record()

moodle_database::get_record	(		$table,
		array	$conditions,
			$fields = `'*'`,
			$strictness = `IGNORE_MISSING`
	)

Get a single database record as an object where all the given conditions met.

Parameters

string	$table	The table to select from.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between
string	$fields	A comma separated list of fields to be returned from the chosen table.
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means we will throw an exception if no record or multiple records found.

Todo:: MDL-30407 MUST_EXIST option should not throw a dml_exception, it should throw a different exception as it's a requested check.

Return values

mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_record_select()

moodle_database::get_record_select	(		$table,
			$select,
		array	$params = `null`,
			$fields = `'*'`,
			$strictness = `IGNORE_MISSING`
	)

Get a single database record as an object which match a particular WHERE clause.

Parameters

string	$table	The database table to be checked against.
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	array of sql parameters
string	$fields	A comma separated list of fields to be returned from the chosen table.
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means throw exception if no record or multiple records found

Return values

stdClass|false a fieldset object containing the first matching record, false or exception if error not found depending on mode

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_record_sql()

moodle_database::get_record_sql	(		$sql,
		array	$params = `null`,
			$strictness = `IGNORE_MISSING`
	)

Get a single database record as an object using a SQL statement.

The SQL statement should normally only return one record. It is recommended to use get_records_sql() if more matches possible!

Parameters

string	$sql	The SQL string you wish to be executed, should normally only return one record.
array	$params	array of sql parameters
int	$strictness	IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended); MUST_EXIST means throw exception if no record or multiple records found

Return values

mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in oci_native_moodle_database.

◆ get_records()

moodle_database::get_records	(		$table,
		array	$conditions = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as an array of objects where all the given conditions met.

If the query succeeds and returns at least one record, the return value is an array of objects, one object for each record found. The array key is the value from the first column of the result set. The object associated with that key has a member variable for each column of the results.

Parameters

string	$table	the table to query.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between
string	$sort	an order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	a comma separated list of fields to return (optional, by default all fields are returned). The first field will be used as key for the array so must be a unique field such as 'id'.
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records in total (optional, required if $limitfrom is set).

Return values

array An array of Objects indexed by first column.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_records_list()

moodle_database::get_records_list	(		$table,
			$field,
		array	$values,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as an array of objects where one field match one list of values.

Return value is like get_records.

Parameters

string	$table	The database table to be checked against.
string	$field	The field to search
array	$values	An array of values
string	$sort	Sort order (as valid SQL sort parameter)
string	$fields	A comma separated list of fields to be returned from the chosen table. If specified, the first field should be a unique one such as 'id' since it will be used as a key in the associative array.
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records in total (optional).

Return values

array An array of objects indexed by first column

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_records_menu()

moodle_database::get_records_menu	(		$table,
		array	$conditions = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get the first two columns from a number of records as an associative array where all the given conditions met.

Arguments are like get_recordset.

If no errors occur the return value is an associative whose keys come from the first field of each record, and whose values are the corresponding second fields. False is returned if an error occurs.

Parameters

string	$table	the table to query.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between
string	$sort	an order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	a comma separated list of fields to return - the number of fields should be 2!
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

array an associative array

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_records_select()

moodle_database::get_records_select	(		$table,
			$select,
		array	$params = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as an array of objects which match a particular WHERE clause.

Return value is like get_records.

Parameters

string	$table	The table to query.
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	An array of sql parameters
string	$sort	An order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	A comma separated list of fields to return (optional, by default all fields are returned). The first field will be used as key for the array so must be a unique field such as 'id'.
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records in total (optional, required if $limitfrom is set).

Return values

array of objects indexed by first column

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_records_select_menu()

moodle_database::get_records_select_menu	(		$table,
			$select,
		array	$params = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get the first two columns from a number of records as an associative array which match a particular WHERE clause.

Arguments are like get_recordset_select}. * Return value is like function get_records_menu.

Parameters

string	$table	The database table to be checked against.
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	array of sql parameters
string	$sort	Sort order (optional) - a valid SQL order parameter
string	$fields	A comma separated list of fields to be returned from the chosen table - the number of fields should be 2!
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

array an associative array

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_records_sql()

moodle_database::get_records_sql	(		$sql,
		array	$params = `null`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

abstract

Get a number of records as an array of objects using a SQL statement.

Return value is like get_records.

Parameters

string	$sql	the SQL select query to execute. The first column of this SELECT statement must be a unique value (usually the 'id' field), as it will be used as the key of the returned array.
array	$params	array of sql parameters
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records in total (optional, required if $limitfrom is set).

Return values

array of objects indexed by first column

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_records_sql_menu()

moodle_database::get_records_sql_menu	(		$sql,
		array	$params = `null`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get the first two columns from a number of records as an associative array using a SQL statement.

Arguments are like get_recordset_sql}. * Return value is like function get_records_menu.

Parameters

string	$sql	The SQL string you wish to be executed.
array	$params	array of sql parameters
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

array an associative array

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_recordset()

moodle_database::get_recordset	(		$table,
		array	$conditions = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as a moodle_recordset where all the given conditions met.

Selects records from the table $table.

If specified, only records meeting $conditions.

If specified, the results will be sorted as specified by $sort. This is added to the SQL as "ORDER BY $sort". Example values of $sort might be "time ASC" or "time DESC".

If $fields is specified, only those fields are returned.

Since this method is a little less readable, use of it should be restricted to code where it's possible there might be large datasets being returned. For known small datasets use get_records - it leads to simpler code.

If you only want some of the records, specify $limitfrom and $limitnum. The query will skip the first $limitfrom records (according to the sort order) and then return the next $limitnum records. If either of $limitfrom or $limitnum is specified, both must be present.

The return value is a moodle_recordset if the query succeeds. If an error occurs, false is returned.

Parameters

string	$table	the table to query.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between
string	$sort	an order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	a comma separated list of fields to return (optional, by default all fields are returned).
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

moodle_recordset A moodle_recordset instance

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_recordset_list()

moodle_database::get_recordset_list	(		$table,
			$field,
		array	$values,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as a moodle_recordset where one field match one list of values.

Only records where $field takes one of the values $values are returned. $values must be an array of values.

Other arguments and the return type are like get_recordset.

Parameters

string	$table	the table to query.
string	$field	a field to check (optional).
array	$values	array of values the field must have
string	$sort	an order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	a comma separated list of fields to return (optional, by default all fields are returned).
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

moodle_recordset A moodle_recordset instance.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_recordset_select()

moodle_database::get_recordset_select	(		$table,
			$select,
		array	$params = `null`,
			$sort = `''`,
			$fields = `'*'`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

Get a number of records as a moodle_recordset which match a particular WHERE clause.

If given, $select is used as the SELECT parameter in the SQL query, otherwise all records from the table are returned.

Other arguments and the return type are like get_recordset.

Parameters

string	$table	the table to query.
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	array of sql parameters
string	$sort	an order to sort the results in (optional, a valid SQL ORDER BY parameter).
string	$fields	a comma separated list of fields to return (optional, by default all fields are returned).
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

moodle_recordset A moodle_recordset instance.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ get_recordset_sql()

moodle_database::get_recordset_sql	(		$sql,
		array	$params = `null`,
			$limitfrom = `0`,
			$limitnum = `0`
	)

abstract

Get a number of records as a moodle_recordset using a SQL statement.

Since this method is a little less readable, use of it should be restricted to code where it's possible there might be large datasets being returned. For known small datasets use get_records_sql - it leads to simpler code.

The return type is like get_recordset.

Parameters

string	$sql	the SQL select query to execute.
array	$params	array of sql parameters
int	$limitfrom	return a subset of records, starting at this point (optional).
int	$limitnum	return a subset comprising this many records (optional, required if $limitfrom is set).

Return values

moodle_recordset A moodle_recordset instance.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_server_info()

moodle_database::get_server_info ( )

abstract

Returns database server info array.

Return values

array Array containing 'description' and 'version' at least.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ get_session_lock()

moodle_database::get_session_lock	(	$rowid,
		$timeout
	)

Obtains the session lock.

Parameters

int	$rowid	The id of the row with session record.
int	$timeout	The maximum allowed time to wait for the lock in seconds.

Return values

void

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_settings_hash()

moodle_database::get_settings_hash ( )

protected

Returns a hash for the settings used during connection.

If not already requested it is generated and stored in a private property.

Return values

string

◆ get_tables()

moodle_database::get_tables ( $usecache = true )

abstract

Return tables in database WITHOUT current prefix.

Parameters

bool $usecache if true, returns list of cached tables.

Return values

array of table names in lowercase and without prefix

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ get_temp_tables_cache()

moodle_database::get_temp_tables_cache ( )

protected

Handle the creation and caching of the temporary tables.

Return values

cache_application The temp_tables cachestore to complete operations on.

◆ get_transaction_start_backtrace()

moodle_database::get_transaction_start_backtrace ( )

Returns transaction trace for debugging purposes.

to be used by core only

Return values

array or null if not in transaction.

◆ import_record()

moodle_database::import_record	(	$table,
		$dataobject
	)

abstract

Import a record into a table, id field is required.

Safety checks are NOT carried out. Lobs are supported.

Parameters

string	$table	name of database table to be inserted into
object	$dataobject	A data object with values for one or more fields in the record

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ insert_record()

moodle_database::insert_record	(	$table,
		$dataobject,
		$returnid = `true`,
		$bulk = `false`
	)

abstract

Insert a record into a table and return the "id" field if required.

Some conversions and safety checks are carried out. Lobs are supported. If the return ID isn't required, then this just reports success as true/false. $data is an object containing needed data

Parameters

string	$table	The database table to be inserted into
object	$dataobject	A data object with values for one or more fields in the record
bool	$returnid	Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
bool	$bulk	Set to true is multiple inserts are expected

Return values

bool|int true or new id

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ insert_record_raw()

moodle_database::insert_record_raw	(	$table,
		$params,
		$returnid = `true`,
		$bulk = `false`,
		$customsequence = `false`
	)

abstract

Insert new record into database, as fast as possible, no safety checks, lobs not supported.

Parameters

string	$table	name
mixed	$params	data record as object or array
bool	$returnid	Returns id of inserted record.
bool	$bulk	true means repeated inserts expected
bool	$customsequence	true if 'id' included in $params, disables $returnid

Return values

bool|int true or new id

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ insert_records()

moodle_database::insert_records	(	$table,
		$dataobjects
	)

Insert multiple records into database as fast as possible.

Order of inserts is maintained, but the operation is not atomic, use transactions if necessary.

This method is intended for inserting of large number of small objects, do not use for huge objects with text or binary fields.

Since: Moodle 2.7

Parameters

string	$table	The database table to be inserted into
array \| Traversable	$dataobjects	list of objects to be inserted, must be compatible with foreach

Return values

void	does not return new record ids

Exceptions

coding_exception	if data objects have different structure
dml_exception	A DML specific exception is thrown for any errors.

Reimplemented in pgsql_native_moodle_database, and mysqli_native_moodle_database.

◆ is_fulltext_search_supported()

moodle_database::is_fulltext_search_supported ( )

Whether the database is able to support full-text search or not.

Return values

bool

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ is_transaction_started()

moodle_database::is_transaction_started ( )

Returns true if a transaction is in progress.

Return values

bool

◆ normalise_limit_from_num()

moodle_database::normalise_limit_from_num	(	$limitfrom,
		$limitnum
	)

protected

Ensures that limit params are numeric and positive integers, to be passed to the database.

We explicitly treat null, '' and -1 as 0 in order to provide compatibility with how limit values have been passed historically.

Parameters

int	$limitfrom	Where to start results from
int	$limitnum	How many results to return

Return values

array Normalised limit params in array($limitfrom, $limitnum)

◆ normalise_value()

moodle_database::normalise_value	(	$column,
		$value
	)

abstractprotected

Normalise values based on varying RDBMS's dependencies (booleans, LOBs...)

Parameters

database_column_info	$column	column metadata corresponding with the value we are going to normalise
mixed	$value	value we are going to normalise

Return values

mixed the normalised value

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ perf_get_queries()

moodle_database::perf_get_queries ( )

Returns the number of queries done by this database.

Return values

int	Number of queries.

◆ perf_get_queries_time()

moodle_database::perf_get_queries_time ( )

Time waiting for the database engine to finish running all queries.

Return values

float Number of seconds with microseconds

◆ perf_get_reads()

moodle_database::perf_get_reads ( )

Returns the number of reads done by this database.

Return values

int	Number of reads.

◆ perf_get_writes()

moodle_database::perf_get_writes ( )

Returns the number of writes done by this database.

Return values

int	Number of writes.

◆ print_debug()

moodle_database::print_debug	(		$sql,
		array	$params = `null`,
			$obj = `null`
	)

protected

Prints sql debug info.

Parameters

string	$sql	The query which is being debugged.
array	$params	The query parameters. (optional)
mixed	$obj	The library specific object. (optional)

Return values

void

◆ print_debug_time()

moodle_database::print_debug_time ( )

protected

Prints the time a query took to run.

Return values

void

◆ query_end()

moodle_database::query_end ( $result )

protected

This should be called immediately after each db query.

It does a clean up of resources. It also throws exceptions if the sql that ran produced errors.

Parameters

mixed $result The db specific result obtained from running a query.

Exceptions

dml_read_exception | dml_write_exception | ddl_change_structure_exception

Return values

void

Reimplemented in sqlsrv_native_moodle_database, and pgsql_native_moodle_database.

◆ query_log()

moodle_database::query_log ( $error = false )

This logs the last query based on 'logall', 'logslow' and 'logerrors' options configured via $CFG->dboptions .

Parameters

string | bool $error or false if not error

Return values

void

◆ query_start()

moodle_database::query_start	(		$sql,
		array	$params = `null`,
			$type,
			$extrainfo = `null`
	)

protected

This should be called before each db query.

Parameters

string	$sql	The query string.
array	$params	An array of parameters.
int	$type	The type of query. ( SQL_QUERY_SELECT \| SQL_QUERY_AUX \| SQL_QUERY_INSERT \| SQL_QUERY_UPDATE \| SQL_QUERY_STRUCTURE )
mixed	$extrainfo	This is here for any driver specific extra information.

Return values

void

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, and oci_native_moodle_database.

◆ query_time()

moodle_database::query_time ( )

protected

Returns the time elapsed since the query started.

Return values

float Seconds with microseconds

◆ record_exists()

moodle_database::record_exists	(		$table,
		array	$conditions
	)

Test whether a record exists in a table where all the given conditions met.

Parameters

string	$table	The table to check.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between

Return values

bool	true if a matching record exists, else false.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ record_exists_select()

moodle_database::record_exists_select	(		$table,
			$select,
		array	$params = `null`
	)

Test whether any records exists in a table which match a particular WHERE clause.

Parameters

string	$table	The database table to be checked against.
string	$select	A fragment of SQL to be used in a WHERE clause in the SQL call.
array	$params	array of sql parameters

Return values

bool	true if a matching record exists, else false.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ record_exists_sql()

moodle_database::record_exists_sql	(		$sql,
		array	$params = `null`
	)

Test whether a SQL SELECT statement returns any records.

This function returns true if the SQL statement executes without any errors and returns at least one record.

Parameters

string	$sql	The SQL statement to execute.
array	$params	array of sql parameters

Return values

bool	true if the SQL executes without errors and returns at least one record.

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ release_session_lock()

moodle_database::release_session_lock ( $rowid )

Releases the session lock.

Parameters

int $rowid The id of the row with session record.

Return values

void

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ replace_all_text()

moodle_database::replace_all_text	(		$table,
		database_column_info	$column,
			$search,
			$replace
	)

Replace given text in all rows of column.

Since: Moodle 2.6.1

Parameters

string	$table	name of the table
database_column_info	$column
string	$search
string	$replace

◆ replace_all_text_supported()

moodle_database::replace_all_text_supported ( )

Does this driver support tool_replace?

Since: Moodle 2.6.1

Return values

bool

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ reset_caches()

moodle_database::reset_caches ( $tablenames = null )

Resets the internal column details cache.

Parameters

array | null $tablenames an array of xmldb table names affected by this request.

Return values

void

◆ rollback_delegated_transaction()

moodle_database::rollback_delegated_transaction	(	moodle_transaction	$transaction,
			$e
	)

Call when delegated transaction failed, this rolls back all delegated transactions up to the top most level.

In many cases you do not need to call this method manually, because all open delegated transactions are rolled back automatically if exceptions not caught.

Parameters

moodle_transaction	$transaction	An instance of a moodle_transaction.
Exception \| Throwable	$e	The related exception/throwable to this transaction rollback.

Return values

void	This does not return, instead the exception passed in will be rethrown.

◆ rollback_transaction()

moodle_database::rollback_transaction ( )

abstractprotected

Driver specific abort of real database transaction, this can not be used directly in code.

Return values

void

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ session_lock_supported()

moodle_database::session_lock_supported ( )

Is session lock supported in this driver?

Return values

bool

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ set_debug()

moodle_database::set_debug ( $state )

Enable/disable very detailed debugging.

Parameters

bool $state

Return values

void

◆ set_field()

moodle_database::set_field	(		$table,
			$newfield,
			$newvalue,
		array	$conditions = `null`
	)

Set a single field in every table record where all the given conditions met.

Parameters

string	$table	The database table to be checked against.
string	$newfield	the field to set.
string	$newvalue	the value to set the field to.
array	$conditions	optional array $fieldname=>requestedvalue with AND in between

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

◆ set_field_select()

moodle_database::set_field_select	(		$table,
			$newfield,
			$newvalue,
			$select,
		array	$params = `null`
	)

abstract

Set a single field in every table record which match a particular WHERE clause.

Parameters

string	$table	The database table to be checked against.
string	$newfield	the field to set.
string	$newvalue	the value to set the field to.
string	$select	A fragment of SQL to be used in a where clause in the SQL call.
array	$params	array of sql parameters

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ set_logging()

moodle_database::set_logging ( $state )

Enable/disable detailed sql logging.

Deprecated:: since Moodle 2.9

◆ setup_is_unicodedb()

moodle_database::setup_is_unicodedb ( )

Checks to see if the database is in unicode mode?

Return values

bool

Reimplemented in pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_bitand()

moodle_database::sql_bitand	(	$int1,
		$int2
	)

Returns the SQL text to be used in order to perform one bitwise AND operation between 2 integers.

NOTE: The SQL result is a number and can not be used directly in SQL condition, please compare it to some number to get a bool!!

Parameters

int	$int1	First integer in the operation.
int	$int2	Second integer in the operation.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in oci_native_moodle_database.

◆ sql_bitnot()

moodle_database::sql_bitnot ( $int1 )

Returns the SQL text to be used in order to perform one bitwise NOT operation with 1 integer.

Parameters

int $int1 The operand integer in the operation.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in oci_native_moodle_database.

◆ sql_bitor()

moodle_database::sql_bitor	(	$int1,
		$int2
	)

Returns the SQL text to be used in order to perform one bitwise OR operation between 2 integers.

NOTE: The SQL result is a number and can not be used directly in SQL condition, please compare it to some number to get a bool!!

Parameters

int	$int1	The first operand integer in the operation.
int	$int2	The second operand integer in the operation.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in oci_native_moodle_database.

◆ sql_bitxor()

moodle_database::sql_bitxor	(	$int1,
		$int2
	)

Returns the SQL text to be used in order to perform one bitwise XOR operation between 2 integers.

NOTE: The SQL result is a number and can not be used directly in SQL condition, please compare it to some number to get a bool!!

Parameters

int	$int1	The first operand integer in the operation.
int	$int2	The second operand integer in the operation.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in pgsql_native_moodle_database, and oci_native_moodle_database.

◆ sql_cast_2signed()

moodle_database::sql_cast_2signed ( $fieldname )

Returns the SQL to be used in order to an UNSIGNED INTEGER column to SIGNED.

(Only MySQL needs this. MySQL things that 1 * -1 = 18446744073709551615 if the 1 comes from an unsigned column).

Deprecated:: since 2.3

Parameters

string $fieldname The name of the field to be cast

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in mysqli_native_moodle_database.

◆ sql_cast_char2int()

moodle_database::sql_cast_char2int	(	$fieldname,
		$text = `false`
	)

Returns the SQL to be used in order to CAST one CHAR column to INTEGER.

Be aware that the CHAR column you're trying to cast contains really int values or the RDBMS will throw an error!

Parameters

string	$fieldname	The name of the field to be casted.
bool	$text	Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_cast_char2real()

moodle_database::sql_cast_char2real	(	$fieldname,
		$text = `false`
	)

Returns the SQL to be used in order to CAST one CHAR column to REAL number.

Be aware that the CHAR column you're trying to cast contains really numbers or the RDBMS will throw an error!

Parameters

string	$fieldname	The name of the field to be casted.
bool	$text	Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_ceil()

moodle_database::sql_ceil ( $fieldname )

Returns the cross db correct CEIL (ceiling) expression applied to fieldname.

note: Most DBs use CEIL(), hence it's the default here.

Parameters

string $fieldname The field (or expression) we are going to ceil.

Return values

string The piece of SQL code to be used in your ceiling statement.

Reimplemented in sqlsrv_native_moodle_database.

◆ sql_compare_text()

moodle_database::sql_compare_text	(	$fieldname,
		$numchars = `32`
	)

Returns the SQL text to be used to compare one TEXT (clob) column with one varchar column, because some RDBMS doesn't support such direct comparisons.

Parameters

string	$fieldname	The name of the TEXT field we need to order by
int	$numchars	Number of chars to use for the ordering (defaults to 32).

Return values

string The piece of SQL code to be used in your statement.

◆ sql_concat()

moodle_database::sql_concat ( )

abstract

Returns the proper SQL to do CONCAT between the elements(fieldnames) passed.

This function accepts variable number of string parameters. All strings/fieldnames will used in the SQL concatenate statement generated.

Return values

string The SQL to concatenate strings passed in. @uses func_get_args() and thus parameters are unlimited OPTIONAL number of additional field names.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_concat_join()

moodle_database::sql_concat_join	(	$separator = `"' '"`,
		$elements = `array()`
	)

abstract

Returns the proper SQL to do CONCAT between the elements passed with a given separator.

Parameters

string	$separator	The separator desired for the SQL concatenating $elements.
array	$elements	The array of strings to be concatenated.

Return values

string The SQL to concatenate the strings.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_empty()

moodle_database::sql_empty ( )

This used to return empty string replacement character.

Deprecated:: use bound parameter with empty string instead

Return values

string An empty string.

◆ sql_equal()

moodle_database::sql_equal	(	$fieldname,
		$param,
		$casesensitive = `true`,
		$accentsensitive = `true`,
		$notequal = `false`
	)

Returns an equal (=) or not equal (<>) part of a query.

Note the use of this method may lead to slower queries (full scans) so use it only when needed and against already reduced data sets.

Since: Moodle 3.2

Parameters

string	$fieldname	Usually the name of the table column.
string	$param	Usually the bound query parameter (?, :named).
bool	$casesensitive	Use case sensitive search when set to true (default).
bool	$accentsensitive	Use accent sensitive search when set to true (default). (not all databases support accent insensitive)
bool	$notequal	True means not equal (<>)

Return values

string The SQL code fragment.

Reimplemented in sqlsrv_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_fullname()

moodle_database::sql_fullname	(	$first = `'firstname'`,
		$last = `'lastname'`
	)

Returns the proper SQL (for the dbms in use) to concatenate $firstname and $lastname.

Todo:: MDL-31233 This may not be needed here.

Parameters

string	$first	User's first name (default:'firstname').
string	$last	User's last name (default:'lastname').

Return values

string The SQL to concatenate strings.

◆ sql_intersect()

moodle_database::sql_intersect	(	$selects,
		$fields
	)

Returns the SQL that allows to find intersection of two or more queries.

Since: Moodle 2.8

Parameters

array	$selects	array of SQL select queries, each of them only returns fields with the names from $fields
string	$fields	comma-separated list of fields (used only by some DB engines)

Return values

string SQL query that will return only values that are present in each of selects

Reimplemented in mysqli_native_moodle_database.

◆ sql_isempty()

moodle_database::sql_isempty	(	$tablename,
		$fieldname,
		$nullablefield,
		$textfield
	)

Returns the proper SQL to know if one field is empty.

Note that the function behavior strongly relies on the parameters passed describing the field so, please, be accurate when specifying them.

Also, note that this function is not suitable to look for fields having NULL contents at all. It's all for empty values!

This function should be applied in all the places where conditions of the type:

... AND fieldname = '';

are being used. Final result for text fields should be:

... AND ' . sql_isempty('tablename', 'fieldname', true/false, true);

and for varchar fields result should be:

... AND fieldname = :empty; "; $params['empty'] = '';

(see parameters description below)

Parameters

string	$tablename	Name of the table (without prefix). Not used for now but can be necessary in the future if we want to use some introspection using meta information against the DB. /// TODO ///
string	$fieldname	Name of the field we are going to check
bool	$nullablefield	For specifying if the field is nullable (true) or no (false) in the DB.
bool	$textfield	For specifying if it is a text (also called clob) field (true) or a varchar one (false)

Return values

string the sql code to be added to check for empty values

Reimplemented in sqlsrv_native_moodle_database, and oci_native_moodle_database.

◆ sql_isnotempty()

moodle_database::sql_isnotempty	(	$tablename,
		$fieldname,
		$nullablefield,
		$textfield
	)

Returns the proper SQL to know if one field is not empty.

Note that the function behavior strongly relies on the parameters passed describing the field so, please, be accurate when specifying them.

This function should be applied in all the places where conditions of the type:

... AND fieldname != '';

are being used. Final result for text fields should be:

... AND ' . sql_isnotempty('tablename', 'fieldname', true/false, true/false);

and for varchar fields result should be:

... AND fieldname != :empty; "; $params['empty'] = '';

(see parameters description below)

Parameters

string	$tablename	Name of the table (without prefix). This is not used for now but can be necessary in the future if we want to use some introspection using meta information against the DB.
string	$fieldname	The name of the field we are going to check.
bool	$nullablefield	Specifies if the field is nullable (true) or not (false) in the DB.
bool	$textfield	Specifies if it is a text (also called clob) field (true) or a varchar one (false).

Return values

string The sql code to be added to check for non empty values.

◆ sql_length()

moodle_database::sql_length ( $fieldname )

Returns the SQL text to be used to calculate the length in characters of one expression.

Parameters

string $fieldname The fieldname/expression to calculate its length in characters.

Return values

string the piece of SQL code to be used in the statement.

Reimplemented in sqlsrv_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_like()

moodle_database::sql_like	(	$fieldname,
		$param,
		$casesensitive = `true`,
		$accentsensitive = `true`,
		$notlike = `false`,
		$escapechar = `'\\'`
	)

Returns 'LIKE' part of a query.

Parameters

string	$fieldname	Usually the name of the table column.
string	$param	Usually the bound query parameter (?, :named).
bool	$casesensitive	Use case sensitive search when set to true (default).
bool	$accentsensitive	Use accent sensitive search when set to true (default). (not all databases support accent insensitive)
bool	$notlike	True means "NOT LIKE".
string	$escapechar	The escape char for '' and '_'.

Return values

string The SQL code fragment.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_like_escape()

moodle_database::sql_like_escape	(	$text,
		$escapechar = `'\\'`
	)

Escape sql LIKE special characters like '_' or ''.

Parameters

string	$text	The string containing characters needing escaping.
string	$escapechar	The desired escape character, defaults to '\'.

Return values

string The escaped sql LIKE string.

◆ sql_modulo()

moodle_database::sql_modulo	(	$int1,
		$int2
	)

Returns the SQL text to be used in order to perform module '' operation - remainder after division.

Parameters

int	$int1	The first operand integer in the operation.
int	$int2	The second operand integer in the operation.

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in oci_native_moodle_database.

◆ sql_null_from_clause()

moodle_database::sql_null_from_clause ( )

Returns the FROM clause required by some DBs in all SELECT statements.

To be used in queries not having FROM clause to provide cross_db Most DBs don't need it, hence the default is ''

Return values

string

Reimplemented in oci_native_moodle_database.

◆ sql_order_by_text()

moodle_database::sql_order_by_text	(	$fieldname,
		$numchars = `32`
	)

Returns the SQL text to be used to order by one TEXT (clob) column, because some RDBMS doesn't support direct ordering of such fields.

Note that the use or queries being ordered by TEXT columns must be minimised, because it's really slooooooow.

Parameters

string	$fieldname	The name of the TEXT field we need to order by.
int	$numchars	The number of chars to use for the ordering (defaults to 32).

Return values

string The piece of SQL code to be used in your statement.

Reimplemented in sqlsrv_native_moodle_database, and oci_native_moodle_database.

◆ sql_position()

moodle_database::sql_position	(	$needle,
		$haystack
	)

Returns the SQL for returning searching one string for the location of another.

Note, there is no guarantee which order $needle, $haystack will be in the resulting SQL so when using this method, and both arguments contain placeholders, you should use named placeholders.

Parameters

string	$needle	the SQL expression that will be searched for.
string	$haystack	the SQL expression that will be searched in.

Return values

string The required searching SQL part.

Reimplemented in sqlsrv_native_moodle_database, and oci_native_moodle_database.

◆ sql_regex()

moodle_database::sql_regex	(	$positivematch = `true`,
		$casesensitive = `false`
	)

Returns the driver specific syntax (SQL part) for matching regex positively or negatively (inverted matching).

Eg: 'REGEXP':'NOT REGEXP' or '~*' : '!~*'

Parameters

bool	$positivematch
bool	$casesensitive

Return values

string or empty if not supported

Reimplemented in pgsql_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_regex_supported()

moodle_database::sql_regex_supported ( )

Returns true if this database driver supports regex syntax when searching.

Return values

bool	True if supported.

Reimplemented in pgsql_native_moodle_database, and mysqli_native_moodle_database.

◆ sql_substr()

moodle_database::sql_substr	(	$expr,
		$start,
		$length = `false`
	)

Returns the proper substr() SQL text used to extract substrings from DB NOTE: this was originally returning only function name.

Parameters

string	$expr	Some string field, no aggregates.
mixed	$start	Integer or expression evaluating to integer (1 based value; first char has index 1)
mixed	$length	Optional integer or expression evaluating to integer.

Return values

string The sql substring extraction fragment.

Reimplemented in sqlsrv_native_moodle_database.

◆ start_delegated_transaction()

moodle_database::start_delegated_transaction ( )

On DBs that support it, switch to transaction mode and begin a transaction you'll need to ensure you call allow_commit() on the returned object or your changes will be lost.

this is very useful for massive updates

Delegated database transactions can be nested, but only one actual database transaction is used for the outer-most delegated transaction. This method returns a transaction object which you should keep until the end of the delegated transaction. The actual database transaction will only be committed if all the nested delegated transactions commit successfully. If any part of the transaction rolls back then the whole thing is rolled back.

Return values

moodle_transaction

◆ store_settings()

moodle_database::store_settings	(		$dbhost,
			$dbuser,
			$dbpass,
			$dbname,
			$prefix,
		array	$dboptions = `null`
	)

protected

Store various database settings.

Parameters

string	$dbhost	The database host.
string	$dbuser	The database user to connect as.
string	$dbpass	The password to use when connecting to the database.
string	$dbname	The name of the database being connected to.
mixed	$prefix	string means moodle db prefix, false used for external databases where prefix not used
array	$dboptions	driver specific options

Return values

void

◆ transactions_forbidden()

moodle_database::transactions_forbidden ( )

This is a test that throws an exception if transaction in progress.

This test does not force rollback of active transactions.

Return values

void

Exceptions

dml_transaction_exception if stansaction active

◆ transactions_supported()

moodle_database::transactions_supported ( )

protected

Checks and returns true if transactions are supported.

It is not responsible to run productions servers on databases without transaction support ;-)

Override in driver if needed.

Return values

bool

Reimplemented in mysqli_native_moodle_database, and mariadb_native_moodle_database.

◆ update_record()

moodle_database::update_record	(	$table,
		$dataobject,
		$bulk = `false`
	)

abstract

Update a record in a table.

$dataobject is an object containing needed data Relies on $dataobject having a variable "id" to specify the record to update

Parameters

string	$table	The database table to be checked against.
object	$dataobject	An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
bool	$bulk	True means repeated updates expected.

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ update_record_raw()

moodle_database::update_record_raw	(	$table,
		$params,
		$bulk = `false`
	)

abstract

Update record in database, as fast as possible, no safety checks, lobs not supported.

Parameters

string	$table	name
mixed	$params	data record as object or array
bool	$bulk	True means repeated updates expected.

Return values

bool true

Exceptions

dml_exception A DML specific exception is thrown for any errors.

Reimplemented in sqlsrv_native_moodle_database, pgsql_native_moodle_database, pdo_moodle_database, oci_native_moodle_database, and mysqli_native_moodle_database.

◆ update_temp_table_stats()

moodle_database::update_temp_table_stats ( )

Analyze the data in temporary tables to force statistics collection after bulk data loads.

Return values

void

◆ where_clause()

moodle_database::where_clause	(		$table,
		array	$conditions = `null`
	)

protected

Returns the SQL WHERE conditions.

Parameters

string	$table	The table name that these conditions will be validated against.
array	$conditions	The conditions to build the where clause. (must not contain numeric indexes)

Exceptions

dml_exception

Return values

array An array list containing sql 'where' part and 'params'.

◆ where_clause_list()

moodle_database::where_clause_list	(		$field,
		array	$values
	)

protected

Returns SQL WHERE conditions for the ..._list group of methods.

Parameters

string	$field	the name of a field.
array	$values	the values field might take.

Return values

array An array containing sql 'where' part and 'params'

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

lib/dml/moodle_database.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ allowed_param_types()

◆ begin_transaction()

◆ change_database_structure()

◆ change_db_encoding()

◆ commit_delegated_transaction()

◆ commit_transaction()

◆ connect()

◆ count_records()

◆ count_records_select()

◆ count_records_sql()

◆ create_database()

◆ delete_records()

◆ delete_records_list()

◆ delete_records_select()

◆ delete_records_subquery()

◆ detect_objects()

◆ diagnose()

◆ dispose()

◆ driver_installed()

◆ execute()

◆ export_dbconfig()

◆ export_table_recordset()

◆ fix_sql_params()

◆ fix_table_name()

◆ fix_table_names()

◆ force_transaction_rollback()

◆ get_columns()

◆ get_configuration_help()

◆ get_configuration_hints()

◆ get_dbfamily()

◆ get_dblibrary()

◆ get_dbtype()

◆ get_dbvendor()

◆ get_debug()

◆ get_driver_instance()

◆ get_field()

◆ get_field_select()

◆ get_field_sql()

◆ get_fieldset_select()

◆ get_fieldset_sql()

◆ get_in_or_equal()

◆ get_indexes()

◆ get_last_error()

◆ get_manager()

◆ get_metacache()

◆ get_name()

◆ get_prefix()

◆ get_record()

◆ get_record_select()

◆ get_record_sql()

◆ get_records()

◆ get_records_list()

◆ get_records_menu()

◆ get_records_select()

◆ get_records_select_menu()

◆ get_records_sql()

◆ get_records_sql_menu()

◆ get_recordset()

◆ get_recordset_list()

◆ get_recordset_select()

◆ get_recordset_sql()

◆ get_server_info()

◆ get_session_lock()

◆ get_settings_hash()

◆ get_tables()

◆ get_temp_tables_cache()

◆ get_transaction_start_backtrace()

◆ import_record()

◆ insert_record()

◆ insert_record_raw()

◆ insert_records()

◆ is_fulltext_search_supported()