XCIV. Funções do MySQL

Introdução

Estas funções permitem a você acessar os servidoes de banco de dados MySQL. maiores informações sobre o MySQL podem ser encontradas em http://www.mysql.com/.

A documentação para o MySQL pode ser encontrada em http://dev.mysql.com/doc/.

Dependências

Para ter estas funções disponíveis, você deve compilar o PHP com suporte a MySQL.

Instalação

Para compilar, simplesmente use a opção de configuração --with-mysql[=DIR] aonde o parãmetro opcional [DIR] aponta para o diretório onde o MySQL esta instalado.

Mesmo sendo esta extensão MySQL compativel com MySQL 4.1.0 e posterior, ela não suporta a funcionalidade extra que estas versões proveem. Para isto, use a extensão MySQLi.

Se você quiser instalar a extensão mysql em conjuno com a extnsão mysqli você deve usar a mesma biblioteca de cliente para evitar quaisquer conflitos.

Instalação em Sistemas Linux

PHP 4

A opção --with-mysql é ativada por padrão. Este é o funcionamento padrão e pode ser desabilitado com a opção de configuração --without-mysql. Se o MySQL for ativado sem especificar o caminho para o diretório de instalação do MySQL, o PHP irá usar a biblioteca de cliente MySQL embutida.

Usuários que executam outras aplicações que usam o MySQL (por exemplo, auth-mysql) não devem usar a biblioteca embutida, mas ao invés especificar o caminho para o diretório de instalação do MySQL, assim: --with-mysql=/path/to/mysql. Isto irá forçar o PHP a usar as bibliotecas de cliente instaladas pelo MySQL, assim evitando quaisquer conflitos.

PHP 5+

O MySQL não esta ativo por padrão, nem a biblioteca MySQL é embutida com o PHP. Leia este FAQ para detalhes sobre o motivo. Use a opção de configuração --with-mysql[=DIR] Para incluir o suporte a MySQL. Você pode baixar cabeçalhos e bibliotecas a partir de MySQL.

Instalação em Sistemas Windows

PHP 4

A extensão do PHP MySQL é compilada no PHP.

PHP 5+

O MySQL não é mais ativado por padrão, assim a DLL php_mysql.dll deve ser ativada dentro do php.ini. Também, o PHP precisa acessar a biblioteca de cliente do MySQL. Um arquivo chamado libmysql.dll é incluso na distribuição PHP do Windows e para permitir que o PHP converse com o MySQL este arquivo precisa estar disponível para o sistema Windows na variavél de ambiênte PATH. Veja o Faq entitulado "Como eu adiciono o meu diretório PHP no PATh no Windows" para informação de como fazer isto. Mesmo que copiar libmysql.dll para o diretório de sistema do Windows também (porque o diretório de sistema esta por padrão no PATH do sistema), isto não é recomendado.

Do mesmo jeito que ativar qualquer extensão do PHP (como php_mysql.dll), a diretiva do PHP extension_dir deve estar definida para o diretório aonde as extensões do PHP estão localizadas. Veja também Instruções de instalação Manual no Windows. Como um exemplo de valor para extension_dir para o PHP 5 é c:\php\ext

Nota: Se ao iniciar o servidor web acontecer um erro similar a este: "Unable to load dynamic library './php_mysql.dll'", isto é porque php_mysql.dll e/ou libmysql.dll não pode ser encontrada pelo sistema.

Notas de Instalação do MySQL

Atenção

Quebras e problemas de inicilização do PHP podem ser encontrados ao carregar esta extensão em conjunto com a extensão recode. Veja a extensão recode para maiores informações.

Nota: Se você precisar de conjuntos de caracteres diferntes de latin (padrão), você terá que instalar um libmysql externa (não embutida) com o suporte ao conjunto de caracteres compilado.

Configurações em execução

O comportamento dessas funções podem ser modificado pelas configurações do php.ini.

Tabela 1. Opções de configuração do MySQL

