包 core

包 mvc

包 orm

包 form

包 database

包 helper

包 cache

包 webcontrols

包 behavior

包 exception

包 debug

类 - QDB_Adapter_Abstract

包 database
类层次 class QDB_Adapter_Abstract
版本 $Id: abstract.php 2631 2009-07-18 06:02:33Z dualface $

QDB_Adapter_Abstract 是所有数据库驱动的抽象基础类

保护的属性

隐藏继承的属性

属性类型描述定义于
$_dsn mixed 数据库连接信息 QDB_Adapter_Abstract
$_id string 数据库访问对象 ID QDB_Adapter_Abstract
$_schema string 默认的 schema QDB_Adapter_Abstract
$_fetch_mode const 指示返回结果集的形式 QDB_Adapter_Abstract
$_conn resource 数据库连接句柄 QDB_Adapter_Abstract
$_log_enabled boolean 是否将查询语句保存到日志 QDB_Adapter_Abstract
$_last_err mixed 最后一次数据库操作的错误信息 QDB_Adapter_Abstract
$_last_err_code mixed 最后一次数据库操作的错误代码 QDB_Adapter_Abstract
$_insert_id mixed 最近一次插入操作或者 nextID() 操作返回的插入 ID QDB_Adapter_Abstract
$_trans_count int 指示事务启动次数 QDB_Adapter_Abstract
$_has_failed_query boolean 指示事务执行期间是否发生了错误 QDB_Adapter_Abstract
$_savepoints_stack array SAVEPOINT 堆栈 QDB_Adapter_Abstract
$_true_value 用于描绘 true、false 和 null 的数据库值 QDB_Adapter_Abstract
$_false_value QDB_Adapter_Abstract
$_null_value QDB_Adapter_Abstract
$_timestamp_format 数据库接受的日期格式 QDB_Adapter_Abstract
$_bind_enabled boolean 指示驱动是否支持原生的参数绑定 QDB_Adapter_Abstract
$_param_style string 指示使用何种样式的参数占位符 QDB_Adapter_Abstract
$_has_insert_id boolean 指示数据库是否有自增字段功能 QDB_Adapter_Abstract
$_affected_rows_enabled boolean 指示数据库是否能获得更新、删除操作影响的记录行数量 QDB_Adapter_Abstract
$_transaction_enabled boolean 指示数据库是否支持事务 QDB_Adapter_Abstract
$_savepoint_enabled boolean 指示数据库是否支持事务中的 SAVEPOINT 功能 QDB_Adapter_Abstract
$_result_field_name_lower boolean 指示是否将查询结果中的字段名转换为全小写 QDB_Adapter_Abstract

公共方法

隐藏继承的方法

