PHP 手册
上一页 |  | 下一页

# C. MySQLi 扩展库

# 简介

mysqli 扩展允许用户访问由 MySQL 4.1 或更高版本所提供的功能。有关 MySQL 数据库服务器的更多信息见 http://www.mysql.com/。

MySQL 的文档见 http://dev.mysql.com/doc/。

经 MySQL AB 授权，本文档中包括部分 MySQL 手册的内容。

# 需求

要使用本扩展库中的函数，必须在编译 PHP 时加入 mysqli 扩展的支持。

> 注意: mysqli 扩展库是设计用于同 MySQL 4.1.3 或更高版本协同工作的。对之前版本，请参考 MySQL 扩展库文档。

# 安装

要安装 PHP 的 mysqli 扩展，配置时加上 `--with-mysqli=mysql_config_path/mysql_config`。其中 `mysql_config_path` 表示 `mysql_config` 程序的路径，该程序随 MySQL 大于 4.1 版本一起发布。

如果要同时安装 mysql 和 mysqli 扩展，必须使用同一个客户端库以避免冲突。

# 运行时配置

这些函数的行为受 `php.ini` 的影响。

表 1. MySQLi 配置选项

名称 | 默认值 | 可修改范围 | 更新日志
--- | --- | --- | ---
mysqli.max_links | "-1" | PHP_INI_SYSTEM | 自 PHP 5.0.0 起可用。
mysqli.default_port | "3306" | PHP_INI_ALL | 自 PHP 5.0.0 起可用。
mysqli.default_socket | NULL | PHP_INI_ALL | 自 PHP 5.0.0 起可用。
mysqli.default_host | NULL | PHP_INI_ALL | 自 PHP 5.0.0 起可用。
mysqli.default_user | NULL | PHP_INI_ALL | 自 PHP 5.0.0 起可用。
mysqli.default_pw | NULL | PHP_INI_ALL | 自 PHP 5.0.0 起可用。

以上 PHP_INI_* 常量的进一步细节及定义，见怎样修改配置设定一节。

以下是配置选项的简要解释。

`mysqli.max_links` integer

  每个进程的 MySQL 连接的最大数目。

`mysqli.default_port` string

  The default TCP port number to use when connecting to the database server if no other port is specified. If no default is specified, the port will be obtained from the `MYSQL_TCP_PORT` environment variable, the `mysql-tcp` entry in `/etc/services` or the compile-time `MYSQL_PORT` constant, in that order. Win32 will only use the `MYSQL_PORT` constant.

`mysqli.default_socket` string

  The default socket name to use when connecting to a local database server if no other socket name is specified.

`mysqli.default_host` string

  The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in safe mode.

`mysqli.default_user` string

  The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in safe mode.

`mysqli.default_pw` string

  The default password to use when connecting to the database server if no other password is specified. Doesn't apply in safe mode.

# 预定义类

## mysqli

表达了 PHP 和 MySQL 数据库之间的连接。

### 构造函数

- mysqli - 构造一个新的 mysqli 对象

### 方法

- autocommit - 打开或关闭自动提交的数据库选项

- change_user - 改变指定的数据库连接的用户

- character_set_name - 返回数据库连接的默认字符集

- close - 关闭一个之前打开的连接

- commit - 提交当前事务

- connect - 打开一个到 MySQL 数据库服务器的新连接

- debug - 执行排错操作

- dump_debug_info - 取得排错信息

- get_client_info - 返回客户端版本

- get_host_info - 返回连接使用的类型

- get_server_info - 返回 MySQL 服务器的版本

- get_server_version - 返回 MySQL 服务器的版本

- init - 初始化 mysqli 对象

- info - 取得最近执行的查询的信息

- kill - 要求服务器停止一个 mysql 线程

- multi_query - 执行多个查询

- more_results - check if more results exist from currently executed multi-query

- next_result - reads next result from currently executed multi-query

- options - set options

- ping - pings a server connection or reconnects if there is no connection

- prepare - prepares a SQL query

- query - performs a query

- real_connect - attempts to open a connection to MySQL database server

- escape_string - escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection

- rollback - rolls back the current transaction

- select_db - selects the default database

- set_charset - sets the default client character set

- ssl_set - sets ssl parameters

- stat - gets the current system status

- stmt_init- initializes a statement for use with mysqli_stmt_prepare

- store_result - transfers a resultset from last query

- thread_safe - returns whether thread safety is given or not

- use_result - transfers an unbuffered resultset from last query

### 属性

- affected_rows - gets the number of affected rows in a previous MySQL operation

- client_info - returns the MySQL client version as a string