NomePadrãoModificávelModificações 
mysql.allow_persistent"On"PHP_INI_SYSTEM  
mysql.max_persistent"-1"PHP_INI_SYSTEM  
mysql.max_links"-1"PHP_INI_SYSTEM  
mysql.default_portNULLPHP_INI_ALL  
mysql.trace_mode"0"PHP_INI_ALLDisponível desde o PHP 4.3.0. 
mysql.default_socketNULLPHP_INI_ALL  
mysql.default_hostNULLPHP_INI_ALLDisponível desde o PHP 4.0.1. 
mysql.default_userNULLPHP_INI_ALL  
mysql.default_passwordNULLPHP_INI_ALL  
mysql.connect_timeout"60"PHP_INI_ALLPHP_INI_SYSTEM in PHP <= 4.3.2. Available since PHP 4.3.0. 
Para mais detalhes e definições das constantes PHP_INI_*, veja a documentação de ini_set().

Breve descrição das diretivas de configuração.

mysql.allow_persistent boolean

Quando permitir conexões persistentes para o MySQL.

mysql.max_persistent integer

O número máximo de conexões persistentes com o MySQL por processo.

mysql.max_links integer

O número maximo de conexões com o MYSQL por processo, incluindo conexões persistentes.

mysql.trace_mode boolean

Trace mode. Quando mysql.trace_mode esta ativado, avisos para procuras table/index scans, conjuntos de resultados não liberados, e erros de SQL serão exibidos. (Introduzido no PHP 4.3.0)

mysql.default_port string

O número padrão da porta TCP a usar quando conectar com o servidor do banco de dados se nenhuma outra porta for especificada. Se nenhum padrão for especificado, aporta será obtida da variavel de ambiente MYSQL_TCP_PORT, da entrada mysql-tcp em /etc/services ou da constante da compilação MYSQL_PORT, nesta ordem. Windows irá usar somente a constante MYSQL_PORT.

mysql.default_socket string

O nome padrão do socket para usar quando conectar com um servidor de banco de dados local se outro nome de socket não for especificado.

mysql.default_host string

O servidor padrão para usar quando conectar com um servidor de banco de dados se outro servidor não for encontrado. Não se aplica em SQL safe mode.

mysql.default_user string

O nome padrão de usuário para conectar ao servidor de banco de dados se outro nome não for especificado. Não se aplica em SQL safe mode.

mysql.default_password string

A senha padrão para usar ao conectar ao servidor de banco de dados se outra senha não for especificada. Não se aplica em SQL safe mode.

mysql.connect_timeout integer

Limite de tempo da conexão em segundos. No Linux este limite é também usado para a espera da primeira resposta do servidor.

Tipos Resource

Existem dois tipos de recursos usados no módulo MySQL. O primeiro é o identificador de conexão com o banco de dados, e o segundo é o recurso o qual guarda o resultado de uma consulta.

Constantes pré-definidas

As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.

Desde PHP 4.3.0 é possivel especificar opções adicionais para as funções mysql_connect() and mysql_pconnect() As seguintes constantes são definidas:

Tabela 2. Constante do cliente MySQL

ConstanteDescrição
MYSQL_CLIENT_COMPRESSUsa o protocolo de compressão
MYSQL_CLIENT_IGNORE_SPACEPermite espaço após o nome de função
MYSQL_CLIENT_INTERACTIVEPermite interactive_timeout segundos (ao inves de wait_timeout) de inatividade antes de fechar a conexão.
MYSQL_CLIENT_SSLUsar encriptação SSL. Esta opção esta disponível apenas com a versão 4.x da biblioteca de cliente MySQL ou mais nova. A versão 3.23.x é distribuida com o PHP 4 e com os binários Windows do PHP 5.

A função mysql_fetch_array() usa uma constante para cada diferentes tipos de matrizes de resultado. As seguintes constantes são definidas:

Tabela 3. MySQL fetch constants

ConstanteDescrição
MYSQL_ASSOC As colunas são retornadas na matriz tendo o nome do campo como índice da matriz.
MYSQL_BOTH As colunas são retornadas na matriz tendo ambos os indices: um numérico e o um com o nome do campo.
MYSQL_NUM As colunas são retornadas numa matriz tendo um indice numérico dos campos. Este indice começa com 0, o primeiro campo no resultado.

Notas

Nota: A maioria das funções MySQL aceitam link_identifier como o último parâmetro opcional. Se este não for dados, a última conexão aberta é usada. Se não existir, é tentado estabelecer uma conexão com os valores padrão definidos no php.ini. Se não for possível, a função retornará FALSE.

Exemplos