方法描述定义于
getDSN() 返回数据库访问对象使用的 DSN QDB_Adapter_Abstract
getID() 返回数据库访问对象的 ID QDB_Adapter_Abstract
getSchema() 返回数据库对象对应的 schema QDB_Adapter_Abstract
getTablePrefix() 返回数据库对象对应的表前缀 QDB_Adapter_Abstract
connect() 连接数据库，失败时抛出异常 QDB_Adapter_Abstract
pconnect() 创建一个持久连接，失败时抛出异常 QDB_Adapter_Abstract
nconnect() 强制创建一个新连接，失败时抛出异常 QDB_Adapter_Abstract
close() 关闭数据库连接 QDB_Adapter_Abstract
isConnected() 确认是否已经连接到数据库 QDB_Adapter_Abstract
handle() 返回连接数据库的句柄 QDB_Adapter_Abstract
setSchema() 选择要操作的 SCHEMA QDB_Adapter_Abstract
qstr() 转义值 QDB_Adapter_Abstract
qsql() 将 SQL 中用“[]”指示的字段名转义为完全限定名 QDB_Adapter_Abstract
qid() 获得完全限定名 QDB_Adapter_Abstract
qids() 获得多个完全限定名 QDB_Adapter_Abstract
identifier() 获得一个名字的规范名 QDB_Adapter_Abstract
qinto() 将 SQL 语句中的参数占位符替换为相应的参数值 QDB_Adapter_Abstract
insert() 插入一条记录到数据库 QDB_Adapter_Abstract
update() 更新数据库中的记录 QDB_Adapter_Abstract
delete() 删除指定数据表中符合条件的记录 QDB_Adapter_Abstract
getPlaceholder() 返回输入数组键名及其对应的参数占位符和转义后的字段名 QDB_Adapter_Abstract
nextID() 为数据表产生下一个序列值，失败时抛出异常 QDB_Adapter_Abstract
createSeq() 创建一个新的序列，失败时抛出异常 QDB_Adapter_Abstract
dropSeq() 删除一个序列，失败时抛出异常 QDB_Adapter_Abstract
insertID() 获取自增字段的最后一个值或者 nextID() 方法产生的最后一个值 QDB_Adapter_Abstract
affectedRows() 返回最近一次数据库操作受到影响的记录数 QDB_Adapter_Abstract
execute() 执行一个查询，返回一个查询对象或者 boolean 值，出错时抛出异常 QDB_Adapter_Abstract
select() 发起一个查询，获得一个 QDB_Select 查询对象 QDB_Adapter_Abstract
selectLimit() QDB_Adapter_Abstract
getAll() 执行一个查询并返回记录集，失败时抛出异常 QDB_Adapter_Abstract
getRow() 执行查询，返回第一条记录 QDB_Adapter_Abstract
getOne() 执行查询，返回第一条记录的第一个字段 QDB_Adapter_Abstract
getCol() 执行查询，返回结果集的指定列 QDB_Adapter_Abstract
dbTimestamp() 将 unix timestamp 转换为数据库可以接受的日期格式 QDB_Adapter_Abstract
startTrans() 开始一个事务 QDB_Adapter_Abstract
completeTrans() 完成事务，根据事务期间的查询是否出错决定是提交还是回滚事务 QDB_Adapter_Abstract
setTransFailed() 指示在调用 completeTrans() 时回滚事务 QDB_Adapter_Abstract
hasFailedQuery() 检查事务过程中是否出现失败的查询 QDB_Adapter_Abstract
metaColumns() 返回指定数据表（或者视图）的元数据 QDB_Adapter_Abstract
metaTables() 获得所有数据表的名称 QDB_Adapter_Abstract
bindEnabled() 确定驱动是否支持参数绑定 QDB_Adapter_Abstract
logEnabled() 确定是否把查询语句保存到日志 QDB_Adapter_Abstract
paramStyle() 返回驱动使用的参数占位符样式 QDB_Adapter_Abstract
parseSQL() 分析 SQL 中的字段名、查询条件，返回符合规范的 SQL 语句 QDB_Adapter_Abstract
parseSQLInternal() 分析 SQL 中的字段名、查询条件，返回符合规范的 SQL 语句（内部调用版本） QDB_Adapter_Abstract

保护的方法

隐藏继承的方法

方法描述定义于
__construct() 构造函数 QDB_Adapter_Abstract
_parseSQLArray() 按照模式 2（数组）对查询条件进行分析 QDB_Adapter_Abstract
_parseSQLString() 按照模式 1（字符串）对查询条件进行分析 QDB_Adapter_Abstract
_clear() 关闭数据库连接后清理资源 QDB_Adapter_Abstract

属性详细说明

$_dsn 属性

数据库连接信息

$_id 属性

数据库访问对象 ID

$_schema 属性

默认的 schema

$_fetch_mode 属性

指示返回结果集的形式

$_conn 属性

数据库连接句柄

$_log_enabled 属性

是否将查询语句保存到日志

$_last_err 属性

最后一次数据库操作的错误信息

$_last_err_code 属性

最后一次数据库操作的错误代码

$_insert_id 属性

最近一次插入操作或者 nextID() 操作返回的插入 ID

$_trans_count 属性

指示事务启动次数

$_has_failed_query 属性

指示事务执行期间是否发生了错误

$_savepoints_stack 属性

SAVEPOINT 堆栈

$_true_value 属性

用于描绘 true、false 和 null 的数据库值

$_false_value 属性
$_null_value 属性
$_timestamp_format 属性

数据库接受的日期格式

$_bind_enabled 属性

指示驱动是否支持原生的参数绑定

$_param_style 属性

指示使用何种样式的参数占位符

$_has_insert_id 属性

指示数据库是否有自增字段功能

$_affected_rows_enabled 属性

指示数据库是否能获得更新、删除操作影响的记录行数量

$_transaction_enabled 属性

指示数据库是否支持事务

