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.
.. php:class:: CI_DB_driver
.. php:method:: initialize()
:returns: TRUE on success, FALSE on failure
:rtype: bool
Initialize database settings, establish a connection to
the database.
.. php: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.
.. php: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)``.
.. php: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.
.. php:method:: db_select([$database = ''])
:param string $database: Database name
:returns: TRUE on success, FALSE on failure
:rtype: bool
Select / switch the current database.
.. php:method:: db_set_charset($charset)
:param string $charset: Character set name
:returns: TRUE on success, FALSE on failure
:rtype: bool
Set client character set.
.. php:method:: platform()
:returns: Platform name
:rtype: string
The name of the platform in use (mysql, mssql, etc...).
.. php:method:: version()
:returns: The version of the database being used
:rtype: string
Database version number.
.. php: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.
.. php: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.
.. php: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.
.. php:method:: trans_off()
:rtype: void
Disables transactions at run-time.
.. php:method:: trans_start([$test_mode = FALSE])
:param bool $test_mode: Test mode flag
:rtype: void
Start a transaction.
.. php:method:: trans_complete()
:rtype: void
Complete Transaction.
.. php: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.
.. php: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.
.. php: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).
.. php: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.
.. php:method:: total_queries()
:returns: The total number of queries executed
:rtype: int
Returns the total number of queries that have been
executed so far.
.. php:method:: last_query()
:returns: The last query executed
:rtype: string
Returns the last query that was executed.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php: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.
.. php:method:: cache_set_path([$path = ''])
:param string $path: Path to the cache directory
:rtype: void
Sets the directory path to use for caching storage.
.. php:method:: cache_on()
:returns: TRUE if caching is on, FALSE if not
:rtype: bool
Enable database results caching.
.. php:method:: cache_off()
:returns: TRUE if caching is on, FALSE if not
:rtype: bool
Disable database results caching.
.. php: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.
.. php:method:: cache_delete_all()
:returns: TRUE on success, FALSE on failure
:rtype: bool
Delete all cache files.
.. php:method:: close()
:rtype: void
Close the DB Connection.
.. php: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.
.. php: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.