Este exemplo simples mostra como conectar, executar uma consulta, mostrar as linhas do resultado e disconectar do banco de dados MySQL.

Exemplo 1. Exemplo de visão geral da extensão MySQL

<?php
// Conectando, escolhendo o banco de dados
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
    or die(
'Não foi possível conectar: ' . mysql_error());
echo
'Conexão bem sucedida';
mysql_select_db('my_database') or die('Não foi possível selecionar o banco da dados');

// Executando a consulta SQL
$query = 'SELECT * FROM my_table';
$result = mysql_query($query) or die('A consulta falhou!: ' . mysql_error());

// Exibindo os resultados em 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";

// Liberar o conjunto de resultados
mysql_free_result($result);

// Fechar a conexão
mysql_close($link);
?>

Índice
mysql_affected_rows -- Obtém o número de linhas atingidas na operação anterior do MySQL
mysql_change_user -- Muda o usuário da conexão ativa
mysql_client_encoding -- Retorna o nome do conjunto de caracteres
mysql_close -- Fecha a conexão MySQL
mysql_connect -- Abre uma conexão com um servidor MySQL
mysql_create_db -- Cria um banco de dados MySQL
mysql_data_seek -- Move o ponteiro interno do resultado
mysql_db_name -- Obtém dados do resultado(nome de banco de dados)
mysql_db_query -- Envia uma consulta MySQL
mysql_drop_db -- Exclui um banco de dados MySQL
mysql_errno -- Retorna o valor numérico da mensagem de erro da operação MySQL anterior
mysql_error -- Retorna o texto da mensagem de erro da operação MySQL anterior
mysql_escape_string -- Escapa uma string para usar em uma consulta MySQL
mysql_fetch_array -- Obtém uma linha como uma matriz associativa, uma matriz numérica, ou ambas
mysql_fetch_assoc -- Obtém um linha do resultado como uma matriz associativa
mysql_fetch_field --  Retorna informação sobre uma coluna de um resultado como um objeto
mysql_fetch_lengths --  Retorna o tamanho de cada campo do resultado
mysql_fetch_object -- Retorna o resultado de uma linha como um objeto
mysql_fetch_row -- Retorna o resultado de uma linha numa matriz numérica
mysql_field_flags --  Pega as flags do campo especificado no resultado
mysql_field_len --  Retorna o tamanho do campo
mysql_field_name --  Retorna o nome do campo especificado no resultado de uma query
mysql_field_seek --  Move o ponteiro do resultado para um campo especificado
mysql_field_table --  Retorna o nome da tabela onde esta o campo especificado
mysql_field_type --  Retorna o tipo do campo especificado em um resultado de query
mysql_free_result -- Libera a memória do resultado de uma query
mysql_get_client_info -- Retorna informação da versão do cliente MySQL
mysql_get_host_info -- Retorna informação sobre o host do MySQL
mysql_get_proto_info -- Retorna informação do protocolo do MySQL
mysql_get_server_info -- Retorna informação do servidor MySQL
mysql_info --  Retorna informação sobre a última query
mysql_insert_id --  Retorna o ID gerado da operação INSERT anterior
mysql_list_dbs --  Lista os bancos de dados disponiveis o servidor do MySQL
mysql_list_fields -- Lista os campos de uma tabela
mysql_list_processes -- Lista os processos MySQL
mysql_list_tables -- Lista as tabelas em um banco de dados MySQL
mysql_num_fields -- Retorna o número de campos no resulatdo
mysql_num_rows -- Retorna o número de linhas em um resultado
mysql_pconnect --  Abre uma conexão persistente com um servidor MySQL
mysql_ping -- Pinga uma conexão ou reconecta se não houver conexão
mysql_query -- Realiza uma query MySQL
mysql_real_escape_string --  Escapa os caracteres especiais numa string para usar em um comando SQL, levando em conta o conjunto atual de caracteres.
mysql_result -- Retorna dados do resultado
mysql_select_db -- Seleciona um banco de dados MySQL
mysql_stat -- Retorna o status atual do sistema
mysql_tablename -- Retorna o nome da tabela do campo
mysql_thread_id -- Returna o ID da thread atual
mysql_unbuffered_query --  Envia uma query para o MySQL, sem retornar e colocar em buffer as linhas do resultado