LXXXII. Funciones MySQL

Introducción

Estas funciones le permiten acceder a servidores de bases de datos MySQL. Puede encontrar más información sobre MySQL en http://www.mysql.com/.

La documentación de MySQL puede encontrarse en http://dev.mysql.com/doc/.

Requirimientos

Para contar con éstas funciones, debe compilar PHP con soporte MySQL.

Instalación

Para la compilación, simplemente use la opción de configuración --with-mysql[=DIR], en donde el valor opcional [DIR] apunta al directorio de instalación de MySQL.

Esta extensión de MySQL no soporta la funcionalidad completa de versiones de MySQL superiores a 4.1.0. Para ellas, use MySQLi.

Si quisiera instalar la extensión mysql junto con la extensión mysqli, debe usar la misma biblioteca de cliente para evitar cualquier conflicto.

La opción --with-mysql está habilitada por defecto. Para desactivar este comportamiento predeterminado, usted puede usar la opción de configuración --without-mysql. Si se habilita MySQL sin especificar el directorio de instalación de MySQL, PHP usará las bibliotecas de cliente de MySQL incorporadas.

Los usuarios que ejecutan otras aplicaciones que usan MySQL (auth-mysql, por ejemplo) no deberían usar la biblioteca incorporada, en su lugar deben especificar la ruta al directorio de instalación de MySQL, de este modo: --with-mysql=/ruta/hacia/mysql. Esto obligará a PHP a usar las bibliotecas de cliente instaladas por MySQL, para así evitar cualquier conflicto.

PHP 5+

El soporte para MySQL no se encuentra habilitado por defecto, ni lo está la biblioteca incorporada con PHP. Lea este FAQ para conocer los detalles del porqué. Use la opcián de configuración --with-mysql[=DIR] para incluir el soporte para MySQL. Es posible descargar las cabeceras y bibliotecas desde MySQL.

Instalación en Sistemas Windows

PHP 4

La extensión MySQL de PHP es compilada en PHP.

PHP 5+

El soporte para MySQL ya no es habilitado por defecto, así que el DLL php_mysql.dll DLL debe habilitarse al interior de php.ini. Asimismo, PHP necesita acceder a la biblioteca de cliente MySQL. Un archivo de nombre libmysql.dll es incluido en la distribución de PHP en Windows, y para que PHP se comunique con MySQL, este archivo necesita estar disponible en la ruta PATH de los sistemas Windows. Vea la entrada del FAQ titulada "Cómo agrego mi directorio PHP a la ruta PATH en Windows" para más información sobre cómo hacerlo. Aunque copiar libmysql.dll al directorio de sistema de Windows también funciona (ya que el directorio de sistema es parte del PATH de sistema por defecto), tal acción no es recomendada.

Al igual que ocurre con cualquier otra extensión (como php_mysql.dll), la directiva de PHP extension_dir debe definirse con el directorio en donde están ubicadas las extensiones PHP. Vea también las Instrucciones de Instalación Manual en Windows. Un valor de ejemplo de extension_dir para PHP 5 es c:\php\ext

Nota: Si al iniciar el servidor web un error similar al siguiente ocurre: "Unable to load dynamic library './php_mysql.dll'", se debe a que php_mysql.dll o libmysql.dll no pueden encontrarse por el sistema.

MySQL Installation Notes

Aviso

Pueden encontrarse problemas de inicialización y bloqueos de PHP cuando esta extensión es cargada en conjunto con la extensión recode. Consulte sobre la extensión recode para más información.

Nota: Si necesita juegos de caracteres diferentes a latin (el juego por defecto), tendrá que instalar una biblioteca de mysql externa (no incorporada) que haya sido compilada con soporte para los juegos de caracteres.

Configuración en tiempo de ejecución

El comportamiento de estas funciones está afectado por los valores definidos en php.ini.

Tabla 1. Opciones de Configuración MySQL

Nombre	Por defecto	Modificable	Cambios
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	Disponible desde PHP 4.3.0.
mysql.default_port	NULL	PHP_INI_ALL
mysql.default_socket	NULL	PHP_INI_ALL	Disponible desde 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 en PHP <= 4.3.2. Disponible desde PHP 4.3.0.

For further details and definitions of the PHP_INI_* constants, see the Apéndice H.

A continuación se presenta una corta explicación de las directivas de configuración.

