# MySQL Functions

## Introduction

These functions allow you to access MySQL database servers. More information about MySQL can be found at » http://www.mysql.com/.

Documentation for MySQL can be found at » http://dev.mysql.com/doc/.

## Requirements

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

## 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.

## Installation on Linux Systems

## PHP 4

The option --with-mysql is enabled by default. This default behavior may be disabled with the --without-mysql configure option. If MySQL is enabled without specifying the path to the MySQL install DIR, PHP will use the bundled MySQL client libraries.

Users who run other applications that use MySQL (for example, auth-mysql) should not use the bundled library, but rather specify the path to MySQL's install directory, like so: --with-mysql=/path/to/mysql. This will force PHP to use the client libraries installed by MySQL, thus avoiding any conflicts.

## PHP 5+

MySQL is not enabled by default, nor is the MySQL library bundled with PHP. Read this FAQ for details on why. Use the --with-mysql[=DIR] configure option to include MySQL support. You can download headers and libraries from » MySQL.

## Installation on Windows Systems

## PHP 4

The PHP MySQL extension is compiled into PHP.

## PHP 5+

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.

## 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) libmysql with compiled charset support.

## Runtime Configuration

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

MySQL Configuration Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
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.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`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.

## 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.

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

Since PHP 4.3.0 it is possible to specify additional client flags for the mysql_connect() and mysql_pconnect() functions. The following constants are defined:

MySQL client constants
Constant | Description
--- | ---
MYSQL_CLIENT_COMPRESS | Use compression protocol
MYSQL_CLIENT_IGNORE_SPACE | Allow space after function names
MYSQL_CLIENT_INTERACTIVE | Allow interactive_timeout seconds (instead of wait_timeout) of inactivity before closing the connection.
MYSQL_CLIENT_SSL | Use SSL encryption. This flag is only available with version 4.x of the MySQL client library or newer. Version 3.23.x is bundled both with PHP 4 and Windows binaries of PHP 5.

The function mysql_fetch_array() uses a constant for the different types of result arrays. The following constants are defined:

MySQL fetch constants
Constant | Description
--- | ---
MYSQL_ASSOC | Columns are returned into the array having the fieldname as the array index.
MYSQL_BOTH | Columns are returned into the array having both a numerical index and the fieldname as the array index.
MYSQL_NUM | Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result.

## Notes

> Note: Most MySQL functions accept `link_identifier` as the last optional parameter. If it is not provided, last opened connection is used. If it doesn't exist, connection is tried to establish with default parameters defined in php.ini. If it is not successful, functions return `FALSE`.

## Examples

This simple example shows how to connect, execute a query, print resulting rows and disconnect from a MySQL database.

Example#1 MySQL extension overview example

`<?php
// Connecting, selecting database
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
or die('Could not connect: ' . mysql_error());
echo 'Connected successfully';
mysql_select_db('my_database') or die('Could not select database');
// Performing SQL query
$query = 'SELECT * FROM my_table';
$result = mysql_query($query) or die('Query failed: ' . mysql_error());
// Printing results in HTML
echo "<table>\n";
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($line as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";
// Free resultset
mysql_free_result($result);
// Closing connection
mysql_close($link);
?>`

## Table of Contents

- mysql_affected_rows — Get number of affected rows in previous MySQL operation
- mysql_change_user — Change logged in user of the active connection
- mysql_client_encoding — Returns the name of the character set
- mysql_close — Close MySQL connection
- mysql_connect — Open a connection to a MySQL Server
- mysql_create_db — Create a MySQL database
- mysql_data_seek — Move internal result pointer
- mysql_db_name — Get result data
- mysql_db_query — Send a MySQL query
- mysql_drop_db — Drop (delete) a MySQL database
- mysql_errno — Returns the numerical value of the error message from previous MySQL operation
- mysql_error — Returns the text of the error message from previous MySQL operation
- mysql_escape_string — Escapes a string for use in a mysql_query
- mysql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- mysql_fetch_assoc — Fetch a result row as an associative array
- mysql_fetch_field — Get column information from a result and return as an object
- mysql_fetch_lengths — Get the length of each output in a result
- mysql_fetch_object — Fetch a result row as an object
- mysql_fetch_row — Get a result row as an enumerated array
- mysql_field_flags — Get the flags associated with the specified field in a result
- mysql_field_len — Returns the length of the specified field
- mysql_field_name — Get the name of the specified field in a result
- mysql_field_seek — Set result pointer to a specified field offset
- mysql_field_table — Get name of the table the specified field is in
- mysql_field_type — Get the type of the specified field in a result
- mysql_free_result — Free result memory
- mysql_get_client_info — Get MySQL client info
- mysql_get_host_info — Get MySQL host info
- mysql_get_proto_info — Get MySQL protocol info
- mysql_get_server_info — Get MySQL server info
- mysql_info — Get information about the most recent query
- mysql_insert_id — Get the ID generated from the previous INSERT operation
- mysql_list_dbs — List databases available on a MySQL server
- mysql_list_fields — List MySQL table fields
- mysql_list_processes — List MySQL processes
- mysql_list_tables — List tables in a MySQL database
- mysql_num_fields — Get number of fields in result
- mysql_num_rows — Get number of rows in result
- mysql_pconnect — Open a persistent connection to a MySQL server
- mysql_ping — Ping a server connection or reconnect if there is no connection
- mysql_query — Send a MySQL query
- mysql_real_escape_string — Escapes special characters in a string for use in a SQL statement
- mysql_result — Get result data
- mysql_select_db — Select a MySQL database
- mysql_set_charset — Sets the client character set
- mysql_stat — Get current system status
- mysql_tablename — Get table name of field
- mysql_thread_id — Return the current thread ID
- mysql_unbuffered_query — Send an SQL query to MySQL, without fetching and buffering the result rows