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.

重要

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()
返り値の型:void
Throws:RuntimeException In case of failure

Initialize database settings, establish a connection to the database.

db_connect($persistent = TRUE)
パラメータ:
  • $persistent (bool) – Whether to establish a persistent connection or a regular one
返り値:

Database connection resource/object or FALSE on failure
返り値の型:

mixed

Establish a connection with the database.

注釈

The returned value depends on the underlying driver in use. For example, a mysqli instance will be returned with the ‘mysqli’ driver.

db_pconnect()
返り値:Database connection resource/object or FALSE on failure
返り値の型:mixed

Establish a persistent connection with the database.

注釈

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

reconnect()
返り値:TRUE on success, FALSE on failure
返り値の型: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 = ''])
パラメータ:
  • $database (string) – Database name
返り値:

TRUE on success, FALSE on failure
返り値の型:

bool

Select / switch the current database.

platform()
返り値:Platform name
返り値の型:string

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

version()
返り値:The version of the database being used
返り値の型:string

Database version number.

query($sql[, $binds = FALSE[, $return_object = NULL]])
パラメータ:
  • $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
返り値:

TRUE for successful “write-type” queries, CI_DB_result instance (method chaining) on “query” success, FALSE on failure
返り値の型:

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)
パラメータ:
  • $sql (string) – The SQL statement to execute
返り値:

Whatever the underlying driver’s “query” function returns
返り値の型:

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()
返り値:Number of rows affected
返り値の型: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])
パラメータ:
  • $mode (bool) – Strict mode flag
返り値の型:

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()
返り値の型:void

Disables transactions at run-time.

trans_start([$test_mode = FALSE])
パラメータ:
  • $test_mode (bool) – Test mode flag
返り値:

TRUE on success, FALSE on failure
返り値の型:

bool

Start a transaction.

trans_complete()
返り値:TRUE on success, FALSE on failure
返り値の型:bool

Complete Transaction.

trans_status()
返り値:TRUE if the transaction succeeded, FALSE if it failed
返り値の型:bool

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

compile_binds($sql, $binds)
パラメータ:
  • $sql (string) – The SQL statement
  • $binds (array) – An array of binding data
返り値:

The updated SQL statement
返り値の型:

string

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

is_write_type($sql)
パラメータ:
  • $sql (string) – The SQL statement
返り値:

TRUE if the SQL statement is of “write type”, FALSE if not
返り値の型:

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])
パラメータ:
  • $decimals (int) – The number of decimal places
返り値:

The aggregate query elapsed time, in microseconds
返り値の型:

string

Calculate the aggregate query elapsed time.

total_queries()
返り値:The total number of queries executed
返り値の型:int

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

last_query()
返り値:The last query executed
返り値の型:string

Returns the last query that was executed.

escape($str)
パラメータ:
  • $str (mixed) – The value to escape, or an array of multiple ones
返り値:

The escaped value(s)
返り値の型:

mixed

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

escape_str($str[, $like = FALSE])
パラメータ:
  • $str (mixed) – A string value or array of multiple ones
  • $like (bool) – Whether or not the string will be used in a LIKE condition
返り値:

The escaped string(s)
返り値の型:

mixed

Escapes string values.

警告

The returned strings do NOT include quotes around them.

escape_like_str($str)
パラメータ:
  • $str (mixed) – A string value or array of multiple ones
返り値:

The escaped string(s)
返り値の型:

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.

重要

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)
パラメータ:
  • $table (string) – Table name
返り値:

The primary key name, FALSE if none
返り値の型:

string

Retrieves the primary key of a table.

注釈

If the database platform does not support primary key detection, the first column name may be assumed as the primary key.

count_all([$table = ''])
パラメータ:
  • $table (string) – Table name
返り値:

Row count for the specified table
返り値の型:

int

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

list_tables([$constrain_by_prefix = FALSE])
パラメータ:
  • $constrain_by_prefix (bool) – TRUE to match table names by the configured dbprefix
返り値:

Array of table names or FALSE on failure
返り値の型:

array

Gets a list of the tables in the current database.

table_exists($table_name)
パラメータ:
  • $table_name (string) – The table name
返り値:

TRUE if that table exists, FALSE if not
返り値の型:

bool

Determine if a particular table exists.

list_fields($table)
パラメータ:
  • $table (string) – The table name
返り値:

Array of field names or FALSE on failure
返り値の型:

array

Gets a list of the field names in a table.

field_exists($field_name, $table_name)
パラメータ:
  • $table_name (string) – The table name
  • $field_name (string) – The field name
返り値:

TRUE if that field exists in that table, FALSE if not
返り値の型:

bool

Determine if a particular field exists.

field_data($table)
パラメータ:
  • $table (string) – The table name
返り値:

Array of field data items or FALSE on failure
返り値の型:

array

Gets a list containing field data about a table.

escape_identifiers($item)
パラメータ:
  • $item (mixed) – The item or array of items to escape
返り値:

The input item(s), escaped
返り値の型:

mixed

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

insert_string($table, $data)
パラメータ:
  • $table (string) – The target table
  • $data (array) – An associative array of key/value pairs
返り値:

The SQL INSERT statement, as a string
返り値の型:

string

Generate an INSERT statement string.

update_string($table, $data, $where)
パラメータ:
  • $table (string) – The target table
  • $data (array) – An associative array of key/value pairs
  • $where (mixed) – The WHERE statement conditions
返り値:

The SQL UPDATE statement, as a string
返り値の型:

string

Generate an UPDATE statement string.

call_function($function)
パラメータ:
  • $function (string) – Function name
返り値:

The function result
返り値の型:

string

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

cache_set_path([$path = ''])
パラメータ:
  • $path (string) – Path to the cache directory
返り値の型:

void

Sets the directory path to use for caching storage.

cache_on()
返り値:TRUE if caching is on, FALSE if not
返り値の型:bool

Enable database results caching.

cache_off()
返り値:TRUE if caching is on, FALSE if not
返り値の型:bool

Disable database results caching.

cache_delete([$segment_one = ''[, $segment_two = '']])
パラメータ:
  • $segment_one (string) – First URI segment
  • $segment_two (string) – Second URI segment
返り値:

TRUE on success, FALSE on failure
返り値の型:

bool

Delete the cache files associated with a particular URI.

cache_delete_all()
返り値:TRUE on success, FALSE on failure
返り値の型:bool

Delete all cache files.

close()
返り値の型:void

Close the DB Connection.

display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
パラメータ:
  • $error (string) – The error message
  • $swap (string) – Any “swap” values
  • $native (bool) – Whether to localize the message
返り値の型:

void
返り値:

Displays the DB error screensends the application/views/errors/error_db.php template
返り値の型:

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]]])
パラメータ:
  • $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
返り値:

The modified item
返り値の型:

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.