$_savepoint_enabled 属性

指示数据库是否支持事务中的 SAVEPOINT 功能

$_result_field_name_lower 属性

指示是否将查询结果中的字段名转换为全小写

方法详细说明

__construct() 方法

protected void __construct($dsn, $id)

$dsn mixed
$id string
{return}

构造函数

getDSN() 方法

public mixed getDSN()

返回数据库访问对象使用的 DSN

getID() 方法

public string getID()

返回数据库访问对象的 ID

getSchema() 方法

public string getSchema()

返回数据库对象对应的 schema

getTablePrefix() 方法

public string getTablePrefix()

返回数据库对象对应的表前缀

connect() 方法

abstract public void connect()

连接数据库，失败时抛出异常

如果已经连接到了数据库，再次连接不会造成任何影响。

pconnect() 方法

abstract public void pconnect()

创建一个持久连接，失败时抛出异常

如果已经连接到了数据库，再次连接不会造成任何影响。

nconnect() 方法

abstract public void nconnect()

强制创建一个新连接，失败时抛出异常

如果已经连接到了数据库，再次连接不会造成任何影响。

close() 方法

abstract public void close()

关闭数据库连接

isConnected() 方法

public boolean isConnected()

确认是否已经连接到数据库

handle() 方法

public resource handle()

返回连接数据库的句柄

setSchema() 方法

public boolean setSchema($schema)

$schema string
{return} boolean

选择要操作的 SCHEMA

qstr() 方法

abstract public string qstr($value)

$value mixed
{return} string

转义值

为了能够在 SQL 语句中安全的插入数据，应该用 qstr() 方法将数据中的特殊字符转义。

example:

$param = "It's live";
$param = $dbo->qstr($param);
$sql = "INSERT INTO posts (title) VALUES ({$param})";
$dbo->execute($sql);

但更有效，而且更简单的方式是使用参数占位符：

example:

$param = "It's live";
$sql = "INSERT INTO posts (title) VALUES (?)";
$dbo->execute($sql, array($param));

而且对于 Oracle 等数据库，由于限制每条 SQL 语句不能超过 4000 字节， 因此在插入包含大量数据的记录时，必须使用参数占位符的形式。

example:

$title = isset($POST['title']) ? $POST['title'] : null;
$body = isset($POST['body']) ? $POST['body'] : null;
 
... 检查 $title、$body 是否为空 ...
 
$sql = "INSERT INTO posts (title, body) VALUES (:title, :body)";
$dbo->execute($sql, array('title' => $title, 'body' => $body));

qsql() 方法

public string qsql($sql, $table_name, $mapping, $callback)

$sql string 要处理的 SQL 字符串
$table_name string 转义字段名时，使用什么数据表名称
$mapping array 字段名映射，用于将字段名转换为映射名
$callback callback 如果提取到数据表名称，则调用回调函数进行转换
{return} string 转义后的 SQL 字符串

将 SQL 中用“[]”指示的字段名转义为完全限定名

qid() 方法

public string qid($name, $alias, $as)

$name string
$alias string
$as string
{return} string

获得完全限定名

qids() 方法

public array qids($names, $as)

$names array|string
$as string
{return} array

获得多个完全限定名

identifier() 方法

abstract public string identifier($name)

$name string
{return} string

获得一个名字的规范名

qinto() 方法

public string|array qinto($sql, $params, $param_style, $return_parameters_count)

$sql string 要处理的 SQL 字符串
$params array 占位符对应的参数值
$param_style enum 占位符样式
$return_parameters_count boolean 是否返回占位符个数
{return} string|array

将 SQL 语句中的参数占位符替换为相应的参数值

insert() 方法

public void insert($table_name, $row, $restricted_fields)

$table_name string 要操作的数据表
$row array 要插入的记录数据
$restricted_fields string|array 限定只使用哪些字段
{return}

插入一条记录到数据库

update() 方法

public void update($table_name, $row, $where, $restricted_fields)

$table_name string 要操作的数据表
$row array|QDB_Expr 要更新的数据
$where
$restricted_fields
{return}

更新数据库中的记录

delete() 方法

public void delete($table_name, $where)

$table_name
$where
{return}

删除指定数据表中符合条件的记录

getPlaceholder() 方法

public array getPlaceholder($inputarr, $restricted_fields, $param_style)