- client_version - returns the MySQL client version as an integer

- errno - returns the error code for the most recent function call

- error - returns the error string for the most recent function call

- field_count - returns the number of columns for the most recent query

- host_info - returns a string representing the type of connection used

- info - retrieves information about the most recently executed query

- insert_id - returns the auto generated id used in the last query

- protocol_version - returns the version of the MySQL protocol used

- server_info - returns a string that represents the server version number

- server_version - returns the version number of the server as an integer

- sqlstate - returns a string containing the SQLSTATE error code for the last error

- thread_id - returns the thread ID for the current connection

- warning_count - returns the number of warnings generated during execution of the previous SQL statement

## mysqli_stmt

表达了一个预备好的语句。

### 方法

- bind_param - binds variables to a prepared statement

- bind_result - binds variables to a prepared statement for result storage

- close - closes a prepared statement

- data_seek - seeks to an arbitrary row in a statement result set

- execute - executes a prepared statement

- fetch - fetches result from a prepared statement into bound variables

- free_result - frees stored result memory for the given statement handle

- prepare - prepares a SQL query

- reset - resets a prepared statement

- result_metadata - retrieves a resultset from a prepared statement for metadata information

- send_long_data - sends data in chunks

- store_result - buffers complete resultset from a prepared statement

### 属性

- affected_rows - returns affected rows from last statement execution

- errno - returns errorcode for last statement function

- error - returns errormessage for last statement function

- field_count - returns the number of columns in a result set

- id - returns the statement identifier

- insert_id - returns the value generated for an AUTO_INCREMENT column by the prepared statement

- num_rows - returns the number of rows in the result set

- param_count - returns number of parameter for a given prepare statement

- sqlstate - returns a string containing the SQLSTATE error code for the last statement function

## mysqli_result

表达了对数据库的查询所返回的结果集。

### 方法

- close - closes resultset

- data_seek - moves internal result pointer

- fetch_array - fetches a result row as an associative array, a numeric array, or both.

- fetch_assoc - fetches a result row as an associative array

- fetch_field - gets column information from a resultset

- fetch_fields - gets information for all columns from a resulset

- fetch_field_direct - gets column information for specified column

- fetch_object - fetches a result row as an object

- fetch_row - gets a result row as an enumerated array

- field_seek - set result pointer to a specified field offset

- free_result - frees result memory

### 属性

- current_field - returns offset of current fieldpointer

- field_count - returns number of fields in resultset

- lengths - returns an array of columnlengths

- num_rows - returns number of rows in resultset

- type - returns `MYSQLI_STORE_RESULT` or `MYSQLI_USE_RESULT`

# 预定义常量

表 2. MySQLi 常量

