LXIV. 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://www.mysql.com/documentation/.

Requirements

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

Installation

By using the --with-mysql[=DIR] configuration option you enable PHP to access MySQL databases.

In PHP 4, the option --with-mysql is enabled by default. To disable this default behavior, you may use the --without-mysql configure option. Also in PHP 4, if you enable MySQL without specifying the path to the MySQL install DIR, PHP will use the bundled MySQL client libraries. In Windows, there is no DLL, it's simply built into PHP 4. 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.

In PHP 5, MySQL is no longer enabled by default, nor is the MySQL library bundled with PHP. Read this FAQ for details on why.

This MySQL extension doesn't support full functionality of MySQL versions greater than 4.1.0. For that, use MySQLi.

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.

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.

Table 1. MySQL Configuration Options

Name	Default	Changeable
mysql.allow_persistent	"On"	PHP_INI_SYSTEM
mysql.max_persistent	"-1"	PHP_INI_SYSTEM
mysql.max_links	"-1"	PHP_INI_SYSTEM
mysql.default_port	NULL	PHP_INI_ALL
mysql.default_socket	NULL	PHP_INI_ALL
mysql.default_host	NULL	PHP_INI_ALL
mysql.default_user	NULL	PHP_INI_ALL
mysql.default_password	NULL	PHP_INI_ALL
mysql.connect_timeout	"0"	PHP_INI_SYSTEM

For further details and definition of the PHP_INI_* constants see ini_set().

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

Table 2. 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.

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

Table 3. 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.

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, taking into account the current charset of the connection.
mysql_result -- Get result data
mysql_select_db -- Select a MySQL database
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