$inputarr array
$restricted_fields array
$param_style
{return} array

返回输入数组键名及其对应的参数占位符和转义后的字段名

nextID() 方法

abstract public int nextID($table_name, $field_name, $start_value)

$table_name string
$field_name string
$start_value string
{return} int

为数据表产生下一个序列值，失败时抛出异常

调用 nextID() 方法，将获得指定名称序列的下一个值。 此处所指的序列，是指一个不断增大的数字。

假设本次调用 nextID() 返回 3，那么下一次调用 nextID() 就会返回一个比 3 更大的值。 nextID() 返回的序列值，可以作为记录的主键字段值，以便确保插入记录时总是使用不同的主键值。

可以使用多个序列，只需要指定不同的 $seq_name 参数即可。

在不同的数据库中，序列的产生方式各有不同。 PostgreSQL、Oracle 等数据库中，会使用数据库自带的序列功能来实现。 其他部分数据库会创建一个后缀为 _seq 表来存放序列值。

例如 $seq_name 为 posts，则存放该序列的表名称为 posts_seq。

createSeq() 方法

abstract public void createSeq($seq_name, $start_value)

$seq_name string
$start_value int
{return}

创建一个新的序列，失败时抛出异常

调用 nextID() 时，如果指定的序列不存在，则会自动调用 create_seq() 创建。 开发者也可以自行调用 create_seq() 创建一个新序列。

dropSeq() 方法

abstract public void dropSeq($seq_name)

$seq_name string
{return}

删除一个序列，失败时抛出异常

insertID() 方法

abstract public int insertID()

获取自增字段的最后一个值或者 nextID() 方法产生的最后一个值

某些数据库（例如 MySQL）可以将一个字段设置为自增。 也就是每次往数据表插入一条记录，该字段的都会自动填充一个更大的新值。

insertID() 方法可以获得最后一次插入记录时产生的自增字段值，或者最后一次调用 nextID() 返回的值。

如果在一次操作中，插入了多条记录，那么 insertID() 有可能返回的是第一条记录的自增值。 这个问题是由数据库本身的实现决定的。

affectedRows() 方法

abstract public int affectedRows()

返回最近一次数据库操作受到影响的记录数

这些操作通常是插入记录、更新记录以及删除记录。 不同的数据库对于其他操作，也可能影响到 affectedRows() 返回的值。

execute() 方法

abstract public QDB_Result_Abstract execute($sql, $inputarr)

$sql string
$inputarr array
{return} QDB_Result_Abstract

执行一个查询，返回一个查询对象或者 boolean 值，出错时抛出异常

$sql 是要执行的 SQL 语句字符串，而 $inputarr 则是提供给 SQL 语句中参数占位符需要的值。

如果执行的查询是诸如 INSERT、DELETE、UPDATE 等不会返回结果集的操作， 则 execute() 执行成功后会返回 true，失败时将抛出异常。

如果执行的查询是 SELECT 等会返回结果集的操作， 则 execute() 执行成功后会返回一个 DBO_Result 对象，失败时将抛出异常。

QDB_Result_Abstract 对象封装了查询结果句柄，而不是结果集。 因此要获得查询的数据，需要调用 QDB_Result_Abstract 的 fetchAll() 等方法。

如果希望执行 SQL 后直接获得结果集，可以使用驱动的 getAll()、getRow() 等方法。

example:

$sql = "INSERT INTO posts (title, body) VALUES (?, ?)";
$dbo->execute($sql, array($title, $body));

example:

$sql = "SELECT * FROM posts WHERE post_id < 12";
$handle = $dbo->execute($sql);
$rowset = $handle->fetchAll();
$handle->free();

select() 方法

public QDB_Select select()

发起一个查询，获得一个 QDB_Select 查询对象

selectLimit() 方法

abstract public void selectLimit($sql, $offset, $length, $inputarr)

$sql
$offset
$length
$inputarr
{return}

getAll() 方法

public array getAll($sql, $inputarr)

$sql string
$inputarr array
{return} array

执行一个查询并返回记录集，失败时抛出异常

getAll() 等同于执行下面的代码：

$rowset = $dbo->execute($sql, $inputarr)->fetchAll();

getRow() 方法

public mixed getRow($sql, $inputarr)

$sql string
$inputarr array
{return} mixed

执行查询，返回第一条记录

