21.9.2.1. Installing/Configuring

21.9.2.1.1. Requirements

In order to have these functions available, you must compile PHP with MySQL support.

21.9.2.1.2. Installation

For compiling, simply use the --with-mysql[=DIR] configuration option where the optional [DIR] points to the MySQL installation directory.

Although this MySQL extension is compatible with MySQL 4.1.0 and greater, it doesn't support the extra functionality that these versions provide. For that, use the MySQLi extension.

If you would like to install the mysql extension along with the mysqli extension you have to use the same client library to avoid any conflicts.

21.9.2.1.2.1. Installation on Linux Systems

Note: [DIR] is the path to the MySQL client library files (headers and libraries), which can be downloaded from MySQL.

Table 21.37. ext/mysql compile time support matrix

PHP Version	Default	Configure Options: mysqlnd	Configure Options: `libmysqlclient`	Changelog
4.x.x	libmysqlclient	Not Available	`--without-mysql` to disable	MySQL enabled by default, MySQL client libraries are bundled
5.0.x, 5.1.x, 5.2.x	libmysqlclient	Not Available	`--with-mysql=[DIR]`	MySQL is no longer enabled by default, and the MySQL client libraries are nolonger bundled
5.3.x	libmysqlclient	`--with-mysql=mysqlnd`	`--with-mysql=[DIR]`	mysqlnd is now available
5.4.x	mysqlnd	`--with-mysql`	`--with-mysql=[DIR]`	mysqlnd is now the default

21.9.2.1.2.2. Installation on Windows Systems

21.9.2.1.2.2.1. PHP 4

The PHP MySQL extension is compiled into PHP.

21.9.2.1.2.2.2. PHP 5.0.x, 5.1.x, 5.2.x

MySQL is no longer enabled by default, so the php_mysql.dll DLL must be enabled inside of php.ini. Also, PHP needs access to the MySQL client library. A file named libmysql.dll is included in the Windows PHP distribution and in order for PHP to talk to MySQL this file needs to be available to the Windows systems PATH. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Although copying libmysql.dll to the Windows system directory also works (because the system directory is by default in the system's PATH), it's not recommended.

As with enabling any PHP extension (such as php_mysql.dll), the PHP directive extension_dir should be set to the directory where the PHP extensions are located. See also the Manual Windows Installation Instructions. An example extension_dir value for PHP 5 is c:\php\ext

Note

If when starting the web server an error similar to the following occurs: "Unable to load dynamic library './php_mysql.dll'", this is because php_mysql.dll and/or libmysql.dll cannot be found by the system.

21.9.2.1.2.2.3. PHP 5.3.0+

The MySQL Native Driver is enabled by default. Include php_mysql.dll, but libmysql.dll is no longer required or used.

21.9.2.1.2.3. MySQL Installation Notes

Warning

Crashes and startup problems of PHP may be encountered when loading this extension in conjunction with the recode extension. See the recode extension for more information.

Note

If you need charsets other than latin (default), you have to install external (not bundled) libmysqlclient with compiled charset support.

21.9.2.1.3. Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 21.38. MySQL Configuration Options

Name	Default	Changeable	Changelog
mysql.allow_local_infile	"1"	PHP_INI_SYSTEM
mysql.allow_persistent	"1"	PHP_INI_SYSTEM
mysql.max_persistent	"-1"	PHP_INI_SYSTEM
mysql.max_links	"-1"	PHP_INI_SYSTEM
mysql.trace_mode	"0"	PHP_INI_ALL	Available since PHP 4.3.0.
mysql.default_port	NULL	PHP_INI_ALL
mysql.default_socket	NULL	PHP_INI_ALL	Available since PHP 4.0.1.
mysql.default_host	NULL	PHP_INI_ALL
mysql.default_user	NULL	PHP_INI_ALL
mysql.default_password	NULL	PHP_INI_ALL
mysql.connect_timeout	"60"	PHP_INI_ALL	PHP_INI_SYSTEM in PHP <= 4.3.2. Available since PHP 4.3.0.

Here's a short explanation of the configuration directives.

mysql.allow_local_infile integer: Allow accessing, from PHP's perspective, local files with LOAD DATA statements
mysql.allow_persistent boolean: Whether to allow persistent connections to MySQL.
mysql.max_persistent integer: The maximum number of persistent MySQL connections per process.
mysql.max_links integer: The maximum number of MySQL connections per process, including persistent connections.
mysql.trace_mode boolean: Trace mode. When mysql.trace_mode is enabled, warnings for table/index scans, non free result sets, and SQL-Errors will be displayed. (Introduced in PHP 4.3.0)
mysql.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.
mysql.default_socket string: The default socket name to use when connecting to a local database server if no other socket name is specified.
mysql.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 SQL safe mode.
mysql.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 SQL safe mode.
mysql.default_password string: The default password to use when connecting to the database server if no other password is specified. Doesn't apply in SQL safe mode.
mysql.connect_timeout integer: Connect timeout in seconds. On Linux this timeout is also used for waiting for the first answer from the server.

21.9.2.1.4. Resource Types

There are two resource types used in the MySQL module. The first one is the link identifier for a database connection, the second a resource which holds the result of a query.