mysql.allow_persistent boolean: Indica si se permiten conexiones persistentes con MySQL.
mysql.max_persistent integer: El número máximo de conexiones persistentes con MySQL por proceso.
mysql.max_links integer: El número máximo de conexiones con MySQL por proceso, incluyendo conexiones persistentes.
mysql.trace_mode boolean: Modo de rastreo. Cuando se habilita mysql.trace_mode, se muestran advertencias para la apertura de tablas/índices, conjuntos de resultados no liberados, y errores SQL. (Se introdujo en PHP 4.3.0)
mysql.default_port string: El número de puerto TCP predeterminado para usar cuando se conecta con el servidor de bases de datos, si no se indica otro. Si no se indica un valor predeterminado, el puerto se obtendrá de la variable de entorno MYSQL_TCP_PORT, la entrada mysql-tcp en /etc/services o la constante de tiempo de compilación MYSQL_PORT, en ese orden. En Win32 sólo se usa la constante MYSQL_PORT.
mysql.default_socket string: El nombre de socket predeterminado a ser usado cuando se realicen conexiones con un servidor de base de datos local, si no se indica algún otro.
mysql.default_host string: La máquina anfitriona predeterminada a ser usada cuando se realicen conexiones con un servidor de bases de datos, si no se indica otro valor. No es aplicable en SQL safe mode.
mysql.default_user string: El nombre de usuario prodeterminado para conectarse al servidor de bases de datos si no se indica otro. No es aplicable bajo SQL safe mode.
mysql.default_password string: La contraseña predeterminada a usar cuando se realicen conexiones con el servidor de bases de datos, si no se indica otro valor. No es aplicable en SQL safe mode.
mysql.connect_timeout integer: Tiempo de espera máximo de conexión, en segundos. Bajo Linux este tiempo de espera es usado también cuando se espera la primera respuesta del servidor.

Tipos de recursos

Hay dos tipos de recursos usados en el módulo MySQL. El primero es el identificador de enlace para una conexión de base de datos, el segundo es un recurso que almacena el resultado de una consulta.

Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinámicamente en tiempo de ejecución.

A partir de PHP 4.3.0, es posible especificar banderas de cliente adicionales para las funciones mysql_connect() y mysql_pconnect(). Las siguientes constantes están definidas:

Tabla 2. Constantes de cliente MySQL

Constante	Descripción
MYSQL_CLIENT_COMPRESS	Usar protocolo de compresión
MYSQL_CLIENT_IGNORE_SPACE	Permitir espacios después de nombres de funciones
MYSQL_CLIENT_INTERACTIVE	Permitir tantos segundos de inactividad como indique interactive_timeout (en lugar de wait_timeout) antes de cerrar la conexión
MYSQL_CLIENT_SSL	Usar encripción SSL. Esta bandera se encuentra disponible únicamente con la versión 4.x o más reciente de la biblioteca cliente de MySQL. La versión 3.23.x se distribuye tanto con PHP 4 como con los binarios de Windows de PHP 5.

La función mysql_fetch_array() usa una constante para los diferentes tipos de matrices de resultado. Las siguientes constantes están definidas:

Tabla 3. Constantes MySQL-fetch

Constante	Descripción
MYSQL_ASSOC	Las columnas son devueltas en la matriz usando el nombre del campo como índice.
MYSQL_BOTH	Las columnas son devueltas en la matriz teniendo tanto un índice numérico como un índice correspondiente al nombre del campo.
MYSQL_NUM	Las columnas son devueltas en la matriz teniendo un índice numérico a los campos. Este índice comienza en 0, el primer campo del resultado.

Notes

Nota: La mayoría de funciones de MySQL aceptan identificador_enlace como último parámetro opcional. Si no es definido, se utiliza la última conexión abierta. Si no existe, se intenta establecer una conexión con los parámetros predeterminados definidos en php.ini. Si no tiene éxito, las funciones devuelven FALSE.

Ejemplos

Este sencillo ejemplo muestra cómo conectarse, ejecutar una consulta, imprimir las filas resultantes y desconectarse de una base de datos MySQL.

Ejemplo 1. Ejemplo general de la extensión MySQL


<?php
// Conexion, seleccion de base de datos
$enlace = mysql_connect('host_mysql', 'usuario_mysql', 'contrasenya_mysql')
    or die('No pudo conectarse : ' . mysql_error());
