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

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