名称 | 说明
--- | ---
`MYSQLI_READ_DEFAULT_GROUP` (integer) | Read options from the named group from `my.cnf' or the file specified with `MYSQLI_READ_DEFAULT_FILE`
`MYSQLI_READ_DEFAULT_FILE` (integer) | Read options from the named option file instead of from `my.cnf`
`MYSQLI_OPT_CONNECT_TIMEOUT` (integer) | Connect timeout in seconds
`MYSQLI_OPT_LOCAL_INFILE` (integer) | Enables command `LOAD LOCAL INFILE`
`MYSQLI_INIT_COMMAND` (integer) | Command to execute when connecting to MySQL server. Will automatically be re-executed when reconnecting.
`MYSQLI_CLIENT_SSL` (integer) | Use SSL (encrypted protocol). This option should not be set by application programs; it is set internally in the MySQL client library
`MYSQLI_CLIENT_COMPRESS` (integer) | Use compression protocol
`MYSQLI_CLIENT_INTERACTIVE` (integer) | Allow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection. The client's session wait_timeout variable will be set to the value of the session interactive_timeout variable.
`MYSQLI_CLIENT_IGNORE_SPACE` (integer) | Allow spaces after function names. Makes all functions names reserved words.
`MYSQLI_CLIENT_NO_SCHEMA` (integer) | Don't allow the db_name.tbl_name.col_name syntax.
`MYSQLI_CLIENT_MULTI_QUERIES` (integer) |
`MYSQLI_STORE_RESULT` (integer) | For using buffered resultsets
`MYSQLI_USE_RESULT` (integer) | For using unbuffered resultsets
`MYSQLI_ASSOC` (integer) | Columns are returned into the array having the fieldname as the array index.
`MYSQLI_NUM` (integer) | Columns are returned into the array having an enumerated index.
`MYSQLI_BOTH` (integer) | Columns are returned into the array having both a numerical index and the fieldname as the associative index.
`MYSQLI_NOT_NULL_FLAG` (integer) | Indicates that a field is defined as `NOT NULL`
`MYSQLI_PRI_KEY_FLAG` (integer) | Field is part of a primary index
`MYSQLI_UNIQUE_KEY_FLAG` (integer) | Field is part of a unique index.
`MYSQLI_MULTIPLE_KEY_FLAG` (integer) | Field is part of an index.
`MYSQLI_BLOB_FLAG` (integer) | Field is defined as `BLOB`
`MYSQLI_UNSIGNED_FLAG` (integer) | Field is defined as `UNSIGNED`
`MYSQLI_ZEROFILL_FLAG` (integer) | Field is defined as `ZEROFILL`
`MYSQLI_AUTO_INCREMENT_FLAG` (integer) | Field is defined as `AUTO_INCREMENT`
`MYSQLI_TIMESTAMP_FLAG` (integer) | Field is defined as `TIMESTAMP`
`MYSQLI_SET_FLAG` (integer) | Field is defined as `SET`
`MYSQLI_NUM_FLAG` (integer) | Field is defined as `NUMERIC`
`MYSQLI_PART_KEY_FLAG` (integer) | Field is part of an multi-index
`MYSQLI_GROUP_FLAG` (integer) | Field is part of `GROUP BY`
`MYSQLI_TYPE_DECIMAL` (integer) | Field is defined as `DECIMAL`
`MYSQLI_TYPE_NEWDECIMAL` (integer) | Precision math `DECIMAL` or `NUMERIC` field (MySQL 5.0.3 and up)
`MYSQLI_TYPE_BIT` (integer) | Field is defined as `BIT` (MySQL 5.0.3 and up)
`MYSQLI_TYPE_TINY` (integer) | Field is defined as `TINYINT`
`MYSQLI_TYPE_SHORT` (integer) | Field is defined as `INT`
`MYSQLI_TYPE_LONG` (integer) | Field is defined as `INT`
`MYSQLI_TYPE_FLOAT` (integer) | Field is defined as `FLOAT`
`MYSQLI_TYPE_DOUBLE` (integer) | Field is defined as `DOUBLE`
`MYSQLI_TYPE_NULL` (integer) | Field is defined as `DEFAULT NULL`
`MYSQLI_TYPE_TIMESTAMP` (integer) | Field is defined as `TIMESTAMP`
`MYSQLI_TYPE_LONGLONG` (integer) | Field is defined as `BIGINT`
`MYSQLI_TYPE_INT24` (integer) | Field is defined as `MEDIUMINT`
`MYSQLI_TYPE_DATE` (integer) | Field is defined as `DATE`
`MYSQLI_TYPE_TIME` (integer) | Field is defined as `TIME`
`MYSQLI_TYPE_DATETIME` (integer) | Field is defined as `DATETIME`
`MYSQLI_TYPE_YEAR` (integer) | Field is defined as `YEAR`
`MYSQLI_TYPE_NEWDATE` (integer) | Field is defined as `DATE`
`MYSQLI_TYPE_ENUM` (integer) | Field is defined as `ENUM`
`MYSQLI_TYPE_SET` (integer) | Field is defined as `SET`
`MYSQLI_TYPE_TINY_BLOB` (integer) | Field is defined as `TINYBLOB`
`MYSQLI_TYPE_MEDIUM_BLOB` (integer) | Field is defined as `MEDIUMBLOB`
`MYSQLI_TYPE_LONG_BLOB` (integer) | Field is defined as `LONGBLOB`
`MYSQLI_TYPE_BLOB` (integer) | Field is defined as `BLOB`
`MYSQLI_TYPE_VAR_STRING` (integer) | Field is defined as `VARCHAR`
`MYSQLI_TYPE_STRING` (integer) | Field is defined as `CHAR`
`MYSQLI_TYPE_GEOMETRY` (integer) | Field is defined as `GEOMETRY`
`MYSQLI_NEED_DATA` (integer) | More data available for bind variable
`MYSQLI_NO_DATA` (integer) | No more data available for bind variable
`MYSQLI_DATA_TRUNCATED` (integer) | Data truncation occurred. Available since PHP 5.1.0 and MySQL 5.0.5.

# 例子

在 MySQLI 文档中的所有例子都使用了来自 MySQL AB 的 world 数据库。数据库 world 可以在此地址下载：http://dev.mysql.com/get/Downloads/Manual/world.sql.gz/from/pick。

上一页 | 起始页 | 下一页
PDO_MYSQL DSN | 上一级 | mysqli_affected_rows