echo 'Conexi&oacute;n exitosa';
mysql_select_db('mi_base_de_datos') or die('No pudo seleccionarse la BD.');

// Realizar una consulta SQL
$consulta  = 'SELECT * FROM mi_tabla';
$resultado = mysql_query($consulta) or die('La consulta fall&oacute;: ' . mysql_error());

// Impresion de resultados en HTML
echo "<table>\n";
while ($linea = mysql_fetch_array($resultado, MYSQL_ASSOC)) {
    echo "\t<tr>\n";
    foreach ($linea as $valor_col) {
        echo "\t\t<td>$valor_col</td>\n";
    }
    echo "\t</tr>\n";
}
echo "</table>\n";

// Liberar conjunto de resultados
mysql_free_result($resultado);

// Cerrar la conexion
mysql_close($enlace);
?>

Tabla de contenidos
mysql_affected_rows -- Devuelve el número de filas afectadas de la última operación MySQL
mysql_change_user -- Cambia el usuario conectado en la conexión activa
mysql_client_encoding -- Devuelve el nombre del juego de caracteres
mysql_close -- cierra el enlace con MySQL
mysql_connect -- Abre una conexión a un servidor MySQL
mysql_create_db -- Crea una base MySQL
mysql_data_seek -- Mueve el puntero interno
mysql_db_name -- Obtener datos de resultado
mysql_db_query -- Envia una sentencia MySQL al servidor
mysql_drop_db -- Borra una base de datos MySQL
mysql_errno -- Deuelve el número del mensaje de error de la última operación MySQL
mysql_error -- Devuelve el texto del mensaje de error de la última operación MySQL
mysql_escape_string -- Escapa una cadena para su uso en mysql_query
mysql_fetch_array -- Extrae la fila de resultado como una matriz asociativa, una matriz numérica o ambas
mysql_fetch_assoc -- Recupera una fila de resultado como una matriz asociativa
mysql_fetch_field -- Extrae la información de una columna y la devuelve como un objeto.
mysql_fetch_lengths -- Devuelve la longitud de cada salida en un resultado
mysql_fetch_object -- Extrae una fila de resultado como un objeto
mysql_fetch_row -- Devuelve una fila de resultado como matriz
mysql_field_flags -- Devuelve las banderas asociados con el campo específicado en un resultado
mysql_field_len -- Devuelve la longitud del campo específicado
mysql_field_name -- Devuelve el nombre del campo específicado en un resultado
mysql_field_seek -- Asigna el puntero del resultado al offset del campo específicado
mysql_field_table -- Devuelve el nombre de la tabla donde está el campo específicado
mysql_field_type -- Devuelve el tipo del campo específicado en un resultado
mysql_free_result -- Libera la memoria del resultado
mysql_get_client_info -- Obtener información del cliente MySQL
mysql_get_host_info -- Obtener información de la máquina anfitriona MySQL
mysql_get_proto_info -- Obtener información del protocolo MySQL
mysql_get_server_info -- Obtener información del servidor MySQL
mysql_info -- Obtiene información sobre la consulta más reciente
mysql_insert_id -- Devuelve el identificador generado en la última llamada a INSERT
mysql_list_dbs -- Lista las bases de datos disponibles en el servidor MySQL
mysql_list_fields -- Lista los campos del resultado de MySQL
mysql_list_processes -- Lista los procesos MySQL
mysql_list_tables -- Lista las tablas en una base de datos MySQL
mysql_num_fields -- devuelve el número de campos de un resultado
mysql_num_rows -- Devuelve el número de filas de un resultado
mysql_pconnect -- Abre una conexión persistente al servidor MySQL
mysql_ping -- Efectuar un chequeo de respuesta (ping) sobre una conexión de servidor o reconectarse si no hay conexión
mysql_query -- Envía una consulta de MySQL
mysql_real_escape_string -- Escapa caracteres especiales de una cadena para su uso en una sentencia SQL
mysql_result -- Devuelve datos de un resultado
mysql_select_db -- Selecciona un base de datos MySQL
mysql_stat -- Obtener el status actual del sistema
mysql_tablename -- Devuelve el nombre de la tabla de un campo
mysql_thread_id -- Devuelve el ID del hilo actual
mysql_unbuffered_query -- Envía una consulta SQL a MySQL, sin recuperar ni colocar en búfer las filas de resultado