getOne() 方法

public mixed getOne($sql, $inputarr)

$sql string
$inputarr array
{return} mixed

执行查询，返回第一条记录的第一个字段

getCol() 方法

public mixed getCol($sql, $col, $inputarr)

$sql string|resource
$col int 要返回的列，0 为第一列
$inputarr array
{return} mixed

执行查询，返回结果集的指定列

dbTimestamp() 方法

public string dbTimestamp($timestamp)

$timestamp int
{return} string

将 unix timestamp 转换为数据库可以接受的日期格式

example:

// 假设 created 是 DATETIME 类型的字段
$sql = "INSERT INTO posts (title, body, created) VALUES (?, ?, ?)";
$created = $dbo->dbTimestamp(time());
$dbo->execute($sql, array($title, $body, $created));

startTrans() 方法

abstract public void startTrans()

开始一个事务

调用 startTrans() 开始一个事务后，应该在关闭数据库连接前调用 completeTrans() 提交或回滚事务。

completeTrans() 方法

abstract public void completeTrans($commit_on_no_errors)

$commit_on_no_errors boolean
{return}

完成事务，根据事务期间的查询是否出错决定是提交还是回滚事务

如果 $commit_on_no_errors 参数为 true，当事务期间所有查询都成功完成时，则提交事务，否则回滚事务； 如果 $commit_on_no_errors 参数为 false，则强制回滚事务。

setTransFailed() 方法

public void setTransFailed()

指示在调用 completeTrans() 时回滚事务

hasFailedQuery() 方法

public void hasFailedQuery()

检查事务过程中是否出现失败的查询

metaColumns() 方法

abstract public array metaColumns($table_name)

$table_name string
{return} array

返回指定数据表（或者视图）的元数据

返回的结果是一个二维数组，每一项为一个字段的元数据。 每个字段包含下列属性：

  • name: 字段名
  • scale: 小数位数
  • type: 字段类型
  • ptype: 简单字段类型（与数据库无关）
  • length: 最大长度
  • not_null: 是否不允许保存 NULL 值
  • pk: 是否是主键
  • auto_incr: 是否是自动增量字段
  • binary: 是否是二进制数据
  • unsigned: 是否是无符号数值
  • has_default: 是否有默认值
  • default: 默认值
  • desc: 字段描述

ptype 是下列值之一：

  • c char/varchar 等类型
  • x text 等类型
  • b 二进制数据
  • n 数值或者浮点数
  • d 日期
  • t TimeStamp
  • l 逻辑布尔值
  • i 整数
  • r 自动增量
  • p 非自增的主键字段

metaTables() 方法

abstract public array metaTables($pattern, $schema)

$pattern string
$schema string
{return} array

获得所有数据表的名称

bindEnabled() 方法

public boolean bindEnabled($enabled)

$enabled boolean
{return} boolean

确定驱动是否支持参数绑定

logEnabled() 方法

public boolean logEnabled($enabled)

$enabled boolean
{return} boolean

确定是否把查询语句保存到日志

paramStyle() 方法

public string paramStyle()

返回驱动使用的参数占位符样式

parseSQL() 方法

public string parseSQL($table_name)

$table_name string
{return} string

分析 SQL 中的字段名、查询条件，返回符合规范的 SQL 语句

parseSQLInternal() 方法

public array parseSQLInternal($table_name, $args)

$table_name string
$args array
{return} array

分析 SQL 中的字段名、查询条件，返回符合规范的 SQL 语句（内部调用版本）

与 parseSQL() 的区别在于 parseSQLInternal() 用第三参数来传递所有的占位符参数及参数值。 并且 parseSQLInternal() 的返回结果是一个数组， 分别由处理后的 SQL 语句、从 SQL 语句中分析出来的数据表名称、分析用到的参数个数组成。

list($sql, $used_tables, $args_count) = parseSQLInternal(...);

_parseSQLArray() 方法

protected array _parseSQLArray($table_name, $arr, $args)

$table_name string
$arr array
$args array
{return} array

按照模式 2（数组）对查询条件进行分析

_parseSQLString() 方法

protected array _parseSQLString($table_name, $where, $args)

$table_name string
$where string
$args array
{return} array

按照模式 1（字符串）对查询条件进行分析

_clear() 方法

protected void _clear()

关闭数据库连接后清理资源