# 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
  initialize()
    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Initialize database settings, establish a connection to the database.

  db_connect($persistent = TRUE)
    Parameters:

      - $persistent (`bool`) – Whether to establish a persistent connection or a regular one

    Returns:

      Database connection resource/object or FALSE on failure

    Return type:

      `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.

  db_pconnect()
    Returns:

      Database connection resource/object or FALSE on failure

    Return type:

      `mixed`

    Establish a persistent connection with the database.

    Note

    This method is just an alias for `db_connect(TRUE)`.

  reconnect()
    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Keep / reestablish the database connection if no queries have been sent for a length of time exceeding the server’s idle timeout.

  db_select([$database = ''])
    Parameters:

      - $database (`string`) – Database name

    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Select / switch the current database.

  db_set_charset($charset)
    Parameters:

      - $charset (`string`) – Character set name

    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Set client character set.

  platform()
    Returns:

      Platform name

    Return type:

      `string`

    The name of the platform in use (mysql, mssql, etc…).

  version()
    Returns:

      The version of the database being used

    Return type:

      `string`

    Database version number.

  query($sql[, $binds = FALSE[, $return_object = NULL]])
    Parameters:

      - $sql (`string`) – The SQL statement to execute

      - $binds (`array`) – An array of binding data

      - $return_object (`bool`) – 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

    Return type:

      `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

  simple_query($sql)
    Parameters:

      - $sql (`string`) – The SQL statement to execute

    Returns:

      Whatever the underlying driver’s “query” function returns

    Return type:

      `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.

  affected_rows()
    Returns:

      Number of rows affected

    Return type:

      `int`

    Returns the number of rows changed by the last executed query.

    Useful for checking how much rows were created, updated or deleted during the last executed query.

  trans_strict([$mode = TRUE])
    Parameters:

      - $mode (`bool`) – Strict mode flag

    Return type:

      `void`

    Enable/disable transaction “strict” mode.

    When strict mode is enabled, if you are running multiple groups of transactions and one group fails, all subsequent 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.

  trans_off()
    Return type:

      `void`

    Disables transactions at run-time.

  trans_start([$test_mode = FALSE])
    Parameters:

      - $test_mode (`bool`) – Test mode flag

    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Start a transaction.

  trans_complete()
    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Complete Transaction.

  trans_status()
    Returns:

      TRUE if the transaction succeeded, FALSE if it failed

    Return type:

      `bool`

    Lets you retrieve the transaction status flag to determine if it has failed.

  trans_active()
    Returns:

      TRUE if a transaction is active, FALSE if not

    Return type:

      `bool`

    Determines if a transaction is currently active.

  compile_binds($sql, $binds)
    Parameters:

      - $sql (`string`) – The SQL statement

      - $binds (`array`) – An array of binding data

    Returns:

      The updated SQL statement

    Return type:

      `string`

    Compiles an SQL query with the bind values passed for it.

  is_write_type($sql)
    Parameters:

      - $sql (`string`) – The SQL statement

    Returns:

      TRUE if the SQL statement is of “write type”, FALSE if not

    Return type:

      `bool`

    Determines if a query is of a “write” type (such as INSERT, UPDATE, DELETE) or “read” type (i.e. SELECT).

  elapsed_time([$decimals = 6])
    Parameters:

      - $decimals (`int`) – The number of decimal places

    Returns:

      The aggregate query elapsed time, in microseconds

    Return type:

      `string`

    Calculate the aggregate query elapsed time.

  total_queries()
    Returns:

      The total number of queries executed

    Return type:

      `int`

    Returns the total number of queries that have been executed so far.

  last_query()
    Returns:

      The last query executed

    Return type:

      `string`

    Returns the last query that was executed.

  escape($str)
    Parameters:

      - $str (`mixed`) – The value to escape, or an array of multiple ones

    Returns:

      The escaped value(s)

    Return type:

      `mixed`

    Escapes input data based on type, including boolean and NULLs.

  escape_str($str[, $like = FALSE])
    Parameters:

      - $str (`mixed`) – A string value or array of multiple ones

      - $like (`bool`) – Whether or not the string will be used in a LIKE condition

    Returns:

      The escaped string(s)

    Return type:

      `mixed`

    Escapes string values.

    Warning

    The returned strings do NOT include quotes around them.

  escape_like_str($str)
    Parameters:

      - $str (`mixed`) – A string value or array of multiple ones

    Returns:

      The escaped string(s)

    Return type:

      `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.

    Important

    The `escape_like_str()` method uses ‘!’ (exclamation mark) to escape special characters for LIKE conditions. Because this method escapes partial strings that you would wrap in quotes yourself, it cannot automatically add the `ESCAPE '!'` condition for you, and so you’ll have to manually do that.

  primary($table)
    Parameters:

      - $table (`string`) – Table name

    Returns:

      The primary key name, FALSE if none

    Return type:

      `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.

  count_all([$table = ''])
    Parameters:

      - $table (`string`) – Table name

    Returns:

      Row count for the specified table

    Return type:

      `int`

    Returns the total number of rows in a table, or 0 if no table was provided.

  list_tables([$constrain_by_prefix = FALSE])
    Parameters:

      - $constrain_by_prefix (`bool`) – TRUE to match table names by the configured dbprefix

    Returns:

      Array of table names or FALSE on failure

    Return type:

      `array`

    Gets a list of the tables in the current database.

  table_exists($table_name)
    Parameters:

      - $table_name (`string`) – The table name

    Returns:

      TRUE if that table exists, FALSE if not

    Return type:

      `bool`

    Determine if a particular table exists.

  list_fields($table)
    Parameters:

      - $table (`string`) – The table name

    Returns:

      Array of field names or FALSE on failure

    Return type:

      `array`

    Gets a list of the field names in a table.

  field_exists($field_name, $table_name)
    Parameters:

      - $table_name (`string`) – The table name

      - $field_name (`string`) – The field name

    Returns:

      TRUE if that field exists in that table, FALSE if not

    Return type:

      `bool`

    Determine if a particular field exists.

  field_data($table)
    Parameters:

      - $table (`string`) – The table name

    Returns:

      Array of field data items or FALSE on failure

    Return type:

      `array`

    Gets a list containing field data about a table.

  escape_identifiers($item)
    Parameters:

      - $item (`mixed`) – The item or array of items to escape

    Returns:

      The input item(s), escaped

    Return type:

      `mixed`

    Escape SQL identifiers, such as column, table and names.

  insert_string($table, $data)
    Parameters:

      - $table (`string`) – The target table

      - $data (`array`) – An associative array of key/value pairs

    Returns:

      The SQL INSERT statement, as a string

    Return type:

      `string`

    Generate an INSERT statement string.

  update_string($table, $data, $where)
    Parameters:

      - $table (`string`) – The target table

      - $data (`array`) – An associative array of key/value pairs

      - $where (`mixed`) – The WHERE statement conditions

    Returns:

      The SQL UPDATE statement, as a string

    Return type:

      `string`

    Generate an UPDATE statement string.

  call_function($function)
    Parameters:

      - $function (`string`) – Function name

    Returns:

      The function result

    Return type:

      `string`

    Runs a native PHP function , using a platform agnostic wrapper.

  cache_set_path([$path = ''])
    Parameters:

      - $path (`string`) – Path to the cache directory

    Return type:

      `void`

    Sets the directory path to use for caching storage.

  cache_on()
    Returns:

      TRUE if caching is on, FALSE if not

    Return type:

      `bool`

    Enable database results caching.

  cache_off()
    Returns:

      TRUE if caching is on, FALSE if not

    Return type:

      `bool`

    Disable database results caching.

  cache_delete([$segment_one = ''[, $segment_two = '']])
    Parameters:

      - $segment_one (`string`) – First URI segment

      - $segment_two (`string`) – Second URI segment

    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Delete the cache files associated with a particular URI.

  cache_delete_all()
    Returns:

      TRUE on success, FALSE on failure

    Return type:

      `bool`

    Delete all cache files.

  close()
    Return type:

      `void`

    Close the DB Connection.

  display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
    Parameters:

      - $error (`string`) – The error message

      - $swap (`string`) – Any “swap” values

      - $native (`bool`) – Whether to localize the message

    Return type:

      `void`

    Returns:

      Displays the DB error screensends the application/views/errors/error_db.php template

    Return type:

      `string`

    Display an error message and stop script execution.

    The message is displayed using the application/views/errors/error_db.php template.

  protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]])
    Parameters:

      - $item (`string`) – The item to work with

      - $prefix_single (`bool`) – Whether to apply the dbprefix even if the input item is a single identifier

      - $protect_identifiers (`bool`) – Whether to quote identifiers

      - $field_exists (`bool`) – Whether the supplied item contains a field name or not

    Returns:

      The modified item

    Return type:

      `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.