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.
