diff options
Diffstat (limited to 'user_guide_src/source/database/db_driver_reference.rst')
| -rw-r--r-- | user_guide_src/source/database/db_driver_reference.rst | 420 |
1 files changed, 420 insertions, 0 deletions
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..7bee555c8 --- /dev/null +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -0,0 +1,420 @@ +################### +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. + +.. important:: Not all methods are supported by all database drivers, + some of them may fail (and return FALSE) if the underlying + driver does not support them. + +.. class:: CI_DB_driver + + .. method:: initialize() + + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Initialize database settings, establish a connection to + the database. + + .. method:: db_connect($persistent = TRUE) + + :param bool $persistent: Whether to establish a persistent connection or a regular one + :returns: Database connection resource/object or FALSE on failure + :rtype: mixed + + Establish a connection with the database. + + .. note:: The returned value depends on the underlying + driver in use. For example, a ``mysqli`` instance + will be returned with the 'mysqli' driver. + + .. method:: db_pconnect() + + :returns: Database connection resource/object or FALSE on failure + :rtype: mixed + + Establish a persistent connection with the database. + + .. note:: This method is just an alias for ``db_connect(TRUE)``. + + .. method:: reconnect() + + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Keep / reestablish the database connection if no queries + have been sent for a length of time exceeding the + server's idle timeout. + + .. method:: db_select([$database = '']) + + :param string $database: Database name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Select / switch the current database. + + .. method:: db_set_charset($charset) + + :param string $charset: Character set name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + 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: Whether to return a result object or not + :returns: TRUE for successful "write-type" queries, CI_DB_result instance (method chaining) on "query" success, FALSE on failure + :rtype: mixed + + Execute an SQL 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" queries + - Boolean FALSE upon failure + - ``CI_DB_result`` object for "read type" queries + + .. note: If 'db_debug' setting is set to TRUE, an error + page will be displayed instead of returning FALSE + on failures and script execution will stop. + + .. method:: simple_query($sql) + + :param string $sql: The SQL statement to execute + :returns: Whatever the underlying driver's "query" function returns + :rtype: mixed + + A simplified version of the ``query()`` method, appropriate + for use when you don't need to get a result object or to + just send a query to the database and not care for the result. + + .. method:: trans_strict([$mode = TRUE]) + + :param bool $mode: Strict mode flag + :rtype: void + + Enable/disable transaction "strict" mode. + + When strict mode is enabled, if you are running multiple + groups of transactions and 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_off() + + :rtype: void + + Disables transactions at run-time. + + .. method:: trans_start([$test_mode = FALSE]) + + :param bool $test_mode: Test mode flag + :rtype: void + + Start a transaction. + + .. method:: trans_complete() + + :rtype: void + + Complete Transaction. + + .. method:: trans_status() + + :returns: TRUE if the transaction succeeded, FALSE if it failed + :rtype: bool + + Lets you retrieve the transaction status 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 + + Compiles an SQL query with the bind values passed for it. + + .. method:: is_write_type($sql) + + :param string $sql: The SQL statement + :returns: TRUE if the SQL statement is of "write type", FALSE if not + :rtype: bool + + Determines if a query is of a "write" type (such as + INSERT, UPDATE, DELETE) or "read" type (i.e. SELECT). + + .. 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 executed + :rtype: int + + Returns the total number of queries that have been + executed so far. + + .. method:: last_query() + + :returns: The last query executed + :rtype: string + + Returns the last query that was executed. + + .. method:: escape($str) + + :param mixed $str: The value to escape, or an array of multiple ones + :returns: The escaped value(s) + :rtype: mixed + + Escapes input data based on type, including boolean and + NULLs. + + .. method:: escape_str($str[, $like = FALSE]) + + :param mixed $str: A string value or array of multiple ones + :param bool $like: Whether or not the string will be used in a LIKE condition + :returns: The escaped string(s) + :rtype: mixed + + Escapes string values. + + .. warning:: The returned strings do NOT include quotes + around them. + + .. method:: escape_like_str($str) + + :param mixed $str: A string value or array of multiple ones + :returns: The escaped string(s) + :rtype: mixed + + Escape LIKE strings. + + Similar to ``escape_str()``, but will also escape the ``%`` + and ``_`` wildcard characters, so that they don't cause + false-positives in LIKE conditions. + + .. method:: primary($table) + + :param string $table: Table name + :returns: The primary key name, FALSE if none + :rtype: string + + Retrieves the primary key of a table. + + .. note:: If the database platform does not support primary + key detection, the first column name may be assumed + as the primary key. + + .. method:: count_all([$table = '']) + + :param string $table: Table name + :returns: Row count for the specified table + :rtype: int + + Returns the total number of rows in a table, or 0 if no + table was provided. + + .. method:: list_tables([$constrain_by_prefix = FALSE]) + + :param bool $constrain_by_prefix: TRUE to match table names by the configured dbprefix + :returns: Array of table names or FALSE on failure + :rtype: array + + Gets a list of the tables in the current database. + + .. method:: table_exists($table_name) + + :param string $table_name: The table name + :returns: TRUE if that table exists, FALSE if not + :rtype: bool + + Determine if a particular table exists. + + .. method:: list_fields($table) + + :param string $table: The table name + :returns: Array of field names or FALSE on failure + :rtype: array + + Gets a list of the field names in a table. + + .. 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, FALSE if not + :rtype: bool + + Determine if a particular field exists. + + .. method:: field_data($table) + + :param string $table: The table name + :returns: Array of field data items or FALSE on failure + :rtype: array + + Gets a list containing field data about a table. + + .. method:: escape_identifiers($item) + + :param mixed $item: The item or array of items to escape + :returns: The input item(s), escaped + :rtype: mixed + + Escape SQL identifiers, such as column, table and names. + + .. method:: insert_string($table, $data) + + :param string $table: The target table + :param array $data: An associative array of key/value pairs + :returns: The SQL INSERT statement, as a string + :rtype: string + + Generate an INSERT statement string. + + .. method:: update_string($table, $data, $where) + + :param string $table: The target table + :param array $data: An associative array of key/value pairs + :param mixed $where: The WHERE statement conditions + :returns: The SQL UPDATE statement, as a string + :rtype: string + + Generate an UPDATE statement string. + + .. method:: call_function($function) + + :param string $function: Function name + :returns: The function result + :rtype: string + + Runs a native PHP function , using a platform agnostic + wrapper. + + .. method:: cache_set_path([$path = '']) + + :param string $path: Path to the cache directory + :rtype: void + + Sets the directory path to use for caching storage. + + .. method:: cache_on() + + :returns: TRUE if caching is on, FALSE if not + :rtype: bool + + Enable database results caching. + + .. method:: cache_off() + + :returns: TRUE if caching is on, FALSE if not + :rtype: bool + + Disable database results 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: bool + + Delete the cache files associated with a particular URI. + + .. method:: cache_delete_all() + + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Delete all cache files. + + .. method:: close() + + :rtype: void + + Close the DB Connection. + + .. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]]) + + :param string $error: The error message + :param string $swap: Any "swap" values + :param bool $native: Whether to localize the message + :rtype: void + + :returns: Displays the DB error screensends the application/views/errors/error_db.php template + :rtype: string + + Display an error message and stop script execution. + + The message is displayed using the + *application/views/errors/error_db.php* template. + + .. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]]) + + :param string $item: The item to work with + :param bool $prefix_single: Whether to apply the dbprefix even if the input item is a single identifier + :param bool $protect_identifiers: Whether to quote identifiers + :param bool $field_exists: Whether the supplied item contains a field name or not + :returns: The modified item + :rtype: string + + Takes a column or table name (optionally with an alias) + and applies the configured *dbprefix* to 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. + + This method is used extensively by the Query Builder class.
\ No newline at end of file |