# 数据库驱动器参考

这是一个平台无关的数据库实现基类，该类不会被直接调用， 而是通过特定的数据库适配器类来继承和实现该类。

关于数据库驱动器，已经在其他几篇文档中介绍过，这篇文档将作为它们的一个参考。

重要

并不是所有的方法都被所有的数据库驱动器所支持， 当不支持的时候，有些方法可能会失败（返回 FALSE）。

class `CI_DB_driver`
  `initialize`()

    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    初始化数据库配置，建立对数据库的连接。

  `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

    建立对数据库的连接。

    注解

    返回值取决于当前使用的数据库驱动器，例如 `mysqli` 实例将会返回 'mysqli' 驱动器。

  `db_pconnect`()

    返回: | Database connection resource/object or FALSE on failure
    返回类型: | mixed

    建立对数据库的连接，使用持久连接。

    注解

    该方法其实就是调用 `db_connect(TRUE)` 。

  `reconnect`()

    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    如果超过服务器的超时时间都没有发送任何查询请求， 使用该方法可以让数据库连接保持有效，或重新连接数据库。

  `db_select`([$database = ''])

    参数: | $database (string) -- Database name
    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    切换到某个数据库。

  `db_set_charset`($charset)

    参数: | $charset (string) -- Character set name
    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    设置客户端字符集。

  `platform`()

    返回: | Platform name
    返回类型: | string

    当前使用的数据库平台（mysql、mssql 等）。

  `version`()

    返回: | The version of the database being used
    返回类型: | string

    数据库版本。

  `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

    执行一个 SQL 查询。

    如果是读类型的查询，执行 SQL 成功后将返回结果对象。

    有以下几种可能的返回值：

    > - 如果是写类型的查询，执行成功返回 TRUE
    > - 执行失败返回 FALSE
    > - 如果是读类型的查询，执行成功返回 `CI_DB_result` 对象

  `simple_query`($sql)

    参数: | $sql (string) -- The SQL statement to execute
    返回: | Whatever the underlying driver's "query" function returns
    返回类型: | mixed

    `query()` 方法的简化版，当你只需要简单的执行一个查询，并不关心查询的结果时， 可以使用该方法。

  `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

    启用或禁用事务的严格模式。

    在严格模式下，如果你正在运行多组事务，只要有一组失败，所有组都会被回滚。

    如果禁用严格模式，那么每一组都被视为独立的组，这意味着其中一组失败不会影响其他的组。

  `trans_off`()

    返回类型: | void

    实时的禁用事务。

  `trans_start`([$test_mode = FALSE])

    参数: | $test_mode (bool) -- Test mode flag
    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    开启一个事务。

  `trans_complete`()

    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    结束事务。

  `trans_status`()

    返回: | TRUE if the transaction succeeded, FALSE if it failed
    返回类型: | bool

    获取事务的状态，用来判断事务是否执行成功。

  `compile_binds`($sql, $binds)

    参数: | $sql (string) -- The SQL statement $binds (array) -- An array of binding data
    返回: | The updated SQL statement
    返回类型: | string

    根据绑定的参数值编译 SQL 查询。

  `is_write_type`($sql)

    参数: | $sql (string) -- The SQL statement
    返回: | TRUE if the SQL statement is of "write type", FALSE if not
    返回类型: | bool

    判断查询是写类型（INSERT、UPDATE、DELETE），还是读类型（SELECT）。

  `elapsed_time`([$decimals = 6])

    参数: | $decimals (int) -- The number of decimal places
    返回: | The aggregate query elapsed time, in microseconds
    返回类型: | string

    计算查询所消耗的时间。

  `total_queries`()

    返回: | The total number of queries executed
    返回类型: | int

    返回当前已经执行了多少次查询。

  `last_query`()

    返回: | The last query executed
    返回类型: | string

    返回上一次执行的查询。

  `escape`($str)

    参数: | $str (mixed) -- The value to escape, or an array of multiple ones
    返回: | The escaped value(s)
    返回类型: | mixed

    根据输入数据的类型进行数据转义，包括布尔值和空值。

  `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

    转义字符串。

    警告

    返回的字符串没有用引号引起来。

  `escape_like_str`($str)

    参数: | $str (mixed) -- A string value or array of multiple ones
    返回: | The escaped string(s)
    返回类型: | mixed

    转义 LIKE 字符串。

    和 `escape_str()` 方法类似，但同时也对 LIKE 语句中的 `%` 和 `_` 通配符进行转义。

    重要

    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

    获取一个表的主键。

    注解

    如果数据库不支持主键检测，将假设第一列就是主键。

  `count_all`([$table = ''])

    参数: | $table (string) -- Table name
    返回: | Row count for the specified table
    返回类型: | int

    返回表中的总记录数。

  `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

    返回当前数据库的所有表。

  `table_exists`($table_name)

    参数: | $table_name (string) -- The table name
    返回: | TRUE if that table exists, FALSE if not
    返回类型: | bool

    判断某个数据库表是否存在。

  `list_fields`($table)

    参数: | $table (string) -- The table name
    返回: | Array of field names or FALSE on failure
    返回类型: | array

    返回某个表的所有字段名。

  `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

    判断某个字段是否存在。

  `field_data`($table)

    参数: | $table (string) -- The table name
    返回: | Array of field data items or FALSE on failure
    返回类型: | array

    获取某个表的所有字段信息。

  `escape_identifiers`($item)

    参数: | $item (mixed) -- The item or array of items to escape
    返回: | The input item(s), escaped
    返回类型: | mixed

    对 SQL 标识符进行转义，例如列名、表名、关键字。

  `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

    生成 INSERT 语句。

  `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

    生成 UPDATE 语句。

  `call_function`($function)

    参数: | $function (string) -- Function name
    返回: | The function result
    返回类型: | string

    使用一种平台无关的方式执行一个原生的 PHP 函数。

  `cache_set_path`([$path = ''])

    参数: | $path (string) -- Path to the cache directory
    返回类型: | void

    设置缓存路径。

  `cache_on`()

    返回: | TRUE if caching is on, FALSE if not
    返回类型: | bool

    启用数据库结果缓存。

  `cache_off`()

    返回: | TRUE if caching is on, FALSE if not
    返回类型: | bool

    禁用数据库结果缓存。

  `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

    删除特定 URI 的缓存文件。

  `cache_delete_all`()

    返回: | TRUE on success, FALSE on failure
    返回类型: | bool

    删除所有缓存文件。

  `close`()

    返回类型: | void

    关闭数据库的连接。

  `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

    显示一个错误信息，并终止脚本执行。

    错误信息是使用 application/views/errors/error_db.php 文件中的模板来显示。

  `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

    根据配置的 dbprefix 参数，给列名或表名（可能是表别名）添加一个前缀。

    为了处理包含路径的列名，必须要考虑一些逻辑。

    例如下面的查询:

        SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table

    或者下面这个查询，使用了表别名:

        SELECT m.member_id, m.member_name FROM members AS m

    由于列名可以包含四段（主机、数据库名、表名、字段名）或者有一个表别名的前缀， 我们需要做点工作来判断这一点，才能将 dbprefix 插入到正确的位置。

    该方法在查询构造器类中被广泛使用。