+ +
+

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.

+
+ +
+ +
+ + +