diff options
| -rw-r--r-- | system/database/DB_driver.php | 10 | ||||
| -rw-r--r-- | user_guide_src/source/database/db_driver_reference.rst | 407 | ||||
| -rw-r--r-- | user_guide_src/source/database/index.rst | 3 |
3 files changed, 414 insertions, 6 deletions
diff --git a/system/database/DB_driver.php b/system/database/DB_driver.php index 7c3df42b8..fdd99167f 100644 --- a/system/database/DB_driver.php +++ b/system/database/DB_driver.php @@ -964,7 +964,7 @@ abstract class CI_DB_driver { * Calculate the aggregate query elapsed time * * @param int The number of decimal places - * @return int + * @return string */ public function elapsed_time($decimals = 6) { @@ -1034,7 +1034,7 @@ abstract class CI_DB_driver { /** * Escape String * - * @param string $str + * @param string|string[] $str * @param bool $like Whether or not the string will be used in a LIKE condition * @return string */ @@ -1103,7 +1103,7 @@ abstract class CI_DB_driver { * position is the primary key * * @param string the table name - * @return string + * @return mixed */ public function primary($table = '') { @@ -1146,7 +1146,7 @@ abstract class CI_DB_driver { * Returns an array of table names * * @param string $constrain_by_prefix = FALSE - * @return array + * @return mixed */ public function list_tables($constrain_by_prefix = FALSE) { @@ -1214,7 +1214,7 @@ abstract class CI_DB_driver { * Fetch Field Names * * @param string the table name - * @return array + * @return mixed */ public function list_fields($table = '') { diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst new file mode 100644 index 000000000..872077a7e --- /dev/null +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -0,0 +1,407 @@ +################### +DB Driver Reference +################### + +This is the platform-independent base DB implementation class. +This class will not be called directly. Rather, the adapter +class for the specific database will extend and instantiate it. + +The how-to material for this has been split over several articles. +This article is intended to be a reference for them. + +.. class:: CI_DB_driver + + .. method:: initialize() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Initialize Database Settings; + establish a connection to the database. + + .. method:: db_pconnect() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Establish a persistent database connection + + .. method:: reconnect() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Keep / reestablish the db connection if no queries have been + sent for a length of time exceeding the server's idle timeout. + + This is only available in drivers that support it. + + .. method:: db_select() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Select database + + .. method:: db_set_charset($charset) + + :param string $charset: Character set name + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Set client character set + + .. method:: platform() + + :returns: Platform name + :rtype: string + + The name of the platform in use (mysql, mssql, etc...) + + .. method:: version() + + :returns: The version of the database being used. + :rtype: string + + Database version number + + .. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]]) + + :param string $sql: The SQL statement to execute + :param array $binds: An array of binding data + :param bool $return_object: Character set name + :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :rtype: mixed + + Execute the query + + Accepts an SQL string as input and returns a result object + upon + successful execution of a "read" type query. Returns boolean + TRUE + upon successful execution of a "write" type query. + Returns boolean + FALSE upon failure, and if the $db_debug variable is set + to TRUE + will raise an error. + + .. method:: load_rdriver() + + :returns: The DB_result object appropriate for the driver in use + :rtype: DB_result + + Load the result drivers + + .. method:: simple_query($sql) + + :param string $sql: The SQL statement to execute + :returns: True on "update" success, DB_result object on "query" success, FALSE on failure + :rtype: mixed + + Simple Query + + This is a simplified version of the query() function. Internally + we only use it when running transaction commands since they do + not require all the features of the main query() function. + + .. method:: trans_off() + + :rtype: void + + Disable Transactions. + + This permits transactions to be disabled at run-time. + + .. method:: trans_strict([$mode = TRUE]) + + :param boolean $mode: TRUE for strict mode + :rtype: void + + Enable/disable Transaction Strict Mode. + + When strict mode is enabled, if you are running multiple + groups of + transactions, if one group fails all groups will be rolled back. + If strict mode is disabled, each group is treated autonomously, + meaning + a failure of one group will not affect any others. + + .. method:: trans_start([$test_mode = FALSE[) + + :param boolean $test_mode: TRUE for testing mode + :rtype: void + + Start Transaction. + + .. method:: trans_complete() + + :rtype: void + + Complete Transaction. + + .. method:: trans_status() + + :returns: TRUE if the transaction succeeded, FALSE if it failed + :rtype: boolean + + Lets you retrieve the transaction flag to determine if it + has failed. + + .. method:: compile_binds($sql, $binds) + + :param string $sql: The SQL statement + :param array $binds: An array of binding data + :returns: The updated SQL statement + :rtype: string + + Compile Bindings + + .. method:: is_write_type($sql) + + :param string $sql: The SQL statement + :returns: TRUE if the SQL statement is a "write" type of statement + :rtype: boolean + + Determines if a query is a "write" type. + + .. method:: elapsed_time([$decimals = 6]) + + :param int $decimals: The number of decimal places + :returns: The aggregate query elapsed time, in microseconds + :rtype: string + + Calculate the aggregate query elapsed time. + + .. method:: total_queries() + + :returns: The total number of queries + :rtype: int + + Returns the total number of queries. + + .. method:: last_query() + + :returns: The last query executed + :rtype: string + + Returns the last query that was executed. + + .. method:: escape($str) + + :param string $str: The string to work with + :returns: The escaped string + :rtype: mixed + + "Smart" Escape String. + + Escapes data based on type. + Sets boolean and null types + + .. method:: escape_str($str[, $like = FALSE]) + + :param mixed $str: The string or array of strings to work with + :param boolean $like: Whether or not the string will be used in a LIKE condition + :returns: The escaped string(s) + :rtype: mixed + + Escape String. + + .. method:: escape_like_str($str) + + :param mixed $str: The string or array of strings to work with + :returns: The escaped string(s) + :rtype: mixed + + Escape LIKE String. + + Calls the individual driver for platform + specific escaping for LIKE conditions. + + .. method:: primary([$table = '']) + + :param string $table: The table name + :returns: The primary key name, FALSE if none + :rtype: mixed + + Primary. + + Retrieves the primary key. It assumes that the row in the first + position is the primary key. + + .. method:: count_all([$table = '']) + + :param string $table: The table name + :returns: Record count for specified table + :rtype: int + + "Count All" query. + + Generates a platform-specific query string that counts + all records in + the specified database. + + .. method:: list_tables([$constrain_by_prefix = FALSE]) + + :param boolean $constrain_by_prefix: TRUE to constrain the tables considered + :returns: Array of table names, FALSE if the operation is unsupported + :rtype: mixed + + Returns an array of table names. + + .. method:: table_exists($table_name) + + :param string $table_name: The table name + :returns: TRUE if that table exists + :rtype: boolean + + Determine if a particular table exists. + + .. method:: list_fields([$table = '']) + + :param string $table: The table name + :returns: Array of field names, FALSE if the table doesn't exist or the operation is un-supported + :rtype: mixed + + Fetch Field Names. + + .. method:: field_exists($field_name, $table_name) + + :param string $table_name: The table name + :param string $field_name: The field name + :returns: TRUE if that field exists in that table + :rtype: boolean + + Determine if a particular field exists. + + .. method:: field_data([$table = '']) + + :param string $table: The table name + :returns: Object with field data, FALSE if no table given + :rtype: mixed + + Returns an object with field data. + + .. method:: escape_identifiers($item) + + :param mixed $item: The item or array of items to escape + :returns: The item(s), escaped + :rtype: mixed + + Escape the SQL Identifiers. + + This function escapes column and table names + + .. method:: insert_string($table, $data) + + :param string $table: The table upon which the query will be performed + :param array $data: an associative array of data key/values + :returns: The SQL insert string + :rtype: string + + Generate an insert string. + + .. method:: update_string($table, $data, $where) + + :param string $table: The table upon which the query will be performed + :param array $data: an associative array of data key/values + :param mixed $where: the "where" statement + :returns: The SQL update string + :rtype: string + + Generate an update string. + + .. method:: call_function($function) + + :param string $function: Function name + :returns: The function result + :rtype: string + + Enables a native PHP function to be run, using a platform + agnostic wrapper. + + .. method:: cache_set_path([$path = '']) + + :param string $path: the path to the cache directory + :rtype: void + + Set Cache Directory Path. + + .. method:: cache_on() + + :returns: cache_on value + :rtype: boolean + + Enable Query Caching. + + .. method:: cache_off() + + :returns: cache_on value + :rtype: boolean + + Disable Query Caching. + + .. method:: cache_delete([$segment_one = ''[, $segment_two = '']]) + + :param string $segment_one: first URI segment + :param string $segment_two: second URI segment + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Delete the cache files associated with a particular URI + + .. method:: cache_delete_all() + + :returns: TRUE on success, FALSE on failure + :rtype: boolean + + Delete All cache files + + .. method:: close() + + :rtype: void + + Close DB Connection + + .. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]]) + + :param string $error: the error message + :param string $swap: any "swap" values + :param boolean $native: whether to localize the message + :returns: sends the application/views/errors/error_db.php template + :rtype: string + + Display an error message + + .. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]]) + + :param string $item: the item + :param boolean $prefix_single: whether to use a single prefix + :param boolean $protect_identifiers: whether to protect identifiers + :param boolean $field_exists: whether the supplied item does not contain a field name. + :returns: the modified item + :rtype: string + + Protect Identifiers. + + This function is used extensively by the Query Builder class, + and by + a couple functions in this class. + It takes a column or table name (optionally with an alias) + and inserts + the table prefix onto it. Some logic is necessary in order + to deal with + column names that include the path. Consider a query like this:: + + SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table + + Or a query with aliasing:: + + SELECT m.member_id, m.member_name FROM members AS m + + Since the column name can include up to four segments + (host, DB, table, column) + or also have an alias prefix, we need to do a bit of work + to figure this out and + insert the table prefix (if it exists) in the proper position, + and escape only + the correct identifiers.
\ No newline at end of file diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 4612daf9d..2fb50f9be 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -21,4 +21,5 @@ patterns. The database functions offer clear, simple syntax. Custom Function Calls <call_function> Query Caching <caching> Database Manipulation with Database Forge <forge> - Database Utilities Class <utilities>
\ No newline at end of file + Database Utilities Class <utilities> + Database Driver Reference <db_driver_reference>
\ No